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:

Limitations

  • Lead-in videos are not shown for Audience Network placements.
  • Only lead-in videos are shown for Instagram placements.
  • Only the App Installs objective is the supported for playable ads.

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:

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.

ErrorPossible Fix

Invalid App ID

This error appears when the App section is not selected, or does not have permission to create ad for this app. Select the App section and check that you have the correct permissions to create the ad for this app.

Missing CTA Click Function Call

The playable code does not use the JavaScript function FbPlayableAd.onCTAClick() for the call to action. Use this function in your CTA code.

Uploaded Bundle Too Many SubAssets

Your zip file contains more than 100 files. Use less than 100 files.

Upload Too Large

Your zip file is larger than 5MB. Reduce the size of zip file to less than 5MB.

Uploaded File Is Too Large

Your single HTML file is larger than 2MB or the index.html file is larger than 2MB. Reduce the size of the file.

Uploaded File Contains Redirect to External Link

One or more assets contains JavaScript redirect code. Remove the code.

Unsupported HTML For Playable Ad

You will see this error if the anti-virus scan has failed.

Unsupported Objective For Playable Ads

You selected an objective that is not supported. Only App Installs is the supported objective for playable ads. Before you create your ad, select the App Installs objective in Ads Manager.

Unsupported Placement For Playable Ads

You selected a placement that Playable Ads does not support.