# Approach A: Bitable Dashboard - Complete Implementation Guide
## Overview
**Approach A** leverages Lark's built-in Bitable Dashboard feature to create TikTok analytics visualizations. This is the **simplest and most recommended approach** for most users, as it uses native Lark features without requiring custom components or complex integrations.
### Key Features
- **Native Integration**: Uses Lark's built-in dashboard blocks (charts, metrics, tables)
- **MCP Proxy Support**: All scripts use the lark-mcp proxy for enhanced reliability
- **Production-Ready**: Comprehensive error handling and logging
- **Type-Safe**: Full TypeScript implementation
- **Easy to Use**: Simple npm commands for all operations
### Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Your Application │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Analysis │ │ Create │ │ Copy │ │
│ │ Script │ │ Dashboard │ │ Dashboard │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └─────────────────┼──────────────────┘ │
│ │ │
└───────────────────────────┼─────────────────────────────────┘
│
▼
┌─────────────────────────┐
│ lark-mcp MCP Proxy │
│ (hypelive.app) │
└─────────────┬───────────┘
│
▼
┌─────────────────────────┐
│ Lark Bitable API │
└─────────────┬───────────┘
│
▼
┌─────────────────────────┐
│ Your Lark Dashboard │
│ (150 TikTok videos) │
└─────────────────────────┘
```
## Configuration
### Base Configuration
All scripts use the following configuration:
```typescript
const CONFIG = {
APP_TOKEN: 'C8kmbTsqoa6rBesTKRpl8nV8gHd',
TABLE_ID: 'tblG4uuUvbwfvI9Z',
EXISTING_DASHBOARD_ID: 'blkxYx6MmEeujy0v',
MCP_PROXY_URL: 'https://lark-mcp.hypelive.app',
REGION: 'sg',
};
```
### Field Mappings
The TikTok table contains these fields:
```typescript
const FIELDS = {
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',
};
```
## Available Scripts
### 1. Quick Start (Recommended)
Run the unified quick-start script that analyzes data and optionally creates a dashboard:
```bash
npm run approach-a:quickstart
```
**What it does:**
- Fetches all TikTok video data via MCP proxy
- Analyzes and displays key metrics (total views, likes, watch rate, top performer)
- Prompts to create a new dashboard
- Adds KPI metrics and performance charts
- Provides dashboard URL for viewing
**Output:**
```
╔═══════════════════════════════════════════════════════════════╗
║ APPROACH A: Bitable Dashboard Quick Start ║
║ Using lark-mcp MCP Proxy ║
╚═══════════════════════════════════════════════════════════════╝
Configuration:
App Token: C8kmbTsqoa6rBesTKRpl8nV8gHd
Table ID: tblG4uuUvbwfvI9Z
MCP Proxy: https://lark-mcp.hypelive.app
Region: sg
[Analysis results...]
[Dashboard creation if selected...]
```
### 2. Analyze TikTok Data
Fetch and analyze all TikTok video data:
```bash
npm run tiktok:analyze
```
**Features:**
- Fetches all 150 video records via MCP proxy
- Calculates aggregate metrics (total views, likes, comments, shares)
- Computes averages (watch rate, duration, engagement rate)
- Identifies top 10 performers by views
- Shows duration distribution
- Generates actionable insights
**Export as JSON:**
```bash
npm run tiktok:analyze:export
```
### 3. Create New Dashboard
Create a comprehensive TikTok analytics dashboard:
```bash
npm run tiktok:create
```
**Dashboard Components:**
1. **KPI Cards (4 cards)**
- Total Views
- Total Engagement (Likes)
- Total Videos
- Average Watch Rate
2. **Performance Trend Chart**
- Line chart showing views and engagement over time
- Grouped by publication date
3. **Top Videos Chart**
- Bar chart of top 10 videos by views
4. **Engagement Breakdown**
- Pie chart showing likes, comments, shares distribution
5. **Data Table**
- Full table view with all video details
- Sortable and filterable
### 4. Copy Existing Dashboard
Copy the existing dashboard to create a new instance:
```bash
npm run tiktok:copy
```
**Use cases:**
- Create a backup of the current dashboard
- Duplicate dashboard for different time periods
- Test modifications without affecting the original
## File Structure
```
lark-dashboard-sdk/
├── scripts/
│ ├── analyze-tiktok-data.ts # Data analysis script
│ ├── create-tiktok-dashboard.ts # Dashboard creation script
│ ├── copy-tiktok-dashboard.ts # Dashboard copy script
│ └── quick-start-approach-a.ts # Unified quick-start script
├── TIKTOK_DASHBOARD_CONFIG.md # Detailed dashboard configuration
└── APPROACH_A_COMPLETE.md # This file
```
## Implementation Details
### MCP Proxy Integration
All scripts use the lark-mcp MCP proxy at `https://lark-mcp.hypelive.app` for:
1. **Enhanced Reliability**: Automatic retries and error handling
2. **Simplified Authentication**: No need to manage API keys directly
3. **Consistent Interface**: Unified API across all operations
4. **Better Error Messages**: Clear, actionable error reporting
### Error Handling
All scripts include comprehensive error handling:
```typescript
try {
// Operation
} catch (error: any) {
if (error.response) {
console.error(`Status: ${error.response.status}`);
console.error(`Message: ${error.response.data?.error}`);
} else if (error.request) {
console.error('No response from server');
} else {
console.error(`Error: ${error.message}`);
}
}
```
### TypeScript Types
All scripts use proper TypeScript types:
```typescript
interface TikTokRecord {
record_id: string;
fields: {
[key: string]: any;
};
}
interface AnalysisResults {
totalRecords: number;
totalViews: number;
totalLikes: number;
avgWatchRate: number;
topVideos: any[];
// ... more fields
}
```
## Dashboard Configuration
### Recommended Dashboard Layout
```
┌─────────────────────────────────────────────────────────┐
│ [Total Views] [Total Likes] [Total Videos] [Watch%] │ KPI Row
├─────────────────────────────────────────────────────────┤
│ │
│ Views & Engagement Over Time │ Trend Chart
│ (Line Chart) │
│ │
├──────────────────────────────┬──────────────────────────┤
│ │ │
│ Top 10 Videos by Views │ Engagement Distribution │ Analysis Row
│ (Bar Chart) │ (Pie Chart) │
│ │ │
├─────────────────────────────────────────────────────────┤
│ │
│ All Videos - Detailed View │ Data Table
│ (Table View) │
│ │
└─────────────────────────────────────────────────────────┘
```
### Chart Specifications
See `TIKTOK_DASHBOARD_CONFIG.md` for detailed specifications of each chart type, including:
- Field mappings
- Aggregation types
- Color schemes
- Size and position
- Filters and sorting
## Best Practices
### 1. Regular Analysis
Run the analysis script regularly to track performance:
```bash
# Daily analysis
npm run tiktok:analyze
# Export for reporting
npm run tiktok:analyze:export > daily-report-$(date +%Y%m%d).json
```
### 2. Dashboard Versioning
Create dated dashboard copies for historical comparison:
```bash
npm run tiktok:copy
# Rename in Lark UI to "TikTok Analytics - 2025-12-09"
```
### 3. Incremental Updates
Instead of recreating dashboards, copy and modify:
1. Copy existing dashboard
2. Adjust date filters for new period
3. Compare with previous periods
4. Archive old dashboards
### 4. Performance Monitoring
Monitor these key metrics:
- **Total Views**: Overall reach
- **Watch Rate**: Content quality indicator
- **Engagement Rate**: (Likes + Comments + Shares) / Views
- **Top Performers**: Learn from successful content
## Troubleshooting
### Common Issues
#### 1. Connection Errors
```
Error: ECONNREFUSED
```
**Solution:**
- Check internet connection
- Verify MCP proxy URL is correct
- Ensure proxy service is running
#### 2. No Data Returned
```
Fetched 0 records
```
**Solution:**
- Verify app token and table ID are correct
- Check table has records
- Ensure table permissions allow reading
#### 3. Dashboard Creation Fails
```
Error: No existing dashboards found
```
**Solution:**
- Create at least one dashboard manually in Lark Bitable first
- Use the existing dashboard ID: `blkxYx6MmEeujy0v`
#### 4. Field Not Found Errors
```
Error: Field 'Total video views' not found
```
**Solution:**
- Verify field names match exactly (case-sensitive)
- Check field names in Lark table
- Update FIELDS configuration if needed
### Debug Mode
Enable verbose logging:
```typescript
const client = new LarkDashboardClient({
// ...
logging: true, // Enable debug logs
});
```
## Comparison with Other Approaches
### Approach A vs Approach B (VChart Custom Component)
| Feature | Approach A (Bitable) | Approach B (VChart) |
|---------|---------------------|---------------------|
| Complexity | Low | High |
| Custom Charts | Limited | Unlimited |
| Setup Time | Minutes | Hours |
| Maintenance | Easy | Complex |
| Interactivity | Basic | Advanced |
| Best For | Standard analytics | Custom visualizations |
### Approach A vs Approach C (Lark Bot)
| Feature | Approach A (Bitable) | Approach C (Bot) |
|---------|---------------------|------------------|
| User Interaction | Dashboard viewing | Chat commands |
| Automation | Manual refresh | Event-driven |
| Accessibility | Web dashboard | Mobile + Web |
| Real-time | Refresh required | Instant updates |
| Best For | Analysis & reporting | Alerts & queries |
## Production Checklist
### Pre-Deployment
- [ ] Test all scripts locally
- [ ] Verify MCP proxy connectivity
- [ ] Review dashboard layout
- [ ] Test with production data
- [ ] Document custom modifications
### Deployment
- [ ] Set environment variables
- [ ] Configure npm scripts
- [ ] Test each command
- [ ] Verify dashboard creation
- [ ] Check data accuracy
### Post-Deployment
- [ ] Schedule regular analysis runs
- [ ] Set up dashboard refresh schedule
- [ ] Configure alerts for anomalies
- [ ] Train team on dashboard usage
- [ ] Document custom dashboards
## Advanced Usage
### Custom Analysis Scripts
Extend the analysis script for custom insights:
```typescript
import { fetchAllRecords, analyzeData } from './scripts/analyze-tiktok-data';
async function customAnalysis() {
const records = await fetchAllRecords();
// Custom analysis
const weekendVideos = records.filter(r => {
const date = new Date(r.fields['Date and time the video was published']);
return date.getDay() === 0 || date.getDay() === 6;
});
console.log(`Weekend videos: ${weekendVideos.length}`);
}
```
### Automated Reporting
Create a cron job for daily reports:
```bash
#!/bin/bash
# daily-report.sh
cd /path/to/lark-dashboard-sdk
npm run tiktok:analyze:export > reports/$(date +%Y%m%d).json
# Send to team
curl -X POST https://your-webhook-url \
-H "Content-Type: application/json" \
-d @reports/$(date +%Y%m%d).json
```
### Dashboard Templates
Create reusable dashboard templates:
```typescript
// templates/tiktok-analytics.ts
export const TIKTOK_DASHBOARD_TEMPLATE = {
name: 'TikTok Analytics Template',
blocks: [
// KPI cards
{ type: 'metrics', field: 'views', aggregation: 'sum' },
{ type: 'metrics', field: 'likes', aggregation: 'sum' },
// Charts
{ type: 'line', x: 'date', y: 'views' },
// ... more blocks
],
};
```
## Support and Resources
### Documentation
- **TIKTOK_DASHBOARD_CONFIG.md**: Detailed dashboard specifications
- **README.md**: SDK overview and installation
- **DOCUMENTATION/TUTORIALS/**: Step-by-step tutorials
### Example Dashboards
- Live Example: `https://hypelive.sg.larksuite.com/base/C8kmbTsqoa6rBesTKRpl8nV8gHd`
- Dashboard ID: `blkxYx6MmEeujy0v`
### Getting Help
1. Check this documentation
2. Review error messages and troubleshooting section
3. Examine example scripts in `/scripts` directory
4. Test with the quick-start script first
5. Review MCP proxy documentation
## Conclusion
**Approach A: Bitable Dashboard** is the recommended starting point for TikTok analytics visualization in Lark. It provides:
✓ **Quick Setup**: Get started in minutes with npm commands
✓ **Production-Ready**: Comprehensive error handling and logging
✓ **MCP Integration**: Enhanced reliability via lark-mcp proxy
✓ **Type-Safe**: Full TypeScript implementation
✓ **Extensible**: Easy to customize and extend
### Quick Start Command
```bash
npm run approach-a:quickstart
```
### Next Steps
1. Run the quick-start script to see it in action
2. Review the generated dashboard in Lark
3. Customize charts and metrics for your needs
4. Set up automated analysis and reporting
5. Share insights with your team
---
**Last Updated**: 2025-12-09
**Version**: 1.0
**Approach**: A (Bitable Dashboard)
**Status**: Production-Ready
