# Quick Start: Lark aPaaS Dashboard Setup
**TL;DR:** Dashboard views cannot be created via API. Create them manually in Lark UI, then use this SDK to manage the data.
---
## The Reality
```
❌ NOT POSSIBLE via API:
- Creating dashboard views
- Adding charts programmatically
- Configuring dashboard layouts
✅ POSSIBLE via API:
- Creating tables & fields
- Creating grid/kanban/gallery/gantt/form views
- Managing records (CRUD)
- Updating data that feeds dashboards
```
---
## 5-Minute Setup
### Step 1: Install & Configure (30 seconds)
```bash
npm install @hypelab/lark-dashboard-sdk
```
```typescript
import { LarkBaseClient } from '@hypelab/lark-dashboard-sdk';
import { createDashboardManager } from '@hypelab/lark-dashboard-sdk/apaas';
const client = new LarkBaseClient({
appId: process.env.LARK_APP_ID,
appSecret: process.env.LARK_APP_SECRET,
appToken: 'KdW3bZ3axa636XsocGVln8DAgmg'
});
const dashboardMgr = createDashboardManager(client, 'KdW3bZ3axa636XsocGVln8DAgmg');
```
### Step 2: Create Tables (1 minute - API)
```typescript
const campaignsTable = await client.tables.create({
name: 'TikTok Campaigns',
fields: [
{ name: 'Campaign Name', type: 1 },
{ name: 'Impressions', type: 2 },
{ name: 'Clicks', type: 2 },
{ name: 'Conversions', type: 2 },
{ name: 'Spend', type: 99003 }
]
});
```
### Step 3: Create Dashboard (3 minutes - MANUAL)
1. Open: https://hypelive.sg.larksuite.com/app/KdW3bZ3axa636XsocGVln8DAgmg
2. Click "+" next to view tabs
3. Select "Dashboard"
4. Add charts:
- Bar chart: Campaign Performance
- Line chart: Trend Over Time
- Pie chart: Budget Distribution
### Step 4: Add Data (30 seconds - API)
```typescript
await dashboardMgr.updateDashboardData(campaignsTable.table_id, [
{
fields: {
'Campaign Name': 'Q1 Campaign',
'Impressions': 1000000,
'Clicks': 5000,
'Conversions': 250,
'Spend': 7500
}
}
]);
```
**Done!** Dashboard automatically updates with new data.
---
## Three Approaches
### Approach A: Manual Dashboard + API Data (Recommended)
**Time:** 5 minutes
**Difficulty:** Easy
**Best for:** Most use cases
```typescript
// 1. Create tables via API
const table = await client.tables.create({...});
// 2. Create dashboard manually in UI (3 min)
// 3. Add data via API
await dashboardMgr.updateDashboardData(table.table_id, records);
```
**Pros:**
- ✅ Full dashboard functionality
- ✅ Easy to implement
- ✅ Professional visualizations
**Cons:**
- ❌ Manual dashboard creation
---
### Approach B: Lark Docs + Embedded Charts
**Time:** 30 minutes
**Difficulty:** Medium
**Best for:** Automated reports
```typescript
// Create doc
const doc = await client.docs.create('Campaign Report');
// Generate chart image
const chartImage = await generateChart(data);
// Embed in doc
await client.docs.addImageBlock(doc.id, chartImage);
```
**Pros:**
- ✅ Fully programmable
- ✅ Rich text + charts
**Cons:**
- ❌ Static images (no interactivity)
- ❌ More complex
---
### Approach C: Custom Base Extension
**Time:** 2-4 hours
**Difficulty:** Hard
**Best for:** Custom analytics
```typescript
import { bitable } from '@lark-base-open/js-sdk';
import VChart from '@visactor/vchart';
// Fetch data
const table = await bitable.base.getActiveTable();
const records = await table.getRecordList();
// Render chart
const vchart = new VChart(spec, { dom: 'chart' });
vchart.renderAsync();
```
**Pros:**
- ✅ Interactive charts
- ✅ Real-time updates
- ✅ Custom UI
**Cons:**
- ❌ Requires extension development
- ❌ Hosting required
---
## Complete Example
```typescript
import { LarkBaseClient } from '@hypelab/lark-dashboard-sdk';
import { createDashboardManager } from '@hypelab/lark-dashboard-sdk/apaas';
async function setupTikTokDashboard() {
// 1. Initialize
const client = new LarkBaseClient({
appId: process.env.LARK_APP_ID,
appSecret: process.env.LARK_APP_SECRET,
appToken: 'KdW3bZ3axa636XsocGVln8DAgmg'
});
const dashboardMgr = createDashboardManager(
client,
'KdW3bZ3axa636XsocGVln8DAgmg'
);
// 2. Create tables
const campaignsTable = await client.tables.create({
name: 'TikTok Campaigns',
fields: [
{ name: 'Campaign Name', type: 1 },
{ name: 'Status', type: 3 },
{ name: 'Impressions', type: 2 },
{ name: 'Clicks', type: 2 },
{ name: 'Conversions', type: 2 },
{ name: 'Spend', type: 99003 },
{ name: 'CTR', type: 20 }, // Formula
{ name: 'CPA', type: 99003 }
]
});
// 3. Prepare infrastructure
const instructions = await dashboardMgr.prepareDashboardInfrastructure({
dashboardName: 'TikTok Campaign Performance',
dataSources: [
{ tableId: campaignsTable.table_id, tableName: 'TikTok Campaigns' }
],
recommendedCharts: [
{
type: 'bar',
title: 'Conversions by Campaign',
dataSource: campaignsTable.table_id,
xField: 'Campaign Name',
yField: 'Conversions'
},
{
type: 'line',
title: 'Trend Over Time',
dataSource: campaignsTable.table_id,
xField: 'Date',
yField: 'Conversions'
}
]
});
// 4. Print instructions
dashboardMgr.printSetupInstructions(instructions);
// 5. Add data
await dashboardMgr.updateDashboardData(campaignsTable.table_id, [
{
fields: {
'Campaign Name': 'Summer Sale 2025',
'Status': 'Active',
'Impressions': 1000000,
'Clicks': 5000,
'Conversions': 250,
'Spend': 7500
}
}
]);
console.log('✅ Dashboard ready!');
console.log(`Open: https://hypelive.sg.larksuite.com/app/KdW3bZ3axa636XsocGVln8DAgmg`);
}
setupTikTokDashboard();
```
---
## Automated Data Updates
Once dashboard is created manually, automate data updates:
```typescript
// Sync TikTok data every hour
setInterval(async () => {
// Fetch from TikTok API
const campaigns = await fetchTikTokCampaigns();
// Update Lark Base
await dashboardMgr.updateDashboardData(
campaignsTable.table_id,
campaigns.map(c => ({
fields: {
'Campaign Name': c.name,
'Impressions': c.metrics.impressions,
'Clicks': c.metrics.clicks,
'Conversions': c.metrics.conversions,
'Spend': c.metrics.spend
}
}))
);
console.log(`✅ Updated ${campaigns.length} campaigns`);
}, 60 * 60 * 1000); // Every hour
```
---
## API Reference
### Supported View Types
| View Type | API Support | Use Case |
|-----------|-------------|----------|
| **grid** | ✅ Yes | Spreadsheet view |
| **kanban** | ✅ Yes | Task management |
| **gallery** | ✅ Yes | Visual browsing |
| **gantt** | ✅ Yes | Project timeline |
| **form** | ✅ Yes | Data collection |
| **dashboard** | ❌ **NO** | Analytics (MANUAL) |
### Create View API
```typescript
// Works for: grid, kanban, gallery, gantt, form
await client.views.create(tableId, {
view_name: 'My View',
view_type: 'grid' // or kanban, gallery, gantt, form
});
// Does NOT work for dashboard
await client.views.create(tableId, {
view_name: 'My Dashboard',
view_type: 'dashboard' // ❌ ERROR: Invalid view_type
});
```
**Error Response:**
```json
{
"code": 40002,
"msg": "Invalid view_type parameter",
"error": {
"message": "view_type must be one of: grid, kanban, gallery, gantt, form"
}
}
```
---
## FAQ
### Q: Can I create dashboards programmatically?
**A:** No. Dashboard views must be created manually in Lark UI.
### Q: Why doesn't Lark provide a dashboard API?
**A:** Dashboard creation is complex and interactive. Lark likely reserves it for UI-based configuration.
### Q: What's the best workaround?
**A:** Use Approach A (Manual Dashboard + API Data). Takes 5 minutes, works perfectly.
### Q: Can I automate dashboard updates?
**A:** Yes! Once created manually, dashboards auto-refresh when you update underlying data via API.
### Q: Can I programmatically add charts to existing dashboard?
**A:** No. Charts must be added manually.
### Q: Will Lark add a dashboard API in the future?
**A:** Unknown. Monitor [Lark Developer Updates](https://www.larksuite.com/hc/en-US/articles/360048487834-lark-docs-updates).
---
## Resources
- **Full Research Report:** [docs/APAAS_API_RESEARCH.md](./APAAS_API_RESEARCH.md)
- **Example Code:** [examples/apaas-dashboard-setup.ts](../examples/apaas-dashboard-setup.ts)
- **API Documentation:** [Lark Developer Portal](https://open.larksuite.com/)
- **GitHub Issues:** [Report a bug](https://github.com/hypelab/hype-dash/issues)
---
## Support
Need help? Check:
1. Full research report: [docs/APAAS_API_RESEARCH.md](./APAAS_API_RESEARCH.md)
2. Example implementations: [examples/](../examples/)
3. GitHub issues: [github.com/hypelab/hype-dash/issues](https://github.com/hypelab/hype-dash/issues)
4. Lark Support: [larksuite.com/hc](https://www.larksuite.com/hc/en-US/)
---
**Last Updated:** December 9, 2025
