New Integration: Meta Ads

Description

Add Meta Ads integration to sync Facebook/Instagram advertising campaigns, ad performance metrics, audience insights, and conversion data into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - OAuth-based API integration
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

integrations/meta-ads/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Meta Marketing API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Meta Marketing API Integration

OAuth Setup

• Use Facebook Login with OAuth 2.0
• Register app on Meta for Developers portal
• Required permissions: ads_read, ads_management, read_insights, pages_read_engagement, business_management
• API versioning: quarterly releases with 2-year lifespan per version (currently v19.0+)
• Base URL: https://graph.facebook.com/v19.0/

Key Endpoints

• GET /act_{ad_account_id}/campaigns - List ad campaigns
• GET /act_{ad_account_id}/adsets - List ad sets
• GET /act_{ad_account_id}/ads - List individual ads
• GET /{campaign_id}/insights - Campaign performance metrics
• GET /{adset_id}/insights - Ad set performance metrics
• GET /{ad_id}/insights - Individual ad metrics
• GET /act_{ad_account_id}/insights - Account-level insights
• GET /{ad_id}/previews - Ad creative previews
• GET /act_{ad_account_id}/customaudiences - Custom audiences
• GET /act_{ad_account_id}/reachestimate - Reach estimates

Events to Track

1. Campaigns - Campaign creation, status changes, budget updates
2. Ad Performance - Impressions, clicks, CTR, CPC, CPM, conversions
3. Audience Insights - Audience demographics, reach, and engagement
4. Ad Sets - Targeting changes, bid strategy updates
5. Creative - Ad creative updates, A/B test results
6. Conversions - Conversion tracking, ROAS, attribution data

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement Facebook OAuth 2.0 flow in account-create.ts
• Create API utilities in utils.ts for campaigns, ad sets, ads, and insights
• Implement sync logic in schedule.ts for polling ad performance data
• Convert ad performance metrics to CORE activity format
• Add error handling and rate limiting (respect Meta API rate limits)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Meta releases new API versions quarterly; each version has a 2-year lifespan
• As of v25.0 (Feb 2025), Advantage+ Shopping/App campaigns cannot be created via API
• Page Viewer Metric replacing legacy reach metric by end of June 2026
• Rate limiting is based on API call volume per ad account
• Insights API supports date range breakdowns and async report generation
• Consider using batch requests for efficiency with multiple ad accounts

Resources

• Meta Marketing API Documentation
• Graph API Reference
• Meta for Developers
• Marketing API Postman Collection

Labels

enhancement, integration, new-feature