Measurement

Guides contents
  • MACT Integration

    • 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”

    Copy of Full Twitter Terms and Conditions for Mobile App Conversion Tracking (MACT)

    In connection with and subject to terms previously entered into by you and Twitter, and without limiting any such agreements, by accepting these terms and using Conversion Tracking for Mobile Apps (aka “MACT”), you agree that you will not use, or allow use by any third party of, any device level data, or any conversion, engagement, tracking or targeting data (collectively, “MACT Data”) that you or any Twitter-approved third party ads partner or other service provider collects, infers, derives, or obtains from or in connection with your Twitter advertising campaigns for any purpose, including, but not limited to, creating or appending end user profiles, including those associated with any mobile device identifier or other unique identifier connected to any end user, computer, browser or device. Further, you will not use MACT Data for repurposing, retargeting or redirecting, or to co-mingle MACT Data with other data or across other advertising campaigns, or for any other purpose. As the sole exception to the foregoing, you may use MACT Data in an aggregated and anonymized format only for optimizing the performance of your applicable Twitter advertising campaigns during the term of such applicable campaigns. You agree to destroy all MACT Data at the end of the applicable Twitter advertising campaigns, or when you no longer have a legitimate business need to retain it, but in no event longer than 6 months from the date you first receive any MACT Data.

    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.