Measurement

Guides contents

MACT Integration

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

Goal

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

Fig. 1 Self-serve sequence diagram

As described in Figure 1, 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 tracking home page.
  • Advertisers will get redirected to the tracking provider’s website, and setup their app tracking in the partner side. The partner will request the advertiser to authenticate through Twitter ads API, and choose which mobile app and event type needs to be tracked, and the partner website 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

Initial Setup

  • ads.twitter.com: Advertiser selects from list of supported conversion tracking 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.

Publisher New User Experience w/ checkbox default unchecked and hidden “Sign In with Twitter” button

Publisher New User Experience w/ checkbox checked & display of “Sign in with Twitter”

Required Advertiser Legal Terms and Conditions

As a MACT partner, 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.

Sign in only possible if terms accepted.

iFrame window for OAuth & redirect.

Onboarding

Before conversion events may be sent to Twitter for a given application this application needs to be onboarded. 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 account(s) is(are) 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.
  • Register each application ID and event type to be tracked in the advertiser account.
  • If you cannot complete this step successfully the application is already being tracked with another partner please contact the advertiser for more information.

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

Error codes: NO_PROVIDER_AVAILABLE_FOR_THIS_CLIENT_APPLICATION

Read tracking provider configuration

Error codes: ENTITY_NOT_FOUND

Remove a tracking provider configuration for an account

Error codes: ENTITY_NOT_FOUND

Set up app event tags for an account

Error codes: NO_MORE_THAN_ONE_PROVIDER_EACH_APP_ID

Read app event tags

Error codes: ENTITY_NOT_FOUND

Delete app event tags

Error codes: TAG_NOT_FOUND

Completion

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. Sending all conversion events to Twitter will be the only option available.

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.

Conversion Event Summary Page

Individual Event Setting Page

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

Tracking provider needs to construct a RESTful client Twitter application to talk to Twitter API and assemble the information in the format of a client event.

  1. Setup & Authentication through Twitter Application-Only Auth
  2. Tracking provider will create a RESTful client and send the event information via a POST https request to Twitter API. See the POST conversion_event real-time attribution endpoint for more details.

For partners who want to test or to query on attribution events without writing to Twitter, use the GET conversion_attribution endpoint. This endpoint functions exactly the same as the POST endpoint, except that it does not record a conversion event at Twitter when making the call.

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: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM=

Here is example format of Device IDs for iOS & Android: iOS: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android: b5bf2122961b3595

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: nRlfZUpf7JzNcjeqTNb9xXb8G0hrXDIMWXyDrc4yTms=

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.