# TikTok Analytics Scripts
This directory contains helper scripts for analyzing TikTok data and creating dashboards in Lark Bitable.
## Prerequisites
Before running these scripts, you need to:
1. Set up your Lark API key:
```bash
export LARK_API_KEY="your-api-key-here"
```
2. (Optional) Set your region:
```bash
export LARK_REGION="sg" # Options: sg, cn, us
```
## Available Scripts
### 1. Analyze TikTok Data
Fetches all TikTok video data from the Bitable and generates comprehensive analytics.
**Usage:**
```bash
# Run analysis and display summary
npm run tiktok:analyze
# Or with ts-node directly
npx ts-node scripts/analyze-tiktok-data.ts
# Export JSON data for visualization
npm run tiktok:analyze:export
```
**Output:**
- Total videos count
- Total views, likes, comments, shares
- Average metrics (watch rate, duration, engagement)
- Top 10 performing videos
- Video duration distribution
- Performance insights and recommendations
**Example Output:**
```
================================================================================
TIKTOK VIDEO ANALYTICS SUMMARY
================================================================================
OVERVIEW:
Total Videos: 150
Date Range: 2024-01-01 to 2024-12-09
PERFORMANCE METRICS:
Total Views: 2,450,000
Total Likes: 185,000
Total Comments: 12,500
Total Shares: 8,200
Total Engagement: 205,700
AVERAGE METRICS:
Avg Views per Video: 16,333
Avg Watch Rate: 45.23%
Avg Engagement Rate: 8.39%
Avg Video Duration: 42 seconds
TOP 10 VIDEOS BY VIEWS:
1. 125,000 views - Check out our new candle collection...
2. 98,500 views - Behind the scenes of candle making...
...
```
### 2. Copy TikTok Dashboard
Copies the existing TikTok dashboard with a new name.
**Usage:**
```bash
npm run tiktok:copy
# Or with ts-node directly
npx ts-node scripts/copy-tiktok-dashboard.ts
```
**What it does:**
1. Lists all existing dashboards in the app
2. Copies the specified dashboard (blkxYx6MmEeujy0v)
3. Creates a new dashboard with timestamp
4. Displays the link to the new dashboard
### 3. Create TikTok Dashboard
Creates a comprehensive TikTok analytics dashboard with all recommended charts and metrics.
**Usage:**
```bash
npm run tiktok:create
# Or with ts-node directly
npx ts-node scripts/create-tiktok-dashboard.ts
```
**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 & Likes over time
- X-axis: Date published
- Y-axis: Views and Likes (dual axis)
3. **Top Videos Chart**
- Horizontal bar chart
- Shows top 10 videos by views
4. **Engagement Pie Chart**
- Breakdown of Likes, Comments, Shares
5. **Data Table**
- Full table view with all video details
- Sortable and filterable columns
## Configuration
All scripts use the following configuration:
```typescript
const CONFIG = {
APP_TOKEN: 'C8kmbTsqoa6rBesTKRpl8nV8gHd',
TABLE_ID: 'tblG4uuUvbwfvI9Z',
EXISTING_DASHBOARD_ID: 'blkxYx6MmEeujy0v',
API_KEY: process.env.LARK_API_KEY || '',
REGION: process.env.LARK_REGION || 'sg',
};
```
## Field Names
The scripts use these field names from the TikTok table:
- `Unique identifier of the video` - Video ID
- `Date and time the video was published` - Publication date
- `Total video views` - View count
- `Total number of likes the video received` - Like count
- `Total number of comments the video received` - Comment count
- `Total number of times the video was shared` - Share count
- `Percentage of video watched completely` - Watch completion rate
- `Video description` - Description text
- `Duration of the video in seconds` - Video length
## Troubleshooting
### Authentication Errors
If you get authentication errors:
1. Verify your `LARK_API_KEY` is correct
2. Check that the API key has proper permissions
3. Ensure the region matches your workspace
### "No existing dashboards found"
The Lark API doesn't support creating dashboards from scratch. You need to:
1. Go to your Lark Bitable app manually
2. Create a new dashboard (even an empty one)
3. Then run the scripts
### Field Name Errors
If you get errors about missing fields:
1. Check that the table ID is correct
2. Verify the field names match exactly (case-sensitive)
3. Ensure you have access to the table
## Examples
### Example 1: Quick Analysis
```bash
# Set your API key
export LARK_API_KEY="cli_xxxxxxxxxxxx"
# Run analysis
npm run tiktok:analyze
# Get insights about your TikTok performance
```
### Example 2: Create Dashboard
```bash
# Set your API key
export LARK_API_KEY="cli_xxxxxxxxxxxx"
# Create comprehensive dashboard
npm run tiktok:create
# Open the link provided in the output
```
### Example 3: Copy and Customize
```bash
# Copy existing dashboard
npm run tiktok:copy
# Open the new dashboard in Lark
# Customize charts and layouts manually in the UI
```
## Integration with Manual Dashboard Creation
Since the Lark API has limitations, we recommend a hybrid approach:
1. **Use Scripts For:**
- Data analysis and insights
- Quick dashboard copying
- Initial dashboard structure
2. **Use Lark UI For:**
- Fine-tuning chart positions
- Adjusting chart sizes and colors
- Adding filters and interactivity
- Setting up auto-refresh
## Next Steps
After running these scripts:
1. Open the dashboard in Lark
2. Review the TIKTOK_DASHBOARD_CONFIG.md for detailed configuration
3. Customize the dashboard layout
4. Share with your team
5. Set up automated reports
## Resources
- Main Configuration Guide: `/TIKTOK_DASHBOARD_CONFIG.md`
- SDK Documentation: `/README.md`
- Lark API Docs: https://open.larksuite.com/
## Support
For issues or questions:
- Check the main README.md
- Review error messages carefully
- Verify your configuration matches the documentation
