Mobile App Promotion Comprehensive Guide

Requirements

  • App store identifiers for apps that you would like to set up ads for.

    • Examples for the Twitter app:
      • iOS bundle identifier: 333903271
      • Android package identifier: com.twitter.android
  • Image or Video App Card (can be created in Ads UI or Ads API)

  • Promoted Tweet using either Image or Video App Card (can be created in Ads UI or Ads API)

  • (Optional) Ad Account with conversion tracking set up

Overview

The Twitter Ads API provides a suite of products that enable advertisers to promote mobile apps via Twitter - this is known as Mobile App Promotion (MAP). You can target mobile users and drive cost-effective app installs, conversions and re-engagements at scale.

The overall steps of setting up a Mobile App Promotion campaign can be summarized as follows:

  1. Create a campaign.
  2. Create a line item (ad group) and associate the line item with an app.
  3. Select an audience to target via targeting criteria.
  4. Create a Video App Card as described in the video upload tutorial.
  5. Choose the Tweets to include in your campaign.
  6. Create more line items and Tweets as needed.
  7. Verify and start the campaign.
  8. Monitor results via Analytics API.

If you want to also target Twitter Audience Platform additional steps need to be performed to set up your campaign: Setting up for Twitter Audience Platform

Steps

  1. Create campaign

  2. Use the POST accounts/:account_id/campaigns or POST batch/accounts/:account_id/campaigns endpoint.

  3. Create a line item (ad group) and associate the line item with an app

  4. Use the POST accounts/:account_id/line_items or POST batch/accounts/:account_id/line_items endpoint to create a line item specifying one of the Mobile App Promotion objectives, associating it with the campaign ID returned from the previous step:

    objective

    APP_INSTALLS or APP_ENGAGEMENTS

    Use APP_INSTALLS to set up an “App installs” campaign and APP_ENGAGEMENTS to set up an “App re-engagements” campaign.

    entity_status

    PAUSED or DRAFT

    We always recommend to create campaigns in a non-running state and change status to ACTIVE when setup and verification is complete.

    bid_type and bid_unit

    See information below.

    These parameters will determine the bidding options.


    Bidding options
    (assumes bid_type=MAX and objective=APP_INSTALLS):

    Bidding option

    bid_unit

    charge_by

    CPAC - Cost Per App Click (MACT Not Required)

    APP_CLICK

    APP_CLICK

    OAB - Optimized action bidding (MACT Required)

    APP_INSTALL

    APP_CLICK

    CPI - Cost Per Install (MACT Required)

    APP_INSTALL

    APP_INSTALL


    Note: APP_ENGAGEMENTS campaigns are billed by app clicks by default and do not need to set bid_unit or charge_by settings.

    Finally the line item can be associated with the app being advertised so that the connection between campaign and app can also appear in the Twitter Ads UI. This does not impact serving of the ad but it is recommended for consistent experience.

    Call POST accounts/:account_id/line_item_apps to enable this association (and this will also enable the campaign to run on Twitter Audience Platform).

    twurl -H ads-api.twitter.com "/5/accounts/:account_id/line_item_apps" -X POST -d "os_type=IOS&app_store_identifier=333903271&line_item_id=:id_for_iOS_line_item"
    
  5. Select an audience to target via targeting criteria
  6. The most basic targeting usually used for MAP campaigns would be Platform targeting.

    Here are examples of getting and setting Platform targeting:

    twurl -H ads-api.twitter.com "/5/targeting_criteria/platforms"
    
    
    
    
    {
      "data": [
        {
          "name": "iOS",
          "targeting_type": "PLATFORM",
          "targeting_value": "0"
        },
        {
          "name": "Android",
          "targeting_type": "PLATFORM",
          "targeting_value": "1"
        },
        {
          "name": "BlackBerry phones and tablets",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "Mobile web on other devices",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "Desktop and laptop computers",
          "targeting_type": "PLATFORM",
          "targeting_value": "4"
        }
      ],
      "request": {
        "params": {}
      }
    }
    

    Adding the targeting criteria to iOS and Android line items:

    twurl -H ads-api.twitter.com "/5/accounts/:account_id/targeting_criteria" -X POST -d "targeting_type=PLATFORM&targeting_value=0&line_item_id=:id_for_iOS_line_item"
    
    twurl -H ads-api.twitter.com "/5/accounts/:account_id/targeting_criteria" -X POST -d "targeting_type=PLATFORM&targeting_value=1&line_item_id=:id_for_Android_line_item"
    

    Please be aware that MAP campaigns can leverage Tailored Audience for Mobile apps to target existing users or exclude them based upon the campaign needs. This would be done by pulling the audience ID from GET accounts/:account_id/tailored_audiences endpoint after filtering to audience_type=MOBILE audiences.

  7. Create a Video App Card as described in the video upload tutorial.
  8. Video App Card is one popular choice for advertising MAP campaigns on Twitter. Please see the video upload tutorial and come back to this guide when you create a Video App Card associated with your app store identifier.

  9. Choose the Tweets to include in your campaign
  10. If you have not created a Tweet containing the Video App Card from previous step, you can do it either via the POST accounts/:account_id/tweet endpoint or from our Ads UI. Here is an example of creating a tweet with a card:

    twurl -H "ads-api.twitter.com" "/5/accounts/:account_id/tweet" -d "nullcast=true&card_uri=card://2119368073444638719&text=MAP Ad"
    

    If you want to select an existing Tweet to use, you can find appropriate Tweets using the GET accounts/:account_id/scoped_timeline endpoint, which is the same as the list of tweets that appear in our Ads UI.

    twurl -H ads-api.twitter.com "/5/accounts/:account_id/scoped_timeline?trim_user=true&count=100&objective=APP_INSTALLS&scoped_to=none&sort_by=created_at-desc"
    

    Promote the Tweet by calling the POST accounts/:account_id/promoted_tweets endpoint.

    twurl -H "ads-api.twitter.com" "/5/accounts/:account_id/promoted_tweets" -d "line_item_id=:iOS_line_item_id&tweet_ids=:app_card_tweet_id"
    
  11. Create more line items and promoted additional Tweets as needed
  12. Additional line items may be useful for creating combinations of creative, targeting and bids. The previous steps should simply be created using the same campaign ID. Please check guidance about using multiple line items on this guide about Ad Groups.

  13. Verify and start the campaign
  14. The recommended best practice would be to create campaigns and line items with entity_status=PAUSED and update it to entity_status=ACTIVE whenever the campaign is completely set up and ready to be run (even if the start date is at a future time). This can be done with PUT accounts/:account_id/line_items/:line_item_id and PUT accounts/:account_id/campaigns/:campaign_id.

    Tip: One creative verification step would be to create draft tweets and use the POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id endpoint to push a notification to a device for an on-device preview of how the promoted tweet will display.

  15. Monitor results via Analytics API

Please see our Asynchronous Analytics Guide for information on how to fetch analytics data related to a MAP campaign. Please note that gathering segmentation data displayed in our Ads UI will require calling the analytics endpoint with different segmentation_type parameters.

Mobile conversion metrics can be fetched with entity_groups=MOBILE_CONVERSION as shown in this pair of queries needed to get all data for Twitter and Twitter Audience Platform data:

twurl -H ads-api.twitter.com "/5/stats/jobs/accounts/:account_id" -X POST -d "entity_ids=:Android_campaign_id&entity=CAMPAIGN&start_time=2019-04-24&end_time=2019-04-26&granularity=TOTAL&metric_groups=MOBILE_CONVERSION&segmentation_type=DEVICES&platform=1&placement=ALL_ON_TWITTER"
twurl -H ads-api.twitter.com "/5/stats/jobs/accounts/:account_id" -X POST -d "entity_ids=:Android_campaign_id&entity=CAMPAIGN&start_time=2019-04-24&end_time=2019-04-26&granularity=TOTAL&metric_groups=MOBILE_CONVERSION&segmentation_type=DEVICES&platform=1&placement=PUBLISHER_NETWORK"

Tip: Use the Active Entities endpoint to drive your algorithm of fetching data and only fetch the data you need, and check the overall Analytics Best Practices when writing code to fetch data.

Setting up for Twitter Audience Platform

The steps for setting up a campaign that also serves to the Twitter Audience Platform contain several additional steps:

  1. Create a campaign.
  2. Create a line item (ad group) and associate the line item with an app.
    1. The line item should have
    2. objective=APP_INSTALLS
    3. product_type=PROMOTED_TWEETS
    4. placements=TWITTER_PROFILE,TWITTER_TIMELINE,PUBLISHER_NETWORK
    5. advertiser_domain= (required parameter)
    6. categories= (required parameter)
    7. Select an audience to target via targeting criteria. Note: Some targeting is unavailable when placements include PUBLISHER_NETWORK as described in the general Twitter Audience Platform setup guide
    8. POST accounts/:account_id/app_lists can be used to create a list of apps and you can use this list with the EXCLUDE_APP_LIST targeting type which will prevent your ad from appearing within those apps.
    9. Create an Image App Card.
    10. Choose the Tweets to include in your campaign.
    11. Upload appropriately sized creative assets (accepted dimensions can be found under Creative Types section) with the method described in the Media Library guide.
    12. Appropriately sized media will appear in the GET accounts/:account_id/account_media endpoint response, which can be used to display available creative assets to users.
    13. An account media ID from the account_media endpoint is needed to pass to the POST accounts/:account_id/media_creatives endpoint which will create the relationship between line item and account media ID.
    14. Create more line items, Tweets and media creatives as needed.
    15. Verify and start the campaign.
    16. Monitor results via Analytics API.