# aPaaS Chart Configuration Files
Production-ready JSON configurations for TikTok Analytics Dashboard components.
## Overview
This directory contains copy-paste ready configurations for all 8 chart components used in the aPaaS-based TikTok analytics dashboard (Approach B).
## Files in This Directory
| File | Component | Description |
|------|-----------|-------------|
| `01-metric-card-total-views.json` | Metric Card | Total video views with trend indicator |
| `02-metric-card-total-likes.json` | Metric Card | Total likes with trend indicator |
| `03-metric-card-avg-engagement.json` | Metric Card | Average engagement rate with conditional formatting |
| `04-metric-card-total-followers.json` | Metric Card | Current followers with growth indicator |
| `05-line-chart-views-engagement.json` | Line Chart | Dual-axis chart for views and engagement trends |
| `06-bar-chart-engagement-breakdown.json` | Bar Chart | Stacked bar chart for likes/comments/shares |
| `07-pie-chart-engagement-distribution.json` | Pie Chart | Donut chart showing engagement distribution |
| `08-table-video-performance.json` | Table | Detailed performance metrics table |
## Quick Start
### 1. Prerequisites
Before using these configurations:
- ✅ aPaaS application created (ID: `Dffwb10dwaz6UZs6c4HlWyV3g7c`)
- ✅ Page created (ID: `pgeEOroex4nCBQxc`)
- ✅ Data request configured (name: `getTikTokData`)
- ✅ Authentication set up (see `/config/apaas-data-request.json`)
### 2. Import Process
For each configuration file:
1. **Open aPaaS Console**
- Navigate to: https://apaas.feishu.cn
- Open your app and page
2. **Add Component**
- Drag the corresponding component type to canvas
- Click to select the component
3. **Apply Configuration**
- Open the JSON file
- Copy relevant sections to component properties:
- Basic settings (title, subtitle)
- Data binding expressions
- Display options (colors, formats)
- Layout settings
4. **Test Component**
- Verify data loads correctly
- Check formatting
- Test interactions
### 3. Configuration Order
Follow this order for best results:
1. **Start with Metric Cards (01-04)**
- Easiest to configure
- Validates data connection
- Provides quick visual feedback
2. **Add Line Chart (05)**
- Tests time-series data
- Validates dual-axis setup
3. **Add Bar Chart (06)**
- Tests stacked series
- Validates data slicing
4. **Add Pie Chart (07)**
- Tests aggregations
- Validates donut layout
5. **Add Table (08)**
- Most complex component
- Validates all field mappings
## Configuration Structure
Each JSON file follows this structure:
```json
{
"component": "ComponentType",
"id": "uniqueComponentId",
"name": "Display Name",
"description": "Component description",
"config": {
"title": "Chart Title",
"dataBinding": { ... },
"display": { ... },
"events": { ... }
},
"layout": {
"position": { ... },
"size": { ... }
},
"metadata": { ... }
}
```
### Key Sections
#### dataBinding
Contains expressions for data access:
```json
{
"dataSource": "getTikTokData",
"valueExpression": "{{getTikTokData.data.items.reduce(...)}}"
}
```
#### display
Visual styling and formatting:
```json
{
"color": {
"primary": "#3370FF"
},
"numberFormat": {
"type": "compact",
"maximumFractionDigits": 1
}
}
```
#### events
Interactive behaviors:
```json
{
"onClick": {
"action": "filter",
"target": "otherComponent"
}
}
```
## Common Patterns
### Data Access Expressions
**Sum all values:**
```javascript
{{getTikTokData.data.items.reduce((sum, item) => sum + (item.fields.Views || 0), 0)}}
```
**Calculate average:**
```javascript
{{getTikTokData.data.items.reduce((sum, item) => sum + (item.fields.Engagement_Rate || 0), 0) / getTikTokData.data.items.length}}
```
**Map to array:**
```javascript
{{getTikTokData.data.items.map(i => i.fields.Views)}}
```
**Get latest value:**
```javascript
{{getTikTokData.data.items[getTikTokData.data.items.length - 1].fields.Followers}}
```
**Slice data:**
```javascript
{{getTikTokData.data.items.slice(0, 30)}}
```
### Format Patterns
**Compact numbers (1.5K, 2.3M):**
```json
{
"type": "compact",
"notation": "compact",
"maximumFractionDigits": 1
}
```
**Percentages:**
```json
{
"type": "decimal",
"maximumFractionDigits": 2,
"suffix": "%"
}
```
**Dates:**
```javascript
{{new Date(item.fields.Date).toLocaleDateString('en-US', {month: 'short', day: 'numeric'})}}
```
## Customization Guide
### Colors
Default color palette:
```javascript
{
"views": "#3370FF", // Blue
"likes": "#FF3B69", // Red
"engagement": "#00C48C", // Green
"followers": "#8A5CD1", // Purple
"comments": "#FA8C16", // Orange
"shares": "#52c41a" // Light Green
}
```
To customize, update the `color` properties in each configuration.
### Number Formats
Available format types:
- `compact`: 1.5K, 2.3M
- `standard`: 1,234,567
- `decimal`: 15.23
- `percentage`: 15.2%
### Chart Dimensions
Default sizes (customizable):
- Metric Cards: 25% width, 120px height
- Line Chart: 100% width, 400px height
- Bar Chart: 50% width, 350px height
- Pie Chart: 50% width, 350px height
- Table: 100% width, 500px height
## Field Reference
### Available Fields
From Bitable table (`tblG4uuUvbwfvI9Z`):
| Field | Type | Description |
|-------|------|-------------|
| `Date` | Timestamp | Publication date (Unix ms) |
| `Views` | Number | Total video views |
| `Likes` | Number | Total likes |
| `Comments` | Number | Total comments |
| `Shares` | Number | Total shares |
| `Followers` | Number | Follower count |
| `Engagement_Rate` | Number | Engagement percentage |
### Field Access Path
```javascript
// Base path
getTikTokData.data.items
// Single record
getTikTokData.data.items[0]
// Field value
getTikTokData.data.items[0].fields.Views
// All values for a field
getTikTokData.data.items.map(i => i.fields.Views)
```
For detailed field mapping, see: `/config/FIELD_MAPPING.md`
## Validation
Before using these configurations, run:
```bash
node scripts/validate-apaas-setup.js
```
Expected output:
```
✓ All tests passed! Your aPaaS setup is ready.
```
## Troubleshooting
### Component doesn't display data
**Check:**
1. Data source name matches exactly: `getTikTokData`
2. Field names are case-sensitive: `Views` not `views`
3. Data path is correct: `data.items` not just `items`
**Fix:**
```javascript
// Wrong
{{getTikTokdata.items.map(...)}}
// Correct
{{getTikTokData.data.items.map(...)}}
```
### "Cannot read property" error
**Cause:** Null/undefined values
**Fix:** Add null safety
```javascript
// Before
item.fields.Views
// After
item.fields.Views || 0
```
### Numbers show as "NaN"
**Cause:** Invalid calculation or null division
**Fix:** Add validation
```javascript
// Before
total / count
// After
count > 0 ? total / count : 0
```
## Examples
### Example 1: Modify Metric Card Color
Open `01-metric-card-total-views.json`, find:
```json
{
"display": {
"color": {
"primary": "#3370FF" // Change this
}
}
}
```
Change to your brand color:
```json
{
"display": {
"color": {
"primary": "#FF6B6B" // New color
}
}
}
```
### Example 2: Change Line Chart Time Period
Open `05-line-chart-views-engagement.json`, find:
```json
{
"dataBinding": {
"dataPath": "data.items" // All data
}
}
```
Change to last 7 days:
```json
{
"dataBinding": {
"dataPath": "data.items.slice(-7)" // Last 7 records
}
}
```
### Example 3: Add Calculated Column to Table
Open `08-table-video-performance.json`, add column:
```json
{
"columns": [
// ... existing columns ...
{
"id": "colViewsPerFollower",
"field": "ViewsPerFollower",
"label": "Views/Follower",
"type": "calculated",
"expression": "{{row.fields.Views / row.fields.Followers}}",
"format": {
"pattern": "0.00"
}
}
]
}
```
## Best Practices
### 1. Always Use Null Safety
```javascript
// Good
item.fields.Views || 0
// Bad
item.fields.Views
```
### 2. Cache Expensive Calculations
```javascript
// Good - calculate once
const totalViews = items.reduce(...);
return totalViews;
// Bad - calculates multiple times
return items.reduce(...) + items.reduce(...);
```
### 3. Format Numbers for Display
```javascript
// Good
{{Intl.NumberFormat('en-US').format(value)}}
// Bad
{{value}} // Shows 1234567 instead of 1,234,567
```
### 4. Test with Edge Cases
- Empty data: `items.length === 0`
- Single record: `items.length === 1`
- Large dataset: `items.length > 1000`
- Null values: `item.fields.Views === null`
### 5. Use Descriptive IDs
```javascript
// Good
"id": "metricCardTotalViews"
// Bad
"id": "card1"
```
## Additional Resources
### Documentation
- [Main Integration Guide](../INTEGRATION_GUIDE.md)
- [Field Mapping Reference](../FIELD_MAPPING.md)
- [Complete Setup Guide](../../APPROACH_B_COMPLETE.md)
- [Chart Configuration Docs](../../APAAS_CHART_CONFIG.md)
### External Links
- [aPaaS Platform](https://apaas.feishu.cn)
- [Bitable API Docs](https://open.feishu.cn/document/server-docs/docs/bitable-v1/)
- [Feishu Open Platform](https://open.feishu.cn)
### Support
- Developer Community: https://open.feishu.cn/community/
- API Explorer: https://open.feishu.cn/api-explorer/
## Version History
- **v1.0** (2025-12-09): Initial release with 8 chart configurations
## License
These configurations are part of the lark-dashboard-sdk project.
See main project LICENSE file for details.
---
**Need Help?**
1. Check `/config/INTEGRATION_GUIDE.md` for detailed setup instructions
2. Run `node scripts/validate-apaas-setup.js` to test your configuration
3. Review field mappings in `/config/FIELD_MAPPING.md`
4. Consult troubleshooting section in `APPROACH_B_COMPLETE.md`
**Ready to Build?**
Start with the Quick Start guide above, and you'll have a working dashboard in ~90 minutes!
