TikTok Ads

Open https://business-api.tiktok.com and navigate to My Apps. Click Create App, enter your app name and description, and under Scopes select the reporting permissions you need — at minimum: ads:read, campaign:read, ad_group:read, ad:read. Submit for review; basic reporting access is typically approved quickly for self-serve accounts. Once approved, go to your app's detail page and locate the Auth section. Complete the OAuth authorization flow for your advertiser account to generate a long-lived access token. TikTok Marketing API access tokens can remain valid for extended periods when issued via the server-to-server OAuth flow, but you should plan for expiry and build a refresh mechanism using the refresh token. Copy the access token and your advertiser_id — you need both in the next step. Do not save either value in a spreadsheet, a Notion doc, or anywhere that might sync to a client-accessible location. They go directly into your backend environment variables only. If you manage multiple advertiser accounts you can use the same developer app but will need a separate token per account or the MCC-style app token flow.

In the Firebase Console, open your project and click Functions in the left sidebar. You will write a small HTTP function that receives the date range and advertiser ID from FlutterFlow, reads the access token from environment variables, and forwards the request to the TikTok Reporting API. Create the function as shown in the code block below. The function must return CORS headers (Access-Control-Allow-Origin: *) because FlutterFlow web builds run in a browser and the browser will block cross-origin responses without these headers. Native iOS and Android builds do not enforce CORS, but including the headers ensures your web build also works. Deploy the function from your local development environment using the Firebase CLI — this is the one CLI operation in this entire tutorial and it runs on your computer, not inside FlutterFlow. After deployment, the Firebase Console shows you the HTTPS trigger URL (something like https://us-central1-YOUR_PROJECT.cloudfunctions.net/tiktokReporting). Copy that URL — you will paste it into FlutterFlow as the API Group Base URL. Set your access token as an environment variable using `firebase functions:config:set` or the newer Secret Manager integration so it never appears in your source code. Alternatively, use a Supabase Edge Function with identical logic — the fetch call and CORS headers are the same; only the deployment method differs.

1// functions/index.js (Firebase Cloud Functions — Node.js)
2const functions = require('firebase-functions');
3const fetch = require('node-fetch'); // add to functions/package.json
4
5exports.tiktokReporting = functions.https.onRequest(async (req, res) => {
6  res.set('Access-Control-Allow-Origin', '*');
7  res.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
8  res.set('Access-Control-Allow-Headers', 'Content-Type');
9  if (req.method === 'OPTIONS') { res.status(204).send(''); return; }
10
11  const ACCESS_TOKEN = process.env.TIKTOK_ACCESS_TOKEN;
12  const { advertiser_id, start_date, end_date } = req.body;
13
14  if (!advertiser_id || !start_date || !end_date) {
15    res.status(400).json({ error: 'Missing required fields' });
16    return;
17  }
18
19  const params = new URLSearchParams({
20    advertiser_id,
21    report_type: 'BASIC',
22    dimensions: JSON.stringify(['campaign_id', 'stat_time_day']),
23    metrics: JSON.stringify(['campaign_name', 'spend', 'impressions', 'clicks', 'ctr', 'cpm']),
24    start_date,
25    end_date,
26    page_size: '100'
27  });
28
29  const tikTokRes = await fetch(
30    `https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/?${params}`,
31    { headers: { 'Access-Token': ACCESS_TOKEN } }
32  );
33  const data = await tikTokRes.json();
34  res.json(data);
35});
36

In FlutterFlow, click API Calls in the left navigation panel, then click + Add and choose Create API Group. Name it TikTokReporting and paste your Firebase Cloud Function HTTPS trigger URL as the Base URL — for example: https://us-central1-your-project.cloudfunctions.net/tiktokReporting. Leave the Headers section of the group empty: the secret token lives on the server and does not travel through FlutterFlow at all. Now click + Add inside the group to create an individual API Call. Name it getCampaignMetrics, set the HTTP method to POST, and leave the endpoint path blank (the Base URL is the complete endpoint). Switch to the Body tab and select JSON as the body format. Add three body variables: advertiser_id (type String), start_date (type String, format YYYY-MM-DD), and end_date (type String). Your body template becomes: { "advertiser_id": "{{advertiser_id}}", "start_date": "{{start_date}}", "end_date": "{{end_date}}" }. Open the Response & Test tab, fill in real values from your TikTok account, and click Test. A successful response shows a JSON object with a data.list array. Click Generate from Response to have FlutterFlow automatically create JSON Path expressions for every field in the response. You will reference these paths when binding widgets to the data. If the test returns an error, check that the Cloud Function is deployed successfully and that the environment variable is set.

1{
2  "advertiser_id": "{{advertiser_id}}",
3  "start_date": "{{start_date}}",
4  "end_date": "{{end_date}}"
5}

In FlutterFlow, navigate to Data Types in the left panel and create a new custom Data Type called CampaignMetric. Add these fields: campaignId (String), campaignName (String), spend (Double), impressions (Integer), clicks (Integer), ctr (Double), cpm (Double), statDate (String). Return to your API Call configuration, go to Response & Test, and use the JSON Path section to map each path to the corresponding field in CampaignMetric: $.data.list[*].dimensions.campaign_id maps to campaignId, $.data.list[*].metrics.spend maps to spend, and so on. The nested structure — dimensions object and metrics object per list item — is TikTok's response shape, so make sure your paths reference the correct sub-object. Now create a new screen for your dashboard. Add a ListView widget and set its source to Backend Query → getCampaignMetrics. In the parameter binding panel, connect advertiser_id to your app's current user's advertiser ID (stored in your Supabase or Firestore user record), and set start_date and end_date from App State variables representing the selected date range. Inside the ListView, add a Container with two Text widgets: one bound to item.campaignName and one formatted as 'Spend: $' + item.spend (use FlutterFlow's number formatting options to show two decimal places). Optionally add a Chart widget above the list bound to the spend series grouped by statDate.

TikTok's Marketing API enforces rate limits per developer app and per advertiser account. When multiple app users open the dashboard at the same time, each session triggers a separate upstream request through your proxy, and together they can exhaust the shared quota — producing 429 errors for everyone. The solution is a caching layer inside your Cloud Function: before calling TikTok, check a Firestore document for a cached response. If the document is less than 30 minutes old, return it immediately. If it is stale or missing, fetch fresh data from TikTok, write it to Firestore, and return it. The Firestore document key can be a combination of advertiser_id and date range so each unique query has its own cache entry. Update your Cloud Function to include this caching logic as shown in the code block below. In FlutterFlow, add a forceRefresh Boolean body variable to the getCampaignMetrics API Call and pass true from your pull-to-refresh action so users can explicitly bypass the cache when they need the very latest numbers. Add a small 'Updated {timestamp}' text on the dashboard screen to set expectations that data refreshes on a schedule rather than in real time. If you want help architecting the caching layer or multi-account proxy setup, RapidDev's team builds FlutterFlow integrations like this every week — free scoping call at rapidevelopers.com/contact.

1// Add caching logic inside tiktokReporting function
2const admin = require('firebase-admin');
3if (!admin.apps.length) admin.initializeApp();
4const db = admin.firestore();
5
6const { advertiser_id, start_date, end_date, force_refresh } = req.body;
7const cacheKey = `${advertiser_id}_${start_date}_${end_date}`;
8const cacheRef = db.collection('tiktok_cache').doc(cacheKey);
9const cached = await cacheRef.get();
10
11if (cached.exists && !force_refresh) {
12  const { payload, lastUpdated } = cached.data();
13  const ageMs = Date.now() - lastUpdated;
14  if (ageMs < 30 * 60 * 1000) {
15    res.json({ ...payload, cached: true, lastUpdated });
16    return;
17  }
18}
19
20// ... TikTok fetch code ...
21// After receiving data from TikTok:
22await cacheRef.set({ payload: tikTokData, lastUpdated: Date.now() });
23res.json({ ...tikTokData, cached: false });
24

If you want TikTok to count in-app conversions for ad attribution, you need to send Purchase or SignUp events back to TikTok via the Events API. This is separate from the Reporting API and handles the reverse data flow — app to TikTok. Create a second endpoint in your Cloud Function (or a separate function) that accepts an event type, revenue amount, currency, and order ID from FlutterFlow and forwards them to https://business-api.tiktok.com/open_api/v1.3/pixel/track/ with your access token. Wire this proxy call to a FlutterFlow Action Flow on your checkout or sign-up success state: add a Backend/API Call action immediately after the completion trigger, passing the event details as the body. If you prefer the native SDK approach for richer attribution signals, you can create a Custom Action wrapping a TikTok events package from pub.dev. Important: Custom Actions do not run in FlutterFlow's web Test Mode — test them on a real device or an APK build only. Add a kIsWeb guard in the Dart code so the SDK initializer is skipped on web and falls back to the proxy-based approach. On iOS 14.5+, the user must have granted App Tracking Transparency (ATT) consent before conversion events are attributed to specific ad campaigns.

1// Optional Dart guard for native SDK Custom Action
2import 'package:flutter/foundation.dart' show kIsWeb;
3
4Future<void> trackTikTokPurchase(
5  String orderId,
6  double revenue,
7  String currency,
8) async {
9  if (kIsWeb) {
10    // On web: use the proxy API Call instead of the SDK
11    return;
12  }
13  // Initialize and call TikTok SDK via pub.dev package
14  // Check pub.dev for current TikTok Flutter package name and API
15  // Example structure (package name varies):
16  // await TikTokBusiness.trackEvent('CompletePayment',
17  //   properties: {'value': revenue, 'currency': currency});
18}
19