# TikTok Analytics VChart Component - Deployment Instructions
## Quick Deployment Guide
Follow these steps to deploy the TikTok Analytics Dashboard custom component to your Lark/Feishu aPaaS application.
---
## Prerequisites Checklist
- [ ] Node.js 16+ installed
- [ ] Lark/Feishu Developer account
- [ ] aPaaS application created
- [ ] Bitable table with TikTok data (table ID: `tblG4uuUvbwfvI9Z`)
- [ ] Lark App credentials (App ID and App Secret)
---
## Step 1: Install Dependencies
```bash
cd /Users/mdch/hype-dash
# Install project dependencies
npm install
# Install VChart dependencies
npm install @visactor/vchart @visactor/lark-vchart --save
# Verify installation
npm list @visactor/vchart @visactor/lark-vchart
```
**Expected Output:**
```
@hypelab/lark-dashboard-sdk@1.0.0
├── @visactor/lark-vchart@1.0.0
└── @visactor/vchart@1.11.0
```
---
## Step 2: Configure Credentials
Create a `.env` file in the project root:
```bash
cat > .env << 'EOF'
# Lark Application Credentials
LARK_APP_ID=your_app_id_here
LARK_APP_SECRET=your_app_secret_here
# Bitable Configuration
BITABLE_APP_TOKEN=your_bitable_app_token
BITABLE_TABLE_ID=tblG4uuUvbwfvI9Z
# Deployment Environment
DEPLOY_ENV=dev
EOF
```
**Get your credentials:**
1. Go to [Feishu Open Platform](https://open.feishu.cn)
2. Navigate to your application
3. Copy App ID and App Secret
4. Get Bitable app token from your Bitable settings
---
## Step 3: Build the Component
### Option A: Automated Build (Recommended)
```bash
# Make script executable
chmod +x scripts/deploy-vchart-component.sh
# Build for development
./scripts/deploy-vchart-component.sh dev
```
### Option B: Manual Build
```bash
# Compile TypeScript
npm run build
# Copy component files
mkdir -p dist/vchart-component
cp -r component/tiktok-dashboard/* dist/vchart-component/
cp -r src/vchart-component dist/vchart-component/src
# Create package
cd dist
zip -r tiktok-dashboard.zip vchart-component/
```
**Build Output Location:**
```
dist/
├── vchart-component/ # Built component files
└── tiktok-dashboard-dev.zip # Deployment package
```
---
## Step 4: Deploy to aPaaS
### Option A: Automated Deployment (Recommended)
```bash
# Set credentials as environment variables
export LARK_APP_ID="your_app_id"
export LARK_APP_SECRET="your_app_secret"
# Deploy to production
./scripts/deploy-vchart-component.sh prod
```
### Option B: Manual Upload
1. **Access Feishu Developer Console:**
- Go to https://open.feishu.cn
- Sign in with your account
- Navigate to your aPaaS application
2. **Upload Component:**
- Click on **"Custom Components"** in the left sidebar
- Click **"Upload Component"** button
- Select file: `dist/tiktok-dashboard-prod.zip`
- Wait for upload to complete
3. **Configure Component:**
- Component Name: `TikTokAnalyticsDashboard`
- Version: `1.0.0`
- Description: Advanced TikTok analytics visualization
- Click **"Save"**
4. **Publish Component:**
- Click **"Publish"** button
- Select target environment (Development/Production)
- Confirm publication
---
## Step 5: Add Component to Your Page
### In aPaaS Page Builder
1. **Open Page Editor:**
- Navigate to your aPaaS application
- Go to **"Pages"** section
- Create a new page or edit existing
2. **Add Component:**
- Drag **"Custom Component"** to your page
- Select **"TikTokAnalyticsDashboard"** from dropdown
- Position on the page
3. **Configure Properties:**
**Basic Configuration:**
```json
{
"bitableTableId": "tblG4uuUvbwfvI9Z",
"bitableAppToken": "your_bitable_app_token",
"chartType": "dashboard",
"width": "100%",
"height": 800
}
```
**Advanced Configuration:**
```json
{
"bitableTableId": "tblG4uuUvbwfvI9Z",
"bitableAppToken": "your_bitable_app_token",
"chartType": "dashboard",
"width": "100%",
"height": 800,
"topVideosMetric": "views",
"showViewsOverTime": true,
"showTopVideos": true,
"showEngagement": true,
"autoRefresh": true,
"refreshInterval": 300000
}
```
4. **Configure Events (Optional):**
```javascript
// On Chart Ready
onChartReady: function(chart) {
console.log('Dashboard loaded successfully');
// Additional initialization
}
// On Chart Click
onChartClick: function(params) {
console.log('Clicked video:', params.datum);
// Navigate to video details
this.navigateTo('/video-details', {
videoId: params.datum.video_id
});
}
// On Data Update
onDataUpdate: function(data) {
console.log('Data updated:', data);
// Update other components
}
// On Error
onError: function(error) {
console.error('Dashboard error:', error);
this.showNotification({
type: 'error',
message: 'Failed to load analytics: ' + error.message
});
}
```
5. **Save and Preview:**
- Click **"Save"** button
- Click **"Preview"** to test
- Verify charts are displaying correctly
---
## Step 6: Verification
### Visual Verification
Your dashboard should display:
✓ **Views Over Time Chart** (Top)
- Line chart showing video views over time
- Multiple colored lines for different videos
- Interactive tooltips on hover
- Date axis at bottom
✓ **Top Videos Chart** (Bottom Left)
- Horizontal bar chart
- Top 10 videos by selected metric
- Gradient-colored bars
- Labels showing values
✓ **Engagement Breakdown Chart** (Bottom Right)
- Donut pie chart
- Segments for views, likes, comments, shares, saves
- Percentage labels
- Total in center
### Functional Verification
Test the following features:
1. **Hover Interactions:**
- Hover over charts to see tooltips
- Verify data is correctly formatted
2. **Click Events:**
- Click on chart elements
- Check console for event logs
3. **Auto-refresh (if enabled):**
- Wait for refresh interval
- Verify data updates
4. **Responsive Sizing:**
- Resize browser window
- Verify charts adjust properly
---
## Step 7: Troubleshooting
### Component Not Visible
**Problem:** Component doesn't appear in custom components list
**Solution:**
```bash
# Re-upload component
./scripts/deploy-vchart-component.sh prod
# Or manually re-upload the ZIP file
```
### Charts Not Rendering
**Problem:** Component shows loading spinner indefinitely
**Solutions:**
1. **Check Bitable Credentials:**
```javascript
// Verify in browser console
console.log('Table ID:', props.bitableTableId);
console.log('App Token:', props.bitableAppToken);
```
2. **Check Data Access:**
- Ensure Bitable table exists
- Verify app has read permissions
- Check table has records
3. **Check Browser Console:**
- Open Developer Tools (F12)
- Look for error messages
- Verify VChart is loaded
### No Data Available
**Problem:** Charts show "No data available"
**Solutions:**
1. **Verify Bitable Table:**
```bash
# Test Bitable API access
curl -X GET \
"https://open.feishu.cn/open-apis/bitable/v1/apps/${BITABLE_APP_TOKEN}/tables/${BITABLE_TABLE_ID}/records" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
```
2. **Check Data Format:**
- Ensure table has required fields:
- video_id
- video_title
- publish_date
- views, likes, comments, shares, saves
3. **Check Field Types:**
- Numeric fields (views, likes, etc.) should be Number type
- publish_date should be DateTime type
### Auto-refresh Not Working
**Problem:** Data doesn't refresh automatically
**Solutions:**
1. **Verify Configuration:**
```json
{
"autoRefresh": true,
"refreshInterval": 300000
}
```
2. **Check Console:**
- Look for refresh logs
- Verify no errors during refresh
3. **Manual Refresh:**
```javascript
// Test manual refresh
const dashboard = page.getComponent('tiktok-dashboard');
await dashboard.refresh();
```
---
## Step 8: Production Deployment
### Pre-production Checklist
- [ ] All features tested in development
- [ ] Performance verified with real data
- [ ] Error handling tested
- [ ] Browser compatibility checked
- [ ] Mobile responsiveness verified
- [ ] Load testing completed
### Deploy to Production
```bash
# Build for production
./scripts/deploy-vchart-component.sh prod
# Or manual deployment
export DEPLOY_ENV=prod
npm run build
```
### Post-deployment Verification
1. **Smoke Test:**
- Load the page
- Verify all charts render
- Test interactions
- Check performance
2. **Monitor Logs:**
- Check for errors in console
- Monitor API calls
- Verify data loading times
3. **User Acceptance:**
- Get feedback from users
- Monitor usage analytics
- Address any issues
---
## Component Maintenance
### Update Component
To update the component with changes:
```bash
# 1. Make changes to component files
# 2. Increment version in package.json
# 3. Rebuild
npm run build
# 4. Re-deploy
./scripts/deploy-vchart-component.sh prod
```
### Rollback
If issues occur after deployment:
```bash
# Use existing rollback script
./scripts/rollback.sh
# Or manually upload previous version
```
---
## Common Configuration Examples
### Example 1: Line Chart Only
```json
{
"bitableTableId": "tblG4uuUvbwfvI9Z",
"bitableAppToken": "your_token",
"chartType": "line",
"width": "100%",
"height": 400
}
```
### Example 2: Top Videos by Likes
```json
{
"bitableTableId": "tblG4uuUvbwfvI9Z",
"bitableAppToken": "your_token",
"chartType": "bar",
"topVideosMetric": "likes",
"width": "100%",
"height": 500
}
```
### Example 3: Engagement Pie Chart
```json
{
"bitableTableId": "tblG4uuUvbwfvI9Z",
"bitableAppToken": "your_token",
"chartType": "pie",
"width": 600,
"height": 400
}
```
### Example 4: Full Dashboard with Auto-refresh
```json
{
"bitableTableId": "tblG4uuUvbwfvI9Z",
"bitableAppToken": "your_token",
"chartType": "dashboard",
"width": "100%",
"height": 800,
"showViewsOverTime": true,
"showTopVideos": true,
"showEngagement": true,
"topVideosMetric": "views",
"autoRefresh": true,
"refreshInterval": 300000
}
```
---
## Support Resources
### Documentation
- [Quick Start Guide](QUICK_START.md)
- [Complete Component Guide](VCHART_COMPONENT_GUIDE.md)
- [Implementation Summary](VCHART_IMPLEMENTATION_SUMMARY.md)
- [Example Code](examples/vchart-dashboard-example.ts)
### External Resources
- [VChart Documentation](https://visactor.io/vchart)
- [Lark VChart Guide](https://visactor.io/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/mini-app/lark)
- [Feishu Open Platform](https://open.feishu.cn)
- [Lark Bitable API](https://open.feishu.cn/document/server-docs/docs/bitable-v1/overview)
### Get Help
- **Email:** dev@hypelab.com
- **GitHub:** https://github.com/hypelab/hype-dash/issues
---
## Success Criteria
Your deployment is successful when:
✓ Component appears in aPaaS custom components list
✓ Component can be added to pages
✓ All three chart types render correctly
✓ Data loads from Bitable without errors
✓ Interactive features (tooltips, clicks) work
✓ Auto-refresh functions as expected
✓ No console errors
✓ Performance is acceptable (< 2s load time)
---
**Deployment Time Estimate:** 30-45 minutes (first time)
**Need help?** Refer to the [Troubleshooting Guide](VCHART_COMPONENT_GUIDE.md#troubleshooting) or contact support.
---
**Last Updated:** December 9, 2024
