# Approach B: aPaaS Native Chart Components - Complete Implementation Guide
**TikTok Analytics Dashboard using Feishu aPaaS Visual Components**
---
## Table of Contents
1. [Overview](#overview)
2. [What You'll Build](#what-youll-build)
3. [Prerequisites](#prerequisites)
4. [Quick Start](#quick-start)
5. [Step-by-Step Setup](#step-by-step-setup)
6. [Configuration Files Reference](#configuration-files-reference)
7. [Testing & Validation](#testing--validation)
8. [Troubleshooting](#troubleshooting)
9. [Next Steps](#next-steps)
---
## Overview
**Approach B** leverages Feishu/Lark aPaaS platform's native chart components to create an interactive TikTok analytics dashboard **without writing any code**. All configuration is done through visual editors and JSON configuration files.
### Key Features
- **No-code/Low-code**: Build dashboards using visual components
- **Native Integration**: Direct connection to Bitable data source
- **Real-time Updates**: Data refreshes automatically
- **Interactive**: Built-in filtering, sorting, and drill-down
- **Production-Ready**: Enterprise-grade performance and security
### Technology Stack
- **Data Storage**: Feishu Bitable (spreadsheet/database hybrid)
- **Platform**: Feishu aPaaS (low-code application builder)
- **Components**: Native chart components (metric cards, line charts, bar charts, pie charts, tables)
- **API**: Feishu Open API for data access
- **Authentication**: Tenant access token or Personal Base Token
---
## What You'll Build
### Dashboard Layout
```
┌─────────────────────────────────────────────────────────────────┐
│ Date Range Filter: [Last 30 Days ▼] │
├────────────┬────────────┬────────────┬──────────────────────────┤
│ 👁️ Total │ ❤️ Total │ 📊 Avg │ 👥 Total │
│ Views │ Likes │ Engage │ Followers │
│ 1.5M │ 180K │ 15.2% │ 26.4K │
│ +12.5% │ +8.7% │ +3.2% │ +1.2K │
├────────────┴────────────┴────────────┴──────────────────────────┤
│ │
│ Views & Engagement Trend Over Time │
│ [Line Chart: Views (primary) + Engagement Rate (secondary)] │
│ │
├──────────────────────────────┬───────────────────────────────────┤
│ │ │
│ Engagement Breakdown │ Total Engagement Distribution │
│ [Stacked Bar Chart] │ [Donut Chart] │
│ Likes/Comments/Shares │ Likes 60% / Comments 25% / │
│ │ Shares 15% │
├──────────────────────────────┴───────────────────────────────────┤
│ │
│ Detailed Video Performance Table │
│ [Sortable, filterable, paginated table with all metrics] │
│ │
└──────────────────────────────────────────────────────────────────┘
```
### Components Included
1. **4 Metric Cards**
- Total Views (with trend indicator)
- Total Likes (with trend indicator)
- Average Engagement Rate (with conditional formatting)
- Total Followers (with growth indicator)
2. **1 Line Chart**
- Dual Y-axis: Views (left) + Engagement Rate (right)
- Time-series visualization
- Interactive tooltips
- Data zoom capability
3. **1 Stacked Bar Chart**
- Engagement breakdown by type
- Likes, Comments, Shares stacked
- Last 30 days of data
- Click-to-detail functionality
4. **1 Donut Chart**
- Total engagement distribution
- Percentage breakdown
- Interactive legend
- Center total display
5. **1 Data Table**
- All video performance metrics
- Sortable columns
- Filterable data
- Pagination
- Export capability (CSV/Excel)
---
## Prerequisites
### Required Access
✅ **Feishu/Lark Account**
- Access to your organization's Feishu workspace
- Permissions to access Bitable and aPaaS
✅ **Bitable Access**
- Read access to the TikTok data table
- Base app_token: `C8kmbTsqoa6rBesTKRpl8nV8gHd`
- Table ID: `tblG4uuUvbwfvI9Z`
✅ **aPaaS Access**
- Edit permissions for aPaaS application
- App ID: `Dffwb10dwaz6UZs6c4HlWyV3g7c`
- Page ID: `pgeEOroex4nCBQxc`
✅ **API Credentials** (Choose one)
- **Option A**: App ID + App Secret (recommended for production)
- **Option B**: Personal Base Token (quick setup for testing)
### System Requirements
- Modern web browser (Chrome, Firefox, Safari, Edge)
- Internet connection
- Access to Feishu Open Platform: https://open.feishu.cn
- Access to aPaaS Console: https://apaas.feishu.cn
---
## Quick Start
### 5-Minute Setup
For experienced users who want to get started immediately:
```bash
# 1. Clone or navigate to the project directory
cd /Users/mdch/hype-dash
# 2. Set up environment variables
cp .env.example .env
# Edit .env and add your APP_ID and APP_SECRET
# 3. Validate your setup
node scripts/validate-apaas-setup.js
# 4. If validation passes, proceed to aPaaS console
# Open: https://apaas.feishu.cn
# Navigate to App: Dffwb10dwaz6UZs6c4HlWyV3g7c
# Open Page: pgeEOroex4nCBQxc
# 5. Import configurations (see Step-by-Step Setup for details)
```
### What's Included
All configuration files are ready to use in `/config/apaas-charts/`:
```
config/
├── apaas-data-request.json # Data source configuration
├── FIELD_MAPPING.md # Field mapping reference
├── INTEGRATION_GUIDE.md # Detailed integration guide
└── apaas-charts/
├── 01-metric-card-total-views.json
├── 02-metric-card-total-likes.json
├── 03-metric-card-avg-engagement.json
├── 04-metric-card-total-followers.json
├── 05-line-chart-views-engagement.json
├── 06-bar-chart-engagement-breakdown.json
├── 07-pie-chart-engagement-distribution.json
└── 08-table-video-performance.json
```
---
## Step-by-Step Setup
### Phase 1: Preparation (15 minutes)
#### Step 1.1: Get API Credentials
**Option A: Tenant Access Token (Recommended)**
1. Go to Feishu Open Platform: https://open.feishu.cn
2. Navigate to "My Apps" or create a new app
3. Copy your App ID and App Secret:
```
App ID: cli_xxxxxxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxx
```
4. Save these credentials securely
**Option B: Personal Base Token**
1. Go to your Bitable base
2. Click Settings → Advanced Settings
3. Generate a Personal Base Token
4. Copy the token:
```
Token: pat_xxxxxxxxxxxxxxxxxxxxxxxx
```
#### Step 1.2: Configure Environment Variables
1. Navigate to project directory:
```bash
cd /Users/mdch/hype-dash
```
2. Create `.env` file:
```bash
cp .env.example .env
```
3. Edit `.env` and add credentials:
```
# For Tenant Access Token
APP_ID=cli_xxxxxxxxxxxxxxxx
APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
# OR for Personal Base Token
# PERSONAL_BASE_TOKEN=pat_xxxxxxxxxxxxxxxxxxxxxxxx
# Optional
ENVIRONMENT=production
```
#### Step 1.3: Validate Setup
Run the validation script:
```bash
node scripts/validate-apaas-setup.js
```
Expected output:
```
╔════════════════════════════════════════════════════════════╗
║ aPaaS Configuration Validation Script ║
║ TikTok Analytics Dashboard Setup ║
╚════════════════════════════════════════════════════════════╝
[PASS] ✓ Found APP_ID and APP_SECRET
[PASS] ✓ Successfully obtained tenant access token
[PASS] ✓ Successfully accessed Bitable table
[PASS] ✓ All required fields present
[PASS] ✓ Valid configuration files
Validation Summary:
Passed: 12
Failed: 0
Warnings: 0
✓ All tests passed! Your aPaaS setup is ready.
```
If validation fails, see [Troubleshooting](#troubleshooting) section.
---
### Phase 2: aPaaS Data Source Setup (10 minutes)
#### Step 2.1: Open aPaaS Console
1. Navigate to: https://apaas.feishu.cn
2. Login with your Feishu account
3. Find your application:
- App ID: `Dffwb10dwaz6UZs6c4HlWyV3g7c`
- Or search by app name
4. Click to open the app
#### Step 2.2: Open Target Page
1. In left sidebar, click "Pages" (页面)
2. Find page with ID: `pgeEOroex4nCBQxc`
3. Click to open page editor
#### Step 2.3: Create Data Request
1. **Open Data Sources Panel**:
- Look for "Data" or "数据源" tab (usually in right panel)
- Click "Data Requests" or "数据请求"
2. **Add New Data Request**:
- Click "+ Add" or "+ 添加"
- Name: `getTikTokData`
- Description: "Fetch TikTok analytics from Bitable"
3. **Import Configuration**:
- Open file: `/Users/mdch/hype-dash/config/apaas-data-request.json`
- Copy the entire `dataRequest` section
- Paste into aPaaS configuration editor
- **OR** fill in manually:
```json
{
"method": "POST",
"url": "https://open.feishu.cn/open-apis/bitable/v1/apps/C8kmbTsqoa6rBesTKRpl8nV8gHd/tables/tblG4uuUvbwfvI9Z/records/search",
"headers": {
"Authorization": "Bearer {{tenant_access_token}}",
"Content-Type": "application/json"
},
"body": {
"field_names": [
"Date",
"Views",
"Likes",
"Comments",
"Shares",
"Followers",
"Engagement_Rate"
],
"page_size": 500,
"sort": [
{
"field_name": "Date",
"desc": false
}
]
}
}
```
#### Step 2.4: Configure Authentication
**For Tenant Access Token**:
1. In Data Request settings, find "Authentication" tab
2. Select "Custom Token" or "OAuth 2.0"
3. Configure:
```
Token Endpoint: https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
Method: POST
Body:
{
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET"
}
Token Path: tenant_access_token
Expires In: 7200
```
**For Personal Base Token**:
1. Simply set header:
```json
{
"Authorization": "Bearer YOUR_PERSONAL_BASE_TOKEN",
"Content-Type": "application/json"
}
```
#### Step 2.5: Test Connection
1. Click "Test" button in Data Request panel
2. Wait for response (2-5 seconds)
3. Verify success:
- ✅ Status: 200 OK
- ✅ Response contains `data.items` array
- ✅ At least 1 record returned
4. Save the Data Request
---
### Phase 3: Add Chart Components (30 minutes)
#### Step 3.1: Add Metric Cards (Row 1)
**Card 1: Total Views**
1. **Add Component**:
- In page editor, click "Add Component" or drag from component library
- Search for "Metric Card" or "指标卡片"
- Drag to top-left position
2. **Configure**:
- Open configuration file: `/Users/mdch/hype-dash/config/apaas-charts/01-metric-card-total-views.json`
- In aPaaS, click on the metric card
- Go to "Properties" or "属性" panel
- Copy settings from JSON:
```
Title: Total Views
Icon: 👁️ (or select eye icon from icon library)
Color: #3370FF
```
3. **Bind Data**:
- In "Data Binding" section:
- Data Source: `getTikTokData`
- Value Expression:
```javascript
{{getTikTokData.data.items.reduce((sum, item) => sum + (item.fields.Views || 0), 0)}}
```
- Number Format: Compact, 1 decimal
**Repeat for Cards 2-4**:
Follow same process for:
- **Card 2**: Total Likes (use `02-metric-card-total-likes.json`)
- **Card 3**: Avg Engagement Rate (use `03-metric-card-avg-engagement.json`)
- **Card 4**: Total Followers (use `04-metric-card-total-followers.json`)
**Layout**:
- Arrange all 4 cards in a single row
- Equal width (25% each)
- Height: ~120px
---
#### Step 3.2: Add Line Chart (Row 2)
1. **Add Component**:
- Drag "Line Chart" or "折线图" component
- Position below metric cards
- Resize to full width
2. **Configure Using JSON**:
- Open: `/Users/mdch/hype-dash/config/apaas-charts/05-line-chart-views-engagement.json`
- Apply settings:
**Basic Settings**:
```
Title: Views & Engagement Trend
Data Source: getTikTokData
```
**X-Axis**:
```
Field: Date
Type: Time
Data Expression: {{getTikTokData.data.items.map(i => new Date(i.fields.Date))}}
Format: MMM DD
```
**Y-Axis (Primary - Left)**:
```
Label: Views
Position: Left
Data Expression: {{getTikTokData.data.items.map(i => i.fields.Views)}}
Format: 0,0
```
**Y-Axis (Secondary - Right)**:
```
Label: Engagement Rate (%)
Position: Right
Data Expression: {{getTikTokData.data.items.map(i => i.fields.Engagement_Rate)}}
Format: 0.0
```
**Series 1 (Views)**:
```
Name: Daily Views
Type: Line
Color: #3370FF
Y-Axis: Primary (left)
Smooth: true
Show Symbol: true
```
**Series 2 (Engagement)**:
```
Name: Engagement Rate
Type: Line
Color: #00C48C
Y-Axis: Secondary (right)
Smooth: true
Line Style: Dashed
```
3. **Configure Display Options**:
```
Legend: Show, Top position
Tooltip: Enabled, Axis trigger
Grid: 10% margins all sides
Animation: Enabled, 1000ms
```
---
#### Step 3.3: Add Bar Chart (Row 3, Left)
1. **Add Component**:
- Drag "Bar Chart" or "柱状图"
- Position in row 3, left side (50% width)
2. **Configure Using JSON**:
- Open: `/Users/mdch/hype-dash/config/apaas-charts/06-bar-chart-engagement-breakdown.json`
**Basic Settings**:
```
Title: Engagement Breakdown
Orientation: Vertical
Data Source: getTikTokData
```
**X-Axis**:
```
Field: Date
Type: Category
Data: {{getTikTokData.data.items.slice(0, 30).map(i => new Date(i.fields.Date).toLocaleDateString())}}
```
**Series (Stacked)**:
```
Series 1 - Likes:
Color: #FF3B69
Stack: engagement
Data: {{getTikTokData.data.items.slice(0, 30).map(i => i.fields.Likes)}}
Series 2 - Comments:
Color: #3370FF
Stack: engagement
Data: {{getTikTokData.data.items.slice(0, 30).map(i => i.fields.Comments)}}
Series 3 - Shares:
Color: #00C48C
Stack: engagement
Data: {{getTikTokData.data.items.slice(0, 30).map(i => i.fields.Shares)}}
```
---
#### Step 3.4: Add Pie Chart (Row 3, Right)
1. **Add Component**:
- Drag "Pie Chart" or "饼图"
- Position in row 3, right side (50% width)
2. **Configure Using JSON**:
- Open: `/Users/mdch/hype-dash/config/apaas-charts/07-pie-chart-engagement-distribution.json`
**Basic Settings**:
```
Title: Total Engagement Distribution
Type: Donut
Radius: 50% - 75%
```
**Data (3 Segments)**:
```javascript
[
{
name: "Likes",
value: {{getTikTokData.data.items.reduce((sum, i) => sum + (i.fields.Likes || 0), 0)}},
color: "#FF3B69"
},
{
name: "Comments",
value: {{getTikTokData.data.items.reduce((sum, i) => sum + (i.fields.Comments || 0), 0)}},
color: "#3370FF"
},
{
name: "Shares",
value: {{getTikTokData.data.items.reduce((sum, i) => sum + (i.fields.Shares || 0), 0)}},
color: "#00C48C"
}
]
```
**Display**:
```
Show Labels: Yes
Label Format: {b}: {d}%
Legend: Right, Vertical
```
---
#### Step 3.5: Add Data Table (Row 4)
1. **Add Component**:
- Drag "Table" or "表格" component
- Position in row 4, full width
2. **Configure Using JSON**:
- Open: `/Users/mdch/hype-dash/config/apaas-charts/08-table-video-performance.json`
**Data Source**:
```
Data Source: getTikTokData
Data Path: data.items
```
**Columns** (in order):
```
1. Date (fields.Date) - Format: YYYY-MM-DD - Width: 120px
2. Views (fields.Views) - Format: 0,0 - Width: 110px
3. Likes (fields.Likes) - Format: 0,0 - Width: 100px
4. Comments (fields.Comments) - Format: 0,0 - Width: 110px
5. Shares (fields.Shares) - Format: 0,0 - Width: 100px
6. Followers (fields.Followers) - Format: 0,0 - Width: 110px
7. Engagement_Rate (fields.Engagement_Rate) - Format: 0.00% - Width: 140px
```
**Table Options**:
```
✅ Enable Sorting (all columns)
✅ Enable Filtering
✅ Enable Search
✅ Enable Pagination (20 rows per page)
✅ Show Row Numbers
✅ Freeze Header
Default Sort: Date, Descending
```
---
### Phase 4: Add Interactivity (15 minutes)
#### Step 4.1: Add Date Range Filter
1. **Add Component**:
- Drag "Date Range Picker" to top of page
- Position above metric cards
2. **Configure**:
```
Name: dateRangeFilter
Type: Date Range
Default Value:
- Start: {{today(-30)}} (30 days ago)
- End: {{today()}} (today)
Format: YYYY-MM-DD
```
#### Step 4.2: Connect Filter to Data Request
1. **Edit Data Request**: `getTikTokData`
2. **Add Parameter**:
```json
{
"name": "dateRange",
"type": "object",
"source": "{{dateRangeFilter.value}}",
"mapping": {
"target": "body.filter.conditions",
"value": [
{
"field_name": "Date",
"operator": "isGreaterEqual",
"value": ["{{dateRange.start}}"]
},
{
"field_name": "Date",
"operator": "isLessEqual",
"value": ["{{dateRange.end}}"]
}
]
}
}
```
3. **Add Event Trigger**:
```
When: dateRangeFilter changes
Action: Refresh getTikTokData
Debounce: 500ms
```
#### Step 4.3: Add Chart Click Events (Optional)
**Bar Chart Click**:
```
Event: onClick
Action: Show Modal
Modal: Engagement Details
Pass Data:
- Date: {{clickedBar.date}}
- Likes: {{clickedBar.likes}}
- Comments: {{clickedBar.comments}}
- Shares: {{clickedBar.shares}}
```
**Metric Card Click**:
```
Event: onClick
Action: Filter Charts
Target: Line Chart
Filter: Highlight corresponding series
```
---
### Phase 5: Polish & Optimize (10 minutes)
#### Step 5.1: Configure Loading States
For each component:
1. Enable loading skeleton
2. Set loading message
3. Configure empty state message
#### Step 5.2: Enable Caching
Edit Data Request `getTikTokData`:
```json
{
"cache": {
"enabled": true,
"ttl": 300,
"key": "tiktok_data_{{dateRange.start}}_{{dateRange.end}}"
}
}
```
#### Step 5.3: Add Error Handling
For each component:
```json
{
"error": {
"showMessage": true,
"fallbackValue": "N/A",
"message": "Unable to load data. Please try again."
}
}
```
#### Step 5.4: Responsive Layout
Test on different screen sizes:
- Desktop: Full layout
- Tablet: Stack bar/pie charts vertically
- Mobile: Single column layout
---
## Configuration Files Reference
### File Structure
```
/Users/mdch/hype-dash/
├── config/
│ ├── apaas-data-request.json # Main data source config
│ ├── FIELD_MAPPING.md # Field reference guide
│ ├── INTEGRATION_GUIDE.md # Detailed integration guide
│ ├── QUICK_START.md # Quick start guide
│ └── apaas-charts/
│ ├── 01-metric-card-total-views.json
│ ├── 02-metric-card-total-likes.json
│ ├── 03-metric-card-avg-engagement.json
│ ├── 04-metric-card-total-followers.json
│ ├── 05-line-chart-views-engagement.json
│ ├── 06-bar-chart-engagement-breakdown.json
│ ├── 07-pie-chart-engagement-distribution.json
│ └── 08-table-video-performance.json
├── scripts/
│ └── validate-apaas-setup.js # Validation script
├── APAAS_CHART_CONFIG.md # Chart configuration guide
└── APPROACH_B_COMPLETE.md # This file
```
### Quick Reference
| File | Purpose | Usage |
|------|---------|-------|
| `apaas-data-request.json` | Data source connection | Import to aPaaS Data Request |
| `FIELD_MAPPING.md` | Field reference | Consult when writing expressions |
| `01-04-metric-card-*.json` | Metric card configs | Copy settings to metric card components |
| `05-line-chart-*.json` | Line chart config | Copy settings to line chart |
| `06-bar-chart-*.json` | Bar chart config | Copy settings to bar chart |
| `07-pie-chart-*.json` | Pie chart config | Copy settings to pie chart |
| `08-table-*.json` | Table config | Copy settings to table component |
| `validate-apaas-setup.js` | Setup validation | Run before starting |
---
## Testing & Validation
### Pre-Deployment Checklist
Before publishing your dashboard, verify:
#### Data Connection
- [ ] Data request returns 200 OK
- [ ] All required fields present in response
- [ ] Data loads in less than 5 seconds
- [ ] Authentication token refreshes automatically
#### Components
- [ ] All 4 metric cards display values
- [ ] Line chart renders with both series
- [ ] Bar chart shows stacked bars
- [ ] Pie chart displays all segments
- [ ] Table shows data with pagination
#### Interactivity
- [ ] Date range filter updates all components
- [ ] Charts refresh when filter changes
- [ ] Click events work (if configured)
- [ ] Tooltips display on hover
#### Display
- [ ] Numbers formatted correctly (1.5K, not 1523)
- [ ] Dates show as readable strings (not timestamps)
- [ ] Percentages show with % symbol
- [ ] Colors match design specifications
#### Performance
- [ ] Page loads in less than 3 seconds
- [ ] No console errors
- [ ] Data caching enabled
- [ ] Loading states show during data fetch
#### Responsive
- [ ] Desktop view: All components visible
- [ ] Tablet view: Layout adapts
- [ ] Mobile view: Single column, readable
### Validation Script
Run automated validation:
```bash
node scripts/validate-apaas-setup.js
```
Expected output:
```
✓ All tests passed! Your aPaaS setup is ready.
Passed: 12
Failed: 0
Warnings: 0
```
### Manual Testing Steps
1. **Test Data Loading**:
- Preview page in aPaaS
- Check all components load
- Verify no "undefined" or "NaN" values
2. **Test Filtering**:
- Change date range
- Verify all components update
- Check that data matches filter
3. **Test Edge Cases**:
- Select date range with no data
- Verify empty state messages
- Test with maximum date range (all data)
- Check performance with large dataset
4. **Test on Different Browsers**:
- Chrome
- Firefox
- Safari
- Edge
5. **Test on Different Devices**:
- Desktop (1920x1080)
- Tablet (768x1024)
- Mobile (375x667)
---
## Troubleshooting
### Common Issues & Solutions
#### Issue 1: "401 Unauthorized" Error
**Symptoms**:
- Data request fails with 401 status
- Components show "Unable to load data"
**Causes**:
- Invalid App ID or App Secret
- Expired token
- Token not refreshed
**Solutions**:
1. Verify credentials in `.env` file:
```bash
cat .env
```
2. Test authentication separately:
```bash
node scripts/validate-apaas-setup.js
```
3. Check token refresh configuration in Data Request
4. Ensure app has required scopes:
- `bitable:app`
- `bitable:app:readonly`
---
#### Issue 2: "403 Forbidden" Error
**Symptoms**:
- Can authenticate but cannot access Bitable
- Error message: "No permission"
**Causes**:
- Bitable not shared with app
- Missing required scopes
- App not published
**Solutions**:
1. Share Bitable with app:
- Open Bitable → Settings → Sharing
- Add app to authorized applications
- Grant "Read" permission
2. Verify app scopes:
- Go to https://open.feishu.cn/app
- Select your app
- Check "Permissions & Scopes"
- Ensure `bitable:app:readonly` is enabled
3. Publish app (if in development mode)
---
#### Issue 3: Charts Not Loading Data
**Symptoms**:
- Components render but show no data
- "No data available" message
**Causes**:
- Incorrect data binding expression
- Wrong field names (case-sensitive)
- Data path mismatch
**Solutions**:
1. Check data source name:
```javascript
// Make sure it matches exactly
getTikTokData (not getTiktokData or getTikTokdata)
```
2. Verify field names:
```javascript
// Fields are case-sensitive
item.fields.Views ✓ correct
item.fields.views ✗ wrong
```
3. Test expression in browser console:
```javascript
getTikTokData.data.items.map(i => i.fields.Views)
```
4. Check data path:
```javascript
// Make sure path is correct
getTikTokData.data.items ✓ correct
getTikTokData.items ✗ wrong
getTikTokData.data.records ✗ wrong
```
---
#### Issue 4: Date Shows as Timestamp
**Symptoms**:
- Charts show numbers like 1698768000000 instead of dates
- Table shows timestamp in date column
**Cause**:
- Missing date transformation
**Solution**:
Convert timestamp to Date object:
```javascript
// Before (wrong)
{{item.fields.Date}}
// After (correct)
{{new Date(item.fields.Date)}}
// Or format as string
{{new Date(item.fields.Date).toLocaleDateString()}}
```
---
#### Issue 5: "NaN" Displayed in Metrics
**Symptoms**:
- Metric cards show "NaN"
- Calculations return NaN
**Causes**:
- Division by zero
- Null/undefined values in calculation
- Non-numeric field
**Solutions**:
1. Add null checks:
```javascript
// Before
total / count
// After
count > 0 ? total / count : 0
```
2. Provide default values:
```javascript
item.fields.Views || 0
```
3. Validate data types:
```javascript
Number(item.fields.Views) || 0
```
---
#### Issue 6: Slow Performance
**Symptoms**:
- Page takes > 5 seconds to load
- Components lag when interacting
**Causes**:
- Large dataset (> 1000 records)
- No caching enabled
- Complex calculations
- Too many API calls
**Solutions**:
1. Enable caching:
```json
{
"cache": {
"enabled": true,
"ttl": 300
}
}
```
2. Limit data in charts:
```javascript
// Show only last 30 days
{{getTikTokData.data.items.slice(0, 30)}}
```
3. Add pagination to table:
```json
{
"pagination": {
"enabled": true,
"pageSize": 20
}
}
```
4. Optimize expressions:
```javascript
// Cache computed values
const items = getTikTokData.data.items;
const total = items.reduce(...);
```
---
#### Issue 7: Filter Not Working
**Symptoms**:
- Changing date range doesn't update charts
- Components don't refresh
**Causes**:
- Filter not connected to data request
- Missing event binding
- Wrong parameter mapping
**Solutions**:
1. Verify filter component ID:
```
Component ID: dateRangeFilter (must match exactly)
```
2. Check data request parameter:
```json
{
"source": "{{dateRangeFilter.value}}"
}
```
3. Ensure event trigger is configured:
```
Event: dateRangeFilter.onChange
Action: Refresh getTikTokData
```
4. Test filter independently:
- Change filter value
- Check browser network tab
- Verify API request is sent with filter params
---
### Getting Help
If you encounter issues not covered here:
1. **Check Documentation**:
- `/config/INTEGRATION_GUIDE.md`
- `/config/FIELD_MAPPING.md`
- `APAAS_CHART_CONFIG.md`
2. **Review Examples**:
- All configuration files in `/config/apaas-charts/`
- Compare your setup with examples
3. **Run Validation**:
```bash
node scripts/validate-apaas-setup.js
```
4. **Check Logs**:
- Browser console (F12)
- aPaaS error messages
- API response in Network tab
5. **Community Resources**:
- Feishu Developer Community: https://open.feishu.cn/community/
- aPaaS Documentation: https://apaas.feishu.cn/docs
- Bitable API Docs: https://open.feishu.cn/document/server-docs/docs/bitable-v1/
---
## Next Steps
### After Successful Setup
1. **Publish Dashboard**:
- Save all changes in aPaaS editor
- Click "Publish" button
- Select target environment (Test/Production)
- Confirm publication
2. **Share with Users**:
- Copy dashboard URL
- Set access permissions
- Send link to stakeholders
3. **Monitor Usage**:
- Track page views
- Monitor API usage
- Check error logs
### Enhancements
Consider these improvements:
1. **Additional Metrics**:
- Average watch time
- Completion rate
- Viral coefficient
- Growth rate
2. **Advanced Visualizations**:
- Heatmap calendar
- Scatter plot (views vs engagement)
- Funnel chart (engagement funnel)
- Gauge charts for targets
3. **Automation**:
- Scheduled reports
- Alert notifications
- Auto-refresh on data changes
4. **Export Features**:
- PDF report generation
- CSV/Excel downloads
- Email reports
### Related Approaches
Explore other implementation methods:
- **Approach A**: Custom code with SDK
- More flexibility
- Custom visualizations
- Programmatic control
- **Approach C**: VChart components
- Advanced charting library
- More chart types
- Custom themes
---
## Summary
### What You've Accomplished
✅ **Built a Production-Ready Dashboard**:
- 4 interactive metric cards
- 3 data visualization charts
- 1 comprehensive data table
- Real-time data from Bitable
- Interactive filtering
- Professional styling
✅ **No Code Required**:
- All configuration via JSON files
- Visual component assembly
- Copy-paste expressions
✅ **Enterprise-Grade**:
- Secure authentication
- Data caching
- Error handling
- Responsive design
- Performance optimized
### Key Files Created
1. **Chart Configurations** (8 files):
- `/config/apaas-charts/01-08-*.json`
2. **Data Source**:
- `/config/apaas-data-request.json`
3. **Documentation**:
- `/config/FIELD_MAPPING.md`
- `/config/INTEGRATION_GUIDE.md`
4. **Validation**:
- `/scripts/validate-apaas-setup.js`
5. **This Guide**:
- `APPROACH_B_COMPLETE.md`
### Estimated Time Investment
- **Initial Setup**: 15 minutes
- **Data Source Configuration**: 10 minutes
- **Chart Implementation**: 30 minutes
- **Interactivity**: 15 minutes
- **Testing**: 15 minutes
- **Total**: ~1.5 hours
### Success Criteria
Your implementation is successful if:
✅ All validation tests pass
✅ Dashboard loads in < 3 seconds
✅ All components display data correctly
✅ Filtering works smoothly
✅ No console errors
✅ Responsive on all devices
---
## Appendix
### A. Project Information
```yaml
Project: TikTok Analytics Dashboard
Approach: B - aPaaS Native Components
Platform: Feishu/Lark aPaaS
Data Source:
Base App Token: C8kmbTsqoa6rBesTKRpl8nV8gHd
Table ID: tblG4uuUvbwfvI9Z
Table Name: TikTok L'AURA - Candle
Records: 150 videos
aPaaS Application:
App ID: Dffwb10dwaz6UZs6c4HlWyV3g7c
Page ID: pgeEOroex4nCBQxc
Fields:
- Date (timestamp)
- Views (number)
- Likes (number)
- Comments (number)
- Shares (number)
- Followers (number)
- Engagement_Rate (percentage)
```
### B. Color Palette
```yaml
Primary Colors:
Blue (Views): #3370FF
Red (Likes): #FF3B69
Green (Engagement): #00C48C
Purple (Followers): #8A5CD1
Secondary Colors:
Orange (Comments): #FA8C16
Yellow (Warning): #FAAD14
UI Colors:
Background: #FFFFFF
Border: #D9D9D9
Text: #262626
Secondary Text: #8C8C8C
```
### C. Expression Cheat Sheet
```javascript
// Sum all values
{{items.reduce((sum, i) => sum + (i.fields.Views || 0), 0)}}
// Average
{{items.reduce((sum, i) => sum + (i.fields.Views || 0), 0) / items.length}}
// Maximum
{{Math.max(...items.map(i => i.fields.Views || 0))}}
// Minimum
{{Math.min(...items.map(i => i.fields.Views || 0))}}
// Count
{{items.length}}
// Filter and count
{{items.filter(i => i.fields.Views > 1000).length}}
// Format number
{{Intl.NumberFormat('en-US', {notation: 'compact'}).format(value)}}
// Format date
{{new Date(timestamp).toLocaleDateString()}}
// Format percentage
{{(value * 100).toFixed(2)}}%
```
---
**Document Version**: 1.0
**Last Updated**: 2025-12-09
**Maintained By**: Analytics Team
**Contact**: See project documentation for support
---
**Congratulations!** 🎉
You've successfully set up a production-ready TikTok analytics dashboard using Feishu aPaaS. Your dashboard is now ready to provide valuable insights into your social media performance.
For questions or feedback, refer to the documentation files in `/config/` or contact your team's aPaaS administrator.
Happy analyzing! 📊
