1. Choose a platform
external_ref — your own namespace for addressing end-users (IN-6), never a
secret. Auto-generated per browser session so concurrent testers don't bind/overwrite each
other's accounts; edit it if you want to reuse a specific one. Kept across the OAuth
redirect round-trip.
2–4. Request sent to binding
Exactly what this app's backend sent to /api/v3/oauth/start
(key held server-side, never sent to this page) — and what it returned.
Example (static contract)
Loading example…
Live (this run)
Click Bind above to see a live run here.
7. Auth result
Example (static contract)
Loading example…
Live (this run)
Complete a Bind above to see a live result here.
Callback contract — what binding actually redirected back to:
Access token: held server-side by BDDAI, never returned to this app —
the redirect back only ever carries ?status=.
8. Bound accounts
Example (static contract)
Loading example…
Live (this run)
Complete a Bind above to see a live fetch here.
9. Fetch data
Insights family only (meta/instagram/tiktok/google/google_analytics — shopee/shopify
are orders-family, not wired here) — GET /{platform}/data for one account,
no date range given (service defaults to the last 30 days).
SV-C6 landed — period (day/week/month/year) and breakdown/filter are now
server-side (breakdown_interval/group_by/
filter_by+filter), not client-side aggregation like before. Period
comparison (current vs previous, delta) is still fetch-two-ranges +
compute client-side — no built-in compare param.
ℹ️ filter matches on campaign name (regex substring,
case-insensitive) — not a numeric campaign ID. Single value: verified correct (narrows the
summary exactly as expected, and filter_exclude gives the exact complement).
Known issue (found live, not a demo bug): multiple values are currently
ANDed together server-side, not OR'd — filtering by two distinct campaign names returns
empty instead of their combined total. Use one value at a time for now.
Example (static contract)
Loading example…
Live (this run)
Complete step 8 above to pick an account here.
Precedence when multiple are set (server-side, verified against the code): Breakdown > Period > Filter > none (plain summary).
10. Metric catalog
Reacts to the platform picker above — no bind needed. Owner decision: metric access is not gated per-metric — once a platform is granted, its whole catalog is open (no per-metric allowlist below).
⚠️ Catalog = full intended metric list. Actual availability on
/{platform}/data fully aligns once service's MV-1 lands
(TikTok is currently a subset) — source moves to MV-2 (data-driven)
later.