Conversion API

Track ad installs from TikTok, Instagram and Pinterest, in two steps per app

Your ads do not link to the app store — they link to your own service, which remembers the click and forwards the person to the store in the same request. Here is how to wire up an app end to end.

  1. 1 · ClickThe ad opens your linkThe click ID, IP address, user agent and campaign params are recorded, then the person is redirected to the App Store or Play Store.
  2. 2 · InstallThe app reports first launchOn first launch your app posts an install event with its device details and a stable install ID it generates once.
  3. 3 · MatchThe install is paired to a clickExact match on the click ID when the app can pass one, otherwise IP plus device fingerprint within the lookback window. Last touch wins.
  4. 4 · ReportThe conversion goes backInstalls, signups and purchases are forwarded to the Meta Conversions API or the TikTok Events API, so their bidding optimises on real converters.

Step by step

Adding an app

Everything but your app's own code happens in the dashboard — there's no service to configure or redeploy.

  1. Create the app in your dashboard

    Sign in and click New App. Fill in the store URLs, a fallback URL for unmatched clicks, and the pixel IDs and access tokens for whichever of Meta, TikTok and Pinterest you're running ads on (where to find those is covered in the three sections below) — access tokens are written straight to Secret Manager and never shown back to you.

    The dashboard generates the app's API key and shows it once. Copy it now — it's what your app sends on every request in the next step, and it can't be recovered afterward.

  2. Send events from the app

    Generate a UUID on first launch and keep it — that is the install ID that ties every later event to the same person. Post an install event on first launch and further events on each conversion.

    POST https://tapgo.web.app/v1/events
X-API-Key: YOUR_APP_KEY

{
  "app_id":     "APP_ID",
  "event_name": "install",
  "install_id": "STABLE_UUID",
  "event_id":   "UUID_PER_EVENT",
  "device": { "os": "ios", "os_version": "17.5", "model": "iPhone15,2" }
}

    Send the device fields with the first event. App HTTP clients often have user agents that carry no OS version, and without OS, version and model there is nothing to fingerprint — every install would come back organic.

    Call this endpoint from the device, not from your own backend. The IP address and user agent are taken from the request itself, because that is what the ad platforms match on.

TikTok

Pointing TikTok ads at your link

In TikTok Ads Manager, go to Tools → Events → Web Events → Set up pixel and choose Events API. Paste the pixel code into the app's TikTok fields in the dashboard, then use Settings → Generate Access Token for the access token field.

Create a normal Website campaign and use this as the landing page URL. TikTok substitutes the macros itself.

TikTok ad URL
https://tapgo.web.app/c/APP_ID?ttclid=__CLICKID__&campaign_id=__CAMPAIGN_ID__

Instagram and Facebook

Pointing Meta ads at your link

In Meta Events Manager, choose Connect data → Web and create a pixel. Paste the pixel or dataset ID into the app's Meta fields in the dashboard, then use Settings → Conversions API → Generate access token for the access token field.

Run ads with a website destination. Meta appends its own click ID to the URL automatically.

Meta ad URL
https://tapgo.web.app/c/APP_ID?platform=meta&campaign_id={{campaign.id}}&campaign_name={{campaign.name}}&adset_id={{adset.id}}&adset_name={{adset.name}}&ad_id={{ad.id}}&ad_name={{ad.name}}

Why website campaigns rather than app-install campaigns? Your ad's destination is a web URL — your own service. App-install campaigns link straight to the stores, which skips the click record entirely and leaves nothing to attribute against.

Pinterest

Pointing Pinterest ads at your link

In Pinterest Ads Manager, go to Conversions → Conversion tools for the ad account you're running under and generate an access token there. Pinterest scopes conversions to the ad account itself rather than a separate pixel, so paste the ad account ID and access token into the app's Pinterest fields in the dashboard — not a pixel ID.

Run a normal Website conversion campaign and use this as the destination URL. Pinterest appends its own click ID (epik) to the URL automatically.

Pinterest ad URL
https://tapgo.web.app/c/APP_ID?platform=pinterest&campaign_id={campaignid}&campaign_name={campaign_name}&adset_id={adgroupid}&adset_name={ad_group_name}&ad_id={creative_id}

Turn Test Mode off before launch. Pinterest validates and discards every event sent with it on — there's no error, so a Pinterest section left in test mode quietly drops every real conversion rather than failing loudly.

Optional

Tagging an influencer or creator

Add i= to any ad link to tag who's driving it — lowercase letters, digits, _ and -, up to 32 characters. It's independent of the network macros above: the same link, with a different i= value, works for every creator you work with. Anything that doesn't match is dropped rather than recorded, the same as an unfilled ad-platform macro.

Tagged ad URL
https://tapgo.web.app/c/APP_ID?platform=meta&i=INFLUENCER_SLUG

Verify

Checking it actually works

CheckHow
Click and redirectOpen your ad URL on a phone. It should land on the right store, and a click record should appear in the datastore.
Install matchedInstall and open the app. The response to its install event reports "attributed": true along with the platform and match type.
Platform receivingFor Meta and TikTok, put a code from the platform's Test Events tool into the app's test_event_code, fire an event, watch it arrive, then clear the code for production. Pinterest has no test code — flip its Test Mode checkbox on instead, verify the event, then flip it back off.
Anything failingThe dashboard's activity tab lists recent delivery failures with the error the platform returned.

Still deciding?

The FAQ covers how matching works without an SDK, how accurate it is, and what happens to personal data.

Read the FAQ