# TikTok Analytics Dashboard - Unified Guide
**Complete Reference for All Three Implementation Approaches**
Version: 1.0.0
Date: 2025-12-09
Project: Lark Dashboard SDK - TikTok Analytics
---
## Table of Contents
1. [Executive Summary](#executive-summary)
2. [Quick Start by Approach](#quick-start-by-approach)
3. [Decision Matrix](#decision-matrix)
4. [Common Configuration](#common-configuration)
5. [Approach A: Native Bitable Dashboard](#approach-a-native-bitable-dashboard)
6. [Approach B: aPaaS Native Chart Components](#approach-b-apaas-native-chart-components)
7. [Approach C: Custom VChart Component](#approach-c-custom-vchart-component)
8. [Feature Comparison](#feature-comparison)
9. [Migration Paths](#migration-paths)
10. [Troubleshooting Across Approaches](#troubleshooting-across-approaches)
11. [Best Practices](#best-practices)
12. [Resources](#resources)
---
## Executive Summary
This guide covers **three distinct approaches** to building TikTok Analytics Dashboards in the Lark/Feishu ecosystem, each with different trade-offs between ease of implementation, customization, and technical requirements.
### The Three Approaches
| Approach | Method | Complexity | Customization | Best For |
|----------|--------|------------|---------------|----------|
| **A** | Native Bitable Dashboard | Low | Medium | Quick setup, basic analytics |
| **B** | aPaaS Chart Components | Medium | High | Interactive apps, no-code |
| **C** | Custom VChart Component | High | Very High | Advanced visualizations, full control |
### Common Foundation
All three approaches share:
- **Data Source:** Bitable Table `tblG4uuUvbwfvI9Z` (150 TikTok videos)
- **Base:** `C8kmbTsqoa6rBesTKRpl8nV8gHd`
- **Field Schema:** 9 standard fields (Video ID, Views, Likes, etc.)
- **Authentication:** Lark API Key required
### Choose Your Path
**30 seconds to decide:**
```bash
# Want a dashboard in under 5 minutes?
→ Approach A (Copy existing dashboard)
# Building a no-code interactive app?
→ Approach B (aPaaS visual editor)
# Need full programmatic control?
→ Approach C (Custom VChart component)
```
---
## Quick Start by Approach
### Approach A: 5-Minute Dashboard
```bash
# 1. Set API key
export LARK_API_KEY="your-key"
# 2. Copy dashboard
npm run tiktok:copy
# 3. Done! Open the link provided
```
**Result:** Working dashboard with all charts
**Time:** 2-5 minutes
**Skill Level:** Beginner
---
### Approach B: 15-Minute Interactive App
```bash
# 1. Navigate to aPaaS
Open: https://apaas.feishu.cn/app/Dffwb10dwaz6UZs6c4HlWyV3g7c
# 2. Import data request
Copy: /config/apaas-data-request.json
# 3. Add 4 metric cards + 3 charts
Follow: /config/QUICK_START.md
# 4. Preview and publish
```
**Result:** Interactive app with filters
**Time:** 15-30 minutes
**Skill Level:** Intermediate (No coding)
---
### Approach C: 1-Hour Custom Component
```bash
# 1. Setup environment
./scripts/setup-vchart-component.sh
# 2. Build and deploy
npm run vchart:deploy
# 3. Upload to aPaaS
Follow deployment instructions
# 4. Add to page
<TikTokDashboard tableId="tblG4uuUvbwfvI9Z" />
```
**Result:** Custom component with full control
**Time:** 1-2 hours
**Skill Level:** Advanced (React/TypeScript)
---
## Decision Matrix
### Use Case → Recommended Approach
| Your Situation | Recommended Approach | Why |
|----------------|---------------------|-----|
| Need dashboard ASAP | **A** | Copy existing, modify later |
| Building internal tool | **B** | No-code, maintainable |
| Complex custom viz | **C** | Full programmatic control |
| Non-technical team | **A or B** | UI-based, no coding |
| Developer team | **C** | Code-based, version controlled |
| Frequent updates | **B** | Easy to modify in UI |
| Embedded in app | **C** | React component, flexible |
| Mobile-first | **B or C** | Better responsive support |
| Multiple data sources | **B or C** | Advanced data integration |
| One-time setup | **A** | Quickest path |
### Technical Requirements
| Requirement | A | B | C |
|-------------|---|---|---|
| Programming skills | None | None | React/TypeScript |
| Lark API access | Yes | Yes | Yes |
| aPaaS account | No | Yes | Yes |
| Build tools | No | No | Yes (npm, Node.js) |
| Hosting | Lark | Lark | Lark aPaaS |
| Version control | No | No | Yes (Git) |
### Feature Availability
| Feature | A | B | C |
|---------|---|---|---|
| KPI Cards | ✅ | ✅ | ✅ |
| Line Charts | ✅ | ✅ | ✅ |
| Bar Charts | ✅ | ✅ | ✅ |
| Pie Charts | ✅ | ✅ | ✅ |
| Data Tables | ✅ | ✅ | ⚠️ |
| Filters | ✅ | ✅ | ✅ |
| Auto-refresh | ✅ | ✅ | ✅ |
| Click events | Limited | ✅ | ✅ |
| Export charts | ✅ | ⚠️ | ✅ |
| Custom themes | Limited | ✅ | ✅ |
| API integration | No | ✅ | ✅ |
| Real-time updates | No | ✅ | ✅ |
Legend: ✅ Full Support | ⚠️ Partial Support | ❌ Not Supported
---
## Common Configuration
### Database Information
All approaches use the same data source:
```yaml
Bitable Base:
app_token: C8kmbTsqoa6rBesTKRpl8nV8gHd
table_id: tblG4uuUvbwfvI9Z
name: TikTok L'AURA - Candle
records: 150 videos
url: https://hypelive.sg.larksuite.com/base/C8kmbTsqoa6rBesTKRpl8nV8gHd
```
### Field Names (Standard Schema)
All approaches reference these exact field names:
| Purpose | Field Name (Exact Match) |
|---------|--------------------------|
| Video ID | `Unique identifier of the video` |
| Date Published | `Date and time the video was published` |
| Views | `Total video views` |
| Likes | `Total number of likes the video received` |
| Comments | `Total number of comments the video received` |
| Shares | `Total number of times the video was shared` |
| Watch Rate | `Percentage of video watched completely` |
| Description | `Video description` |
| Duration | `Duration of the video in seconds` |
**Important:** Field names are case-sensitive and must match exactly.
### API Endpoints
```bash
# Bitable Records (All Approaches)
POST https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/search
# Dashboard Operations (Approach A)
GET https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/dashboards
POST https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/dashboards
# Authentication (All Approaches)
POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
```
### Authentication Setup
All approaches require API authentication:
```bash
# Environment variables
export LARK_API_KEY="your-app-secret"
export LARK_REGION="sg" # or "us", "eu"
# Get tenant access token (approaches B & C)
curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
-H "Content-Type: application/json" \
-d '{
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET"
}'
```
### Color Palette (Consistent Across All Approaches)
```typescript
const TIKTOK_COLORS = {
primary: '#1890ff', // Blue - Views, primary metrics
secondary: '#ff4d4f', // Red - Likes, engagement
success: '#52c41a', // Green - Shares, positive
warning: '#fa8c16', // Orange - Comments
purple: '#722ed1', // Purple - Duration, special
info: '#13c2c2', // Cyan - Additional metrics
gradient: [
'#1890ff', // Blue
'#36cfc9', // Cyan
'#73d13d', // Lime
'#ffec3d', // Yellow
'#ff4d4f' // Red
]
};
```
### Standard Dashboard Components
All approaches implement these core components:
#### 1. KPI Cards (4 Total)
| Metric | Aggregation | Format | Icon |
|--------|-------------|--------|------|
| Total Views | SUM | 1.5M | 👁️ |
| Total Engagement | SUM | 125K | ❤️ |
| Total Videos | COUNT | 150 | 📹 |
| Avg Watch Rate | AVG | 75.5% | 📊 |
#### 2. Performance Trend (Line Chart)
- X-axis: Date published (time series)
- Y-axis: Views (primary), Engagement Rate (secondary)
- Shows trends over time
#### 3. Top Performers (Bar Chart)
- Horizontal bars
- Top 10 videos by views
- Sorted descending
#### 4. Engagement Breakdown (Pie Chart)
- Segments: Likes, Comments, Shares
- Donut style
- Shows distribution
#### 5. Data Quality View (Scatter/Table)
- Watch rate vs Views correlation
- Full sortable data table
---
## Approach A: Native Bitable Dashboard
### Overview
Use Lark Bitable's built-in dashboard functionality to create visualizations by copying and modifying existing dashboards.
### When to Use
- ✅ Need dashboard immediately (< 5 minutes)
- ✅ Non-technical users
- ✅ Simple analytics needs
- ✅ Working within Bitable already
- ❌ Need programmatic control
- ❌ Complex custom interactions
### Quick Start
```bash
# 1. Set environment
export LARK_API_KEY="your-key"
# 2. Analyze data (optional)
npm run tiktok:analyze
# 3. Copy dashboard
npm run tiktok:copy
# 4. Or create from scratch
npm run tiktok:create
```
### Files & Documentation
| File | Purpose | Lines |
|------|---------|-------|
| `TIKTOK_DASHBOARD_CONFIG.md` | Complete manual guide | 400 |
| `QUICK_START_TIKTOK.md` | Quick reference | 122 |
| `IMPLEMENTATION_SUMMARY.md` | Full details | 445 |
| `scripts/analyze-tiktok-data.ts` | Data analysis | 377 |
| `scripts/copy-tiktok-dashboard.ts` | Copy automation | 100 |
| `scripts/create-tiktok-dashboard.ts` | Create automation | 250 |
### npm Scripts
```json
{
"tiktok:analyze": "Analyze TikTok data, show insights",
"tiktok:analyze:export": "Analyze + export JSON",
"tiktok:copy": "Copy existing dashboard",
"tiktok:create": "Create new dashboard with blocks"
}
```
### Limitations
1. **Cannot create dashboards from scratch via API** - Must copy existing
2. **Limited programmatic customization** - Fine-tuning requires UI
3. **No advanced event handling** - Basic click interactions only
4. **Manual filter setup** - Filters configured in UI only
### Workflow
```
1. Manual: Create one empty dashboard in Bitable UI
↓
2. Automated: Run npm run tiktok:copy
↓
3. Manual: Customize in UI (colors, positions, filters)
↓
4. Manual: Share with team
```
### Pros
- ✅ Fastest setup (2-5 minutes)
- ✅ No coding required
- ✅ Native Lark integration
- ✅ Automatic mobile optimization
- ✅ Built-in sharing and permissions
### Cons
- ❌ Limited API control
- ❌ Requires manual UI work
- ❌ Less flexible
- ❌ Hard to version control
### Documentation Links
- Configuration Guide: `/TIKTOK_DASHBOARD_CONFIG.md`
- Quick Start: `/QUICK_START_TIKTOK.md`
- Implementation: `/IMPLEMENTATION_SUMMARY.md`
---
## Approach B: aPaaS Native Chart Components
### Overview
Build interactive applications using Feishu/Lark aPaaS platform's visual editor with native chart components connected to Bitable data.
### When to Use
- ✅ Building interactive applications
- ✅ Need custom workflows
- ✅ No-code/low-code preference
- ✅ Frequent UI changes
- ✅ Multiple data sources
- ❌ Need offline functionality
- ❌ Want version-controlled code
### Quick Start
```bash
# 1. Open aPaaS application
https://apaas.feishu.cn/app/Dffwb10dwaz6UZs6c4HlWyV3g7c
# 2. Import data request configuration
File: /config/apaas-data-request.json
# 3. Follow quick start guide
Guide: /config/QUICK_START.md
# 4. Add components via drag-and-drop
```
### Application Details
```yaml
aPaaS Application:
app_id: Dffwb10dwaz6UZs6c4HlWyV3g7c
page_id: pgeEOroex4nCBQxc
platform: https://apaas.feishu.cn
Data Source:
type: Bitable Connector
method: POST
endpoint: /bitable/v1/apps/{app_token}/tables/{table_id}/records/search
```
### Files & Documentation
| File | Purpose | Lines |
|------|---------|-------|
| `APAAS_CHART_CONFIG.md` | Complete reference | 975 |
| `APAAS_IMPLEMENTATION_SUMMARY.md` | Overview | 475 |
| `config/apaas-data-request.json` | Data connector config | 440 |
| `config/INTEGRATION_GUIDE.md` | Step-by-step | 1,110 |
| `config/QUICK_START.md` | 15-min setup | 246 |
| `config/README.md` | Config overview | 440 |
### Component Types
#### Metric Cards
```json
{
"component": "MetricCard",
"dataSource": "getTikTokData",
"value": "{{sum(data.views)}}",
"format": "compact"
}
```
#### Line Chart
```json
{
"component": "LineChart",
"xAxis": {"field": "Date", "type": "time"},
"yAxis": [
{"field": "Views", "position": "left"},
{"field": "Engagement_Rate", "position": "right"}
]
}
```
#### Bar Chart
```json
{
"component": "BarChart",
"orientation": "horizontal",
"series": [
{"field": "Likes", "color": "#ff4d4f"},
{"field": "Comments", "color": "#1890ff"},
{"field": "Shares", "color": "#52c41a"}
]
}
```
### Event Binding
```javascript
// Click event
{
"onClick": {
"action": "filter",
"target": "otherChart",
"expression": "{{item.date}}"
}
}
// Filter connection
{
"filters": [
{
"id": "dateRangeFilter",
"type": "dateRange",
"affects": ["lineChart1", "barChart1"]
}
]
}
```
### Implementation Phases
1. **Phase 1:** Bitable data source verification
2. **Phase 2:** Authentication configuration
3. **Phase 3:** Data request setup
4. **Phase 4:** Chart components (drag & drop)
5. **Phase 5:** Event bindings & filters
6. **Phase 6:** Testing
7. **Phase 7:** Deployment & optimization
### Pros
- ✅ Visual no-code editor
- ✅ Rich component library
- ✅ Advanced event handling
- ✅ Real-time data updates
- ✅ Built-in authentication
- ✅ Easy to modify
### Cons
- ❌ Requires aPaaS account
- ❌ Platform-dependent
- ❌ Limited version control
- ❌ Learning curve for aPaaS
### Documentation Links
- Chart Configuration: `/APAAS_CHART_CONFIG.md`
- Integration Guide: `/config/INTEGRATION_GUIDE.md`
- Quick Start: `/config/QUICK_START.md`
- Data Request Config: `/config/apaas-data-request.json`
---
## Approach C: Custom VChart Component
### Overview
Develop a custom React component using ByteDance's VChart library for full programmatic control, deployed as an aPaaS custom component.
### When to Use
- ✅ Need full customization
- ✅ Complex visualizations
- ✅ Developer team available
- ✅ Version control required
- ✅ Reusable components
- ❌ Quick prototype needed
- ❌ Non-technical team
### Quick Start
```bash
# 1. Setup environment
./scripts/setup-vchart-component.sh
# 2. Build component
npm run build
# 3. Deploy to aPaaS
npm run vchart:deploy
# 4. Upload ZIP to aPaaS custom components
# File: dist/vchart-component/component/tiktok-analytics-dashboard.zip
```
### Files & Documentation
| File | Purpose | Lines |
|------|---------|-------|
| `VCHART_COMPONENT_GUIDE.md` | Complete guide | 616 |
| `VCHART_IMPLEMENTATION_SUMMARY.md` | Overview | 474 |
| `src/vchart-component/index.tsx` | Main component | 195 |
| `src/vchart-component/specs/line-chart.ts` | Line chart spec | 120 |
| `src/vchart-component/specs/bar-chart.ts` | Bar chart spec | 115 |
| `src/vchart-component/specs/pie-chart.ts` | Pie chart spec | 100 |
| `src/vchart-component/specs/dashboard.ts` | Dashboard spec | 180 |
| `component/tiktok-dashboard/index.tsx` | aPaaS wrapper | 150 |
| `component/tiktok-dashboard/model.ts` | Data logic | 135 |
| `component/tiktok-dashboard/meta.ts` | Type definitions | 65 |
| `scripts/deploy-vchart-component.sh` | Deployment script | 125 |
### Component API
```typescript
interface TikTokDashboardProps {
tableId: string; // Required
chartType?: 'line' | 'bar' | 'pie' | 'dashboard';
refreshInterval?: number; // Seconds
height?: number; // Pixels
onChartClick?: (data) => void;
onDataLoad?: (event) => void;
onError?: (error) => void;
}
```
### Usage Example
```tsx
import { TikTokDashboard } from '@components/tiktok-analytics-dashboard';
function App() {
const dashboardRef = useRef();
return (
<TikTokDashboard
ref={dashboardRef}
tableId="tblG4uuUvbwfvI9Z"
chartType="dashboard"
height={600}
refreshInterval={60}
onDataLoad={(e) => console.log(`Loaded ${e.recordCount} videos`)}
onChartClick={(data) => navigate(`/video/${data.videoId}`)}
onError={(err) => showNotification(err.message)}
/>
);
}
```
### Methods (via Ref)
```typescript
// Refresh data
await dashboardRef.current.refresh();
// Export as image
const png = await dashboardRef.current.exportImage('png');
// Get current data
const data = dashboardRef.current.getData();
```
### Chart Specifications
#### Line Chart
```typescript
{
type: 'line',
xField: 'datePublished',
yField: 'views',
point: { visible: true },
line: { style: { lineWidth: 2 } },
axes: [
{ orient: 'bottom', type: 'time' },
{ orient: 'left', type: 'linear' }
]
}
```
#### Bar Chart
```typescript
{
type: 'bar',
direction: 'horizontal',
xField: 'views',
yField: 'title',
data: topTenVideos,
bar: {
style: {
fill: {
gradient: 'linear',
stops: [
{ offset: 0, color: '#1890ff' },
{ offset: 1, color: '#36cfc9' }
]
}
}
}
}
```
#### Pie Chart
```typescript
{
type: 'pie',
outerRadius: 0.8,
innerRadius: 0.5,
data: [
{ type: 'Likes', value: totalLikes },
{ type: 'Comments', value: totalComments },
{ type: 'Shares', value: totalShares }
],
label: {
visible: true,
position: 'outside'
}
}
```
### Dependencies
```json
{
"dependencies": {
"@visactor/vchart": "^1.11.0",
"@visactor/lark-vchart": "^1.0.0",
"react": "^18.0.0",
"react-dom": "^18.0.0"
},
"devDependencies": {
"@types/react": "^18.0.0",
"@types/react-dom": "^18.0.0",
"typescript": "^5.0.0"
}
}
```
### Build Process
```bash
# Install dependencies
npm install
# Build TypeScript
tsc -p src/vchart-component/tsconfig.json
# Bundle component
# (Creates dist/vchart-component/component/tiktok-analytics-dashboard.zip)
npm run vchart:deploy
```
### Pros
- ✅ Full programmatic control
- ✅ Version controlled (Git)
- ✅ Type-safe (TypeScript)
- ✅ Reusable across projects
- ✅ Advanced customization
- ✅ Unit testable
- ✅ Export functionality
### Cons
- ❌ Requires development skills
- ❌ Longer setup time
- ❌ Build/deploy process needed
- ❌ Dependency management
### Documentation Links
- Component Guide: `/VCHART_COMPONENT_GUIDE.md`
- Implementation Summary: `/VCHART_IMPLEMENTATION_SUMMARY.md`
- Quickstart: `/VCHART_QUICKSTART.md`
---
## Feature Comparison
### Implementation Time
| Task | Approach A | Approach B | Approach C |
|------|-----------|-----------|-----------|
| Initial setup | 2 min | 5 min | 30 min |
| First dashboard | 5 min | 15 min | 1 hour |
| Add new chart | 2 min | 5 min | 15 min |
| Modify styling | 3 min | 3 min | 10 min |
| Add interaction | N/A | 5 min | 20 min |
| Deploy changes | Instant | 1 min | 5 min |
### Customization Level
| Feature | A | B | C |
|---------|---|---|---|
| Chart types | Limited to built-in | Native components | Any VChart type |
| Color schemes | Predefined + custom | Full control | Full control |
| Interactions | Basic clicks | Events + filters | Full programmatic |
| Animations | Built-in | Built-in | Custom |
| Layouts | Grid-based | Drag-and-drop | Programmatic |
| Themes | Limited | Custom CSS | Full theming |
### Data Handling
| Capability | A | B | C |
|------------|---|---|---|
| Real-time updates | Auto-refresh | Auto-refresh | Auto-refresh |
| Data transformation | Limited | Expressions | Full code |
| Multiple sources | Via views | Via data requests | Via code |
| Caching | Automatic | Configurable | Programmatic |
| Pagination | Automatic | Configurable | Manual |
| Filtering | UI-based | Expression-based | Code-based |
### Deployment & Maintenance
| Aspect | A | B | C |
|--------|---|---|---|
| Version control | No | No | Yes (Git) |
| CI/CD integration | No | No | Yes |
| Rollback | Manual | Manual | Automated |
| Testing | Manual | Manual | Automated |
| Documentation | Manual | No-code docs | Code comments |
| Team collaboration | Via sharing | Via aPaaS | Via Git |
---
## Migration Paths
### A → B: Bitable to aPaaS
**When to migrate:**
- Need more interactivity
- Want custom workflows
- Require advanced filtering
**Migration steps:**
1. Document current dashboard layout
2. Create aPaaS application
3. Set up Bitable data connector
4. Recreate charts using native components
5. Add interactive features
6. Test and deploy
**Time estimate:** 2-4 hours
---
### A → C: Bitable to VChart
**When to migrate:**
- Need custom visualizations
- Want version control
- Require programmatic control
**Migration steps:**
1. Analyze current dashboard structure
2. Set up development environment
3. Build VChart component
4. Implement chart specifications
5. Add data fetching logic
6. Deploy as custom component
**Time estimate:** 1-2 days
---
### B → C: aPaaS to VChart
**When to migrate:**
- Outgrew no-code limitations
- Need advanced customization
- Want code-based workflow
**Migration steps:**
1. Export aPaaS data request config
2. Set up React development environment
3. Convert expressions to TypeScript
4. Implement chart specs
5. Add business logic
6. Deploy as custom component
**Time estimate:** 4-8 hours
---
### C → B: VChart to aPaaS
**When to migrate:**
- Simplify maintenance
- Enable non-technical updates
- Reduce complexity
**Migration steps:**
1. Document component behavior
2. Identify equivalent aPaaS components
3. Recreate in visual editor
4. Test functionality parity
5. Archive custom component
**Time estimate:** 2-4 hours
---
## Troubleshooting Across Approaches
### Common Issues (All Approaches)
#### 1. Authentication Errors
**Symptoms:**
- 401 Unauthorized
- 403 Forbidden
- "Invalid token" errors
**Solutions:**
```bash
# Check API key is set
echo $LARK_API_KEY
# Verify credentials
curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
-H "Content-Type: application/json" \
-d '{"app_id":"YOUR_ID","app_secret":"YOUR_SECRET"}'
# Ensure correct region
export LARK_REGION="sg" # or "us", "eu"
```
#### 2. Field Name Mismatches
**Symptoms:**
- "Field not found"
- Charts show no data
- Null values displayed
**Solutions:**
- Field names are **case-sensitive**
- Use exact names: `Total video views` not `total video views`
- Verify field exists in Bitable table
- Check field type matches aggregation
#### 3. No Data Displayed
**Symptoms:**
- Empty charts
- "No data available"
- Blank visualizations
**Solutions:**
```javascript
// Check data is being fetched
console.log('Records:', records.length);
// Verify table ID
const TABLE_ID = 'tblG4uuUvbwfvI9Z';
// Check date range filters
// Ensure filters aren't excluding all data
// Verify aggregation types
// SUM for numbers, COUNT for any field
```
#### 4. Performance Issues
**Symptoms:**
- Slow loading
- Timeout errors
- Browser lag
**Solutions:**
```javascript
// Limit records fetched
{
"page_size": 100, // Instead of 500
"field_names": ["Views", "Likes"] // Only needed fields
}
// Enable caching (Approach B & C)
{
"cache": {
"enabled": true,
"ttl": 300
}
}
// Use pagination
// Aggregate data server-side
// Optimize chart rendering
```
### Approach-Specific Issues
#### Approach A Issues
**Problem:** Cannot create dashboard via API
```
Solution: Create one empty dashboard manually in UI first,
then use scripts to copy and modify it.
```
**Problem:** Charts not updating after data change
```
Solution: Refresh dashboard manually or set auto-refresh
interval in dashboard settings.
```
#### Approach B Issues
**Problem:** Data request returns empty
```javascript
// Check authentication in data request settings
{
"auth": {
"type": "custom",
"tokenEndpoint": "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
}
}
// Verify Bitable permissions
// Ensure aPaaS app has access to Bitable table
```
**Problem:** Expression evaluation errors
```javascript
// Use safe navigation
{{data?.views ?? 0}}
// Check expression syntax
{{sum(getTikTokData.data.items.map(i => i.fields.Views))}}
// Test with mock data
```
#### Approach C Issues
**Problem:** Component not loading in aPaaS
```bash
# Check build output
npm run build
# Verify package structure
ls -la dist/vchart-component/
# Check component metadata
cat component/tiktok-dashboard/index.meta.json
# Ensure dependencies are bundled
```
**Problem:** VChart rendering errors
```typescript
// Check data format
interface TikTokVideoData {
videoId: string;
title: string;
views: number; // Must be number, not string
datePublished: string; // ISO 8601 format
}
// Verify chart spec
const spec = getLineChartSpec(data);
console.log('Spec:', spec);
// Check for null values
const validData = data.filter(d => d.views != null);
```
### Debug Checklist
Use this checklist for any approach:
- [ ] API key is set and valid
- [ ] Table ID is correct: `tblG4uuUvbwfvI9Z`
- [ ] Base app token is correct: `C8kmbTsqoa6rBesTKRpl8nV8gHd`
- [ ] Field names match exactly (case-sensitive)
- [ ] Data types are compatible with aggregations
- [ ] No filters excluding all data
- [ ] Authentication token not expired
- [ ] Network connectivity to Lark APIs
- [ ] Browser console shows no errors
- [ ] Data is actually present in Bitable table
---
## Best Practices
### Data Quality
```yaml
Before Building Dashboard:
- Verify all 150 records have complete data
- Check for outliers in metrics (views > 10M?)
- Validate date formats are consistent
- Ensure numeric fields contain numbers, not text
- Remove or handle null values appropriately
```
### Performance Optimization
#### Approach A
- Use filters to limit data range
- Enable auto-refresh (1 hour recommended)
- Archive old dashboards
#### Approach B
```json
{
"optimization": {
"caching": {
"enabled": true,
"ttl": 300
},
"pagination": {
"page_size": 100
},
"field_selection": ["Views", "Likes", "Date"]
}
}
```
#### Approach C
```typescript
// Memoize expensive calculations
const chartData = useMemo(() =>
transformData(rawData),
[rawData]
);
// Debounce resize events
const debouncedResize = debounce(() => {
chart.resize();
}, 200);
// Lazy load charts
const ChartComponent = lazy(() => import('./Chart'));
```
### Security
```bash
# Never commit API keys
echo "LARK_API_KEY=xxx" >> .env
echo ".env" >> .gitignore
# Use environment variables
export LARK_API_KEY="${LARK_API_KEY}"
# Rotate credentials regularly
# Set up IP allowlisting in Lark console
# Use minimal permissions (read-only for dashboards)
```
### Naming Conventions
```typescript
// Dashboards
"TikTok Analytics - Production"
"TikTok Analytics - Staging"
"TikTok Analytics - 2025-12-09"
// Components (Approach B)
getTikTokData // Data request
metricCardViews // Component ID
lineChartTrend // Component ID
// Components (Approach C)
TikTokDashboard // Component name
useTikTokData // Hook name
getLineChartSpec // Function name
```
### Documentation
Regardless of approach:
1. **Document field mappings** - Maintain field name reference
2. **Track changes** - Log modifications to dashboards
3. **Share knowledge** - Document non-obvious configurations
4. **Version dashboards** - Use naming: v1, v2, etc.
5. **Export configs** - Backup configurations regularly
### Testing
#### Approach A
```
1. Test with sample data first
2. Verify all charts load
3. Check mobile view
4. Test filters work
5. Validate sharing permissions
```
#### Approach B
```
1. Test in preview mode
2. Mock data for edge cases
3. Test all event bindings
4. Cross-browser testing
5. Performance testing with full dataset
```
#### Approach C
```typescript
// Unit tests
describe('TikTokDashboard', () => {
it('renders with valid data', () => {
// Test
});
it('handles empty data', () => {
// Test
});
it('handles API errors', () => {
// Test
});
});
// Integration tests
// E2E tests with Cypress/Playwright
```
---
## Resources
### Documentation by Approach
#### Approach A
- **Main Guide:** `/TIKTOK_DASHBOARD_CONFIG.md` (400 lines)
- **Quick Start:** `/QUICK_START_TIKTOK.md` (122 lines)
- **Implementation:** `/IMPLEMENTATION_SUMMARY.md` (445 lines)
- **Scripts Doc:** `/scripts/README.md`
#### Approach B
- **Chart Config:** `/APAAS_CHART_CONFIG.md` (975 lines)
- **Integration Guide:** `/config/INTEGRATION_GUIDE.md` (1,110 lines)
- **Quick Start:** `/config/QUICK_START.md` (246 lines)
- **Data Request:** `/config/apaas-data-request.json` (440 lines)
- **Config README:** `/config/README.md` (440 lines)
#### Approach C
- **Component Guide:** `/VCHART_COMPONENT_GUIDE.md` (616 lines)
- **Implementation:** `/VCHART_IMPLEMENTATION_SUMMARY.md` (474 lines)
- **Quick Start:** `/VCHART_QUICKSTART.md`
- **Component README:** `/src/vchart-component/README.md`
### External Resources
#### Official Documentation
- **Lark Open Platform:** https://open.larksuite.com/
- **Feishu Open Platform:** https://open.feishu.cn/
- **Bitable API:** https://open.feishu.cn/document/server-docs/docs/bitable-v1/
- **aPaaS Platform:** https://apaas.feishu.cn/
- **VChart Library:** https://visactor.io/vchart/
#### Community & Support
- **Developer Community:** https://open.feishu.cn/community/
- **Lark Help Center:** https://www.larksuite.com/hc/
- **GitHub Issues:** https://github.com/hypelab/hype-dash/issues
#### Tools
- **API Explorer:** https://open.feishu.cn/api-explorer/
- **JSON Validator:** https://jsonlint.com/
- **Date Converter:** https://www.epochconverter.com/
### npm Scripts Reference
```json
{
"scripts": {
// Approach A
"tiktok:analyze": "Analyze TikTok data",
"tiktok:analyze:export": "Analyze + export JSON",
"tiktok:copy": "Copy existing dashboard",
"tiktok:create": "Create new dashboard",
// Approach C
"vchart:deploy": "Build and deploy VChart component",
// General
"build": "Build TypeScript",
"test": "Run tests"
}
}
```
### Project Structure
```
lark-dashboard-sdk/
├── Approach A Documentation
│ ├── TIKTOK_DASHBOARD_CONFIG.md
│ ├── QUICK_START_TIKTOK.md
│ └── IMPLEMENTATION_SUMMARY.md
│
├── Approach B Documentation
│ ├── APAAS_CHART_CONFIG.md
│ ├── APAAS_IMPLEMENTATION_SUMMARY.md
│ └── config/
│ ├── INTEGRATION_GUIDE.md
│ ├── QUICK_START.md
│ ├── README.md
│ └── apaas-data-request.json
│
├── Approach C Documentation
│ ├── VCHART_COMPONENT_GUIDE.md
│ ├── VCHART_IMPLEMENTATION_SUMMARY.md
│ ├── VCHART_QUICKSTART.md
│ └── src/vchart-component/
│ ├── index.tsx
│ ├── specs/
│ └── component/
│
├── Unified Documentation
│ ├── UNIFIED_DASHBOARD_GUIDE.md (this file)
│ ├── CONSISTENCY_CHECKLIST.md
│ └── scripts/run-all-approaches.sh
│
└── Scripts
├── analyze-tiktok-data.ts
├── copy-tiktok-dashboard.ts
├── create-tiktok-dashboard.ts
├── deploy-vchart-component.sh
└── setup-vchart-component.sh
```
---
## Quick Reference Tables
### Approach Selection
| If you need... | Choose |
|----------------|--------|
| Dashboard in 5 minutes | A |
| No-code solution | A or B |
| Interactive app | B |
| Custom visualizations | C |
| Version control | C |
| Team collaboration | B or C |
| Mobile-first | B or C |
| Offline capability | None |
| Export functionality | A or C |
### Time Investment
| Task | A | B | C |
|------|---|---|---|
| Learning | 30 min | 2 hours | 1 day |
| Setup | 5 min | 30 min | 2 hours |
| First dashboard | 10 min | 1 hour | 4 hours |
| Maintenance | Low | Medium | Medium |
### Skill Requirements
| Skill | A | B | C |
|-------|---|---|---|
| Lark/Bitable | Required | Required | Required |
| aPaaS Platform | No | Required | Required |
| JavaScript | No | No | Required |
| React | No | No | Required |
| TypeScript | No | No | Recommended |
| Git | No | No | Recommended |
---
## Summary
This unified guide provides complete documentation for all three approaches to building TikTok Analytics Dashboards in the Lark ecosystem:
- **Approach A:** Native Bitable Dashboard - Fastest setup, minimal coding
- **Approach B:** aPaaS Chart Components - Visual editor, no-code interactivity
- **Approach C:** Custom VChart Component - Full control, code-based
### Choose Based On
- **Time available:** A (minutes) < B (hours) < C (days)
- **Technical skills:** A (none) < B (none) < C (React/TS)
- **Customization needs:** A (basic) < B (high) < C (unlimited)
- **Maintenance:** A (manual) < B (visual) < C (code)
### All Approaches Share
- Same data source (Bitable table)
- Same field schema
- Same authentication
- Same core visualizations
- TikTok-branded color scheme
### Next Steps
1. **Review Decision Matrix** to pick your approach
2. **Follow Quick Start** for chosen approach
3. **Consult approach-specific docs** for details
4. **Use Troubleshooting section** when issues arise
5. **Consider migration paths** as needs evolve
### Support
- **Documentation:** See approach-specific guides
- **Issues:** GitHub Issues
- **Community:** Lark Developer Community
---
**Version:** 1.0.0
**Last Updated:** 2025-12-09
**Maintainer:** HypeLab Development Team
**License:** MIT
