Playable Ads for Mobile Apps

Playable ads are interactive ads that allow mobile app advertisers to offer short previews of their apps before people choose to download it. Playable ads have a lead-in, or introductory, video with a Tap to Try message. When a person taps on the video they will be taken to a full screen demo of the game that they can interact with. The ad can display a call-to-action throughout the demo or when the demo is complete.

Playable ads are available on:

• Facebook Stories
• Facebook Newsfeed
• Audience Network Interstitial
• Audience Network Rewarded
• Instagram Feed and Instagram Stories via the Placement Asset Customization feature

Limitations

• Lead-in videos are not shown for Audience Network placements.
• Only lead-in videos are shown for Instagram placements.
• Playable ads are only available with the App Installs objective.

Upload a Playable Ad using the Ads Manager instead of the API.

Specifications

Visit the Playable Ads article in the Ads Help Center to learn about the specifications for Lead-in videos, and HTML and zip files.

Create a Playable Ad Using the API

Requirements

You will need the following:

• A lead-in video.
• An HTML file or zip file.
• A Page ID of a Facebook Page associated with the ad.
• An ad account ID.
• An ad campaign ID for the playable ad.
• A system user access token.

Step 1. Create an Ad Set

Send a POST request to the /act_AD_ACCOUNT_ID/adsets endpoint to create an ad set.

You can upload more than one video for your ad and specify which video to use for a specific placement when you have multiple placements. The following example specifies multiple placements using publisher_platforms, facebook_positions, and audience_network_positions.

Formatted for readability.

curl -X POST "https://graph.facebook.com/act_AD_ACCOUNT_ID/adsets
  ?name=AD_SET_NAME
  &access_token=ACCESS_TOKEN
  &bid_amount=2
  &billing_event=IMPRESSIONS
  &campaign_id=AD_CAMPAIGN_ID
  &daily_budget=1000
  &optimization_goal=APP_INSTALLS
  &promoted_object={  
    'application_id':'APP_ID',
    'object_store_url':'APP_STORE_URL'
    }
  &targeting={
    'device_platforms': ['mobile'],
    'geo_locations': {countries:['US']},
    'publisher_platforms': ['facebook','audience_network'],
    'facebook_positions': ['feed'],
    'audience_network_positions': ['rewarded_video','classic'],
    'user_os': ['ANDROID']
    }"

On success, a playable ad set ID will be returned.

Step 2. Upload an HTML or Zip File to Your Ad Account

Send a POST request to the /act_AD_ACCOUNT_ID/adplayables endpoint to upload your playable ad file. Use the source parameter for an HTML file or the source_zip parameter for a zip file.

Formatted for readability.

curl -X POST "https://graph.facebook.com/act_{your-ad-account}/adplayables
  ?name={your-playable-ad-name}
  &source=@{your-source-location}  
  &access_token={your-system-access-token}"

On success, a playable asset ID will be returned.

Step 3. Upload a Lead-in Video File to an Ad Account

Send a POST request to the /act_AD_ACCOUNT_ID/advideos endpoint to upload a lead-in video. Use the source parameter for an HTML file or the source_zip parameter for a zip file.

Formatted for readability.

curl -X POST "https://graph-video.facebook.com/act_AD_ACCOUNT_ID/advideos
  ?source=@SOURCE_LOCATION
  &access_token=AD_ACCOUNT_ID"

On success, a lead-in video ID will be returned.

Step 4. Create an Ad Creative.

Send a POST request to the /act_AD_ACCOUNT_ID/adcreatives endpoint to create an ad creative.

Formatted for readability.

curl -X POST "https://graph.facebook.com/act_AD_ACCOUNT_ID/adcreatives
  ?name=PLAYABLE_AD_CREATIVE_NAME
  &access_token=ACCESS_TOKEN
  &playable_asset_id=PLAYABLE_ASSET_ID
  &object_story_spec={
    'page_id': 'PAGE_ID',
    'video_data': {
      'call_to_action': {
        'type':'INSTALL_MOBILE_APP',
        'value':{
          'application':'APP_ID',
          'link':'LINK_URL'
        }
      },
      'image_url': 'THUMBNAIL_URL',
      'link_description': 'CTA_MESSAGE',
      'video_id': 'LEAD_IN_VIDEO_ID'
    }
  }"

On success, an ad creative ID will be returned.

Step 5. Create an Ad

Send a POST request to the /act_AD_ACCOUNT_ID/ads endpoint.

Formatted for readability.

curl -X POST "https://graph.facebook.com/act_AD_ACCOUNT_ID/ads
  ?name=PLAYABLE_AD_NAME
  &access_token=ACCESS_TOKEN
  &adset_id=PLAYABLE_AD_SET_ID
  &creative={'creative_id':'PLAYABLE_AD_CREATIVE_ID'}
  &status=PAUSED"
  

Once testing the ad is complete, change the status to ACTIVE.

Troubleshooting

When you upload playable assets while creating a playable ad, you may see an error message that indicates your playable asset is invalid.

The following are the common errors you may receive and tips on how you can correct them.