Ads Platform Integrations
UniPulse integrates with Meta Ads (Facebook/Instagram) and TikTok Promote for campaign management, post boosting, and ad performance tracking.
Supported Platforms
| Platform | API | Features | Sync Queue |
|---|---|---|---|
| Meta Ads | Marketing API v19+ | Create campaigns, boost posts, read insights | ad-sync |
| TikTok Promote | TikTok Ads API | Boost TikTok videos, read performance | ad-sync |
Meta Ads Manager
Authentication
OAuth 2.0 via Facebook Login with the ads_management and ads_read permissions. Uses the same token as the social account connection.
Capabilities
| Feature | API Call | Description |
|---|---|---|
| Create campaign | Marketing API - Campaign creation | Full campaign setup with targeting |
| Boost post | Marketing API - Promote existing post | Turn organic post into ad |
| Read insights | GET /act_{ad-account-id}/insights | Spend, reach, conversions, CPM, CPC |
| Manage ad sets | Marketing API - Ad set CRUD | Audience targeting, budget, schedule |
Auto-Boost Rules
The AutoBoostRule model enables automatic post promotion when performance thresholds are met:
| Rule Condition | Example | Action |
|---|---|---|
| Engagement rate above threshold | engagementRate > 5% | Boost with specified budget |
| Reach above threshold | reach > 10000 in first 2 hours | Boost for wider reach |
| Specific content type | classification.category == 'promotional' | Boost with conversion objective |
Configuration
// AutoBoostRule example
{
workspaceId: 'ws_123',
conditions: {
metric: 'engagementRate',
operator: 'gt',
value: 5,
timeWindow: '2h',
},
budget: {
amount: 50,
currency: 'USD',
duration: '3d',
},
targeting: {
audiences: ['existing_followers', 'lookalike'],
},
enabled: true,
}
TikTok Promote
Authentication
TikTok Ads OAuth with promote.create and promote.read scopes. Linked to the existing TikTok social account.
Capabilities
| Feature | Description |
|---|---|
| Boost videos | Promote existing TikTok videos to wider audience |
| Read performance | Campaign views, clicks, spend, conversions |
| Auto-boost | Same rule engine as Meta, targeting TikTok content |
Ad Performance Sync
The ad-sync queue periodically fetches ad performance metrics from both platforms:
Synced Metrics
| Metric | Meta Ads | TikTok Promote |
|---|---|---|
| Spend | Yes | Yes |
| Reach | Yes | Yes |
| Impressions | Yes | Yes |
| Clicks | Yes | Yes |
| Conversions | Yes | Yes |
| CPM | Yes | Calculated |
| CPC | Yes | Calculated |
| ROAS | Yes (with e-commerce) | Yes (with e-commerce) |
Database Models
| Model | Purpose | Key Fields |
|---|---|---|
AdCampaign | Ad campaign records | workspaceId, platform, externalId, budget, status, metrics |
AutoBoostRule | Automatic boost rules | workspaceId, conditions, budget, targeting, enabled |
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/ads | GET | List ad campaigns with performance |
/api/v1/ads | POST | Create ad campaign or boost rule |
/api/v1/ads/:id | PATCH | Update campaign or rule |
/api/v1/ads/:id | DELETE | Delete campaign or rule |
All ads routes require authenticate, requireWorkspace('EDITOR'), and requireFeature('ads').
Cross-Reference
- Social APIs -- underlying platform auth tokens
- Queue System -- ad-sync queue
- Analytics -- unified organic + paid analytics
- Schema Overview -- AdCampaign and AutoBoostRule models