elinking-111 Ads API Connectors
Design reliable read-first ads data pipelines. Treat write operations such as pausing campaigns, changing bids, uploading audiences, or editing budgets as high-risk and require explicit user confirmation.
Workflow
- Define connector purpose:
- Reporting only.
- Monitoring and anomaly detection.
- Offline conversion upload.
- Audience sync.
- Controlled account actions.
- Resolve account model:
- Google MCC/customer ids, Meta business/ad account ids, TikTok advertiser ids, LinkedIn ad accounts, Microsoft manager accounts, Apple Ads orgs.
- Confirm auth:
- OAuth app, scopes, refresh token, developer token, app review, system user, token expiration, least-privilege access.
- Design schema:
- Stable ids, names, status, date, currency, spend, impressions, clicks, conversions, values, campaign/ad group/ad/keyword/creative dimensions.
- Creative-level fields when available: creative/ad id, asset id, asset name, format, aspect ratio, duration, thumbnail/video URL, landing URL, copy text, headline, CTA, hook, angle, offer, product/use case, creator, proof type, funnel stage, launch date, age, and fatigue status.
- Build sync plan:
- Incremental daily sync, rolling backfill for conversion lag, idempotent upserts, retry and rate-limit handling.
- Validate:
- Reconcile API totals to platform UI for the same date range, timezone, attribution settings, and currency.
- Document failure modes:
- Auth expiration, partial pages, incompatible fields, delayed conversions, removed entities, renamed entities, sampling, privacy thresholding.
Platform Notes
- Google Ads: use GAQL compatibility carefully; cost is micros; MCC login customer id often matters.
- Meta: account timezone and attribution settings can change apparent results; CAPI diagnostics are separate from Ads Insights.
- TikTok: advertiser id, reporting dimensions, Events API status, and Spark Ads permissions need separate checks.
- LinkedIn: limited reporting granularity and long B2B lag; align with CRM stages when possible.
- Microsoft: imported Google structures need validation; UET and Microsoft-specific placements matter.
- Apple Ads: org/campaign ids, CPP assignment, MMP post-install events, and AdAttributionKit/SKAN limitations matter.
Creative-Level Data Model
When the user wants creative analytics, reporting, fatigue monitoring, or a creative board, design the pipeline at creative/ad grain instead of only campaign/ad group grain.
Canonical Tables
| Table | Grain | Purpose |
|---|---|---|
ad_daily |
platform + account + ad/creative + date | Spend, delivery, clicks, conversions, value, CPA/ROAS over time |
creative_asset |
platform + asset/creative id | Stable metadata, format, dimensions, duration, URLs, text, launch date |
creative_taxonomy |
asset/creative id + taxonomy version | Hook, angle, offer, CTA, proof type, product/use case, funnel stage |
creative_cluster |
cluster id + taxonomy signature | Groups similar assets by concept, not just file or text similarity |
creative_alert |
asset/cluster + date + alert type | Fatigue, winner, loser, inconclusive, policy risk, tracking caveat |
Canonical Creative Fields
| Field | Notes |
|---|---|
creative_id |
Platform ad or creative id; stable if possible |
asset_id |
Image/video/document/product asset id when distinct from ad id |
creative_cluster_id |
Concept cluster for comparing variants across platforms |
format |
static, video, carousel, collection, document, PMax asset, CPP, etc. |
hook |
First-frame / headline / opening promise; inferred fields must be marked |
angle |
price, speed, trust, novelty, ROI, risk reduction, ease, quality, etc. |
offer |
trial, demo, discount, consultation, bundle, app install, lead magnet |
cta |
normalized CTA text |
proof_type |
review, case study, rating, benchmark, credential, demo, guarantee |
funnel_stage |
prospecting, retargeting, brand, competitor, retention, upsell |
launch_date / creative_age_days |
Needed for fatigue and refresh cadence |
thumbstop_rate / hold_rate / watch_time |
Platform-specific video metrics; null when unavailable |
Validation Rules
- Reconcile creative totals to campaign totals for the same date range, timezone, and attribution window.
- Preserve platform ids even when names change.
- Store taxonomy version so AI-generated tags can be re-run without corrupting historical reports.
- Mark AI-inferred fields as inferred; do not mix them with user-approved manual tags.
- Avoid cross-platform creative ranking unless attribution windows and conversion definitions are comparable.
- Track missing thumbnails/videos separately from missing metrics.
Output
Provide:
## Connector Plan
| Platform | Auth Needed | Accounts | Data Grain | Sync Cadence | Risks |
## Field Map
| Canonical Field | Platform Field | Notes |
## Creative-Level Schema
| Canonical Field | Google | Meta | TikTok | LinkedIn | Microsoft | Apple | Notes |
## Validation Plan
...
## Runbook
...