Key Tracking Provider Deliverables
- PGP Key to deliver HMAC Key to tracking provider
- Tracking provider endpoint & credentials
- URL to link tracking provider site w/ parameters to redirect to Twitter publisher page
- Tracking provider Logo (150x60 or close), link to homepage or sign in page, and help doc link
- Application w/ Twitter auth and postback setup w/ Twitter API integration (app that sends the events to Twitter)
- Client App ID for Twitter Ads/API (numerical ID for app that sends events to Twitter)
- Test advertiser accounts (create these accounts on business.twitter.com)
- Timeline of delivery for tracking provider endpoint & credentials
- Timeline of delivery for self serve UI implementation
- Video walkthrough of campaign setup flow on tracking provider’s site
This document describes the integration details for the Mobile App Conversion Tracking (MACT) including the self-serve advertiser flow, authorization process, as well as details of how the real-time conversion and attribution flow works.
Permitted Use of Twitter Ads API
In order to enable tracking partner to implement MACT, Twitter may provide tracking provider with full technical documentation for the Twitter Ads API. However, despite any additional access or information provided via such documentation, tracking partner may use the Twitter Ads API only as expressly stated in this integration spec, and any other uses of the Twitter Ads API are prohibited.
Advertiser Self-Serve Overview
The MACT workflow goes through 3 major stages:
- Advertisers sign in to ads.twitter.com, and choose which tracking provider to work with from the list of partners in the conversion tracking home page.
- Advertisers will get redirected to the mobile measurement partner’s (MMP) website and set up their app tracking in the partner side. The partner will request the advertiser to authenticate through Twitter ads API, choose which mobile app and event type needs to be tracked, and the MMP will call back the Twitter Ads API to set up the tracking.
- Advertiser is redirected back to ads.twitter.com and configures individual event attribution windows if needed.
Advertiser Self Service Integration Details
- ads.twitter.com: Advertiser selects from list of supported MMP providers and is directed to the tracking providers login/signup page. Once logged in, the advertiser is directed straight to the Twitter setup page for sending conversion events.
- Direct navigation: Advertiser starts on the tracking providers site and finds the setup page for Twitter publisher setup.
- SDK setup: If the advertiser does not already have the tracking providers sdk, they must first integrate the SDK into their app.
Twitter Publisher Setup page
- On the tracking provider’s Twitter page, the advertiser is prompted to accept Twitter’s terms & if box is checked, then they can Sign in with Twitter OAuth and, if applicable, select the advertiser account to associate with the app(s) being setup for tracking.
Required Advertiser Legal Terms and Conditions
As an MMP, you are also required to pass through specific legal terms and conditions to advertisers using your product in connection with Twitter ad campaigns. Please reach out to your contact at Twitter to obtain the correct legal terms that you will pass on.
Before conversion events may be sent to Twitter for a given application, the mobile application needs to be configured for the advertisers Twitter ads account. If you cannot successfully onboard an application, you must not send conversion events for this application.
- Tracking provider will use GET accounts API call to see if i) the account is a registered Twitter advertiser and ii) if there are multiple ads accounts for that account. Note: The advertiser account id will be returned as a alphanumeric id.
- If advertiser is not a registered Twitter advertiser (no full accounts returned), the advertiser will be given a prompt to signup at ads.twitter.com.
- If multiple full accounts are returned, then an option to select multiple accounts is shown. If only 1 account is returned, no selection is shown and the setup will occur with the only ads account available. Note: The accounts should be shown with their display names and not their actual @handle
Once an account is selected, the advertiser chooses the apps and events for which to set up tracking. Note: that advertisers may choose to track different events for the same application across multiple advertiser accounts.
For each ads account in which tracking is to be set up for a new application the following steps must be performed:
- Register yourself as a tracking provider for this account if you haven’t already done so. Note: that there may be multiple registered providers but only one MMP can register for a single event.
- Register each application ID and event type to be tracked in the advertiser account. The application ID should be an app store identifier.
- If you cannot complete this step successfully, the application is already being tracked with another partner please notify the advertiser the existing MMP connection must be removed.
Multiple apps and multiple conversion events can be set up in a single advertiser account but individual API calls are needed for the following:
- Set up a new tracking provider configuration for an account
- Read tracking provider configuration
- Remove a tracking provider configuration for an account
- Set up app event tags for an account
- Read app event tags
- Delete app event tags
Set up a new tracking provider configuration for an account
Read tracking provider configuration
- GET accounts/:account_id/app_event_provider_configurations
- GET accounts/:account_id/app_event_provider_configurations/:id
Remove a tracking provider configuration for an account
Set up app event tags for an account
Read app event tags
Delete app event tags
For each app, an advertiser chooses which conversion events to send to Twitter for tracking. The conversion events Twitter supports for MACT will be indicated as templates - install, signup, purchase, open and others. Additional events can be added but will be grouped under Custom. Each event can be added through a standard setup process provided by tracking provider.
Once event setup is completed, a direct link should point to ads.twitter.com to the conversion event summary page where an advertiser can adjust window settings.
Ongoing configuration: advertisers will have a direct link to the tracking provider Twitter Publisher settings page that will enable adjustment of any existing postback configurations.
Postback Conversion Events
MMPs leverage the Twitter Ads API to send client conversion events.
- Setup & Authentication through Twitter Application-Only Auth
- Tracking provider will create a RESTful client and send the event information via a POST https request to Twitter Ads API. See the POST conversion_event real-time attribution endpoint for more details.
Device ID Hashing
Twitter will share base64 encoded keys for hashing the device ID. Tracking provider will base64 decode the key and feed it into the HMAC. In order to receive the key, please provide a public PGP to the Twitter contact so that it can be sent via an encrypted email.
Example HMAC base64 encoded key looks like:
Here is example format of Device IDs for iOS & Android: iOS:
The hmacs will also be base64 encoded. Here’s an example base64 encoded hmac looks for iOS & Android device IDs (using the above sample):
iOS Device ID hmac:
lPo51NIvOIzpIYeh2agqY9MaRGUg3S6omlWEORIUeWk= Android Device ID hmac:
Note: The specific number of characters for both the encoded HMAC and key could vary based on the input and the encoding so the specific number of characters.
Tracking provider should match on the encoded HMAC for Device ID.
For Limit Ad Tracking (LAT) users that opt out, please use zeros as the device ID and hash this value.