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 are available on Facebook Newsfeed, Audience Network Interstitial, and Audience Network Rewarded video (see how the experience looks for each placement. Playable ad sets can also opt into Instagram Feed and Instagram Stories via the Placement Asset Customization feature, and the lead in video will deliver instead of the playable on these placements.

After you create a playable ad, people will see a lead-in video in feed with a controller overlay and a Tap to Try tip (Note: no lead-in video is shown for Audience Network placements). When a person taps on the video they will be taken to a full screen game demo to interact with. A call-to-action will appear when demo is complete or can also be shown throughout the demo experience.

Learn More

Specifications

Creating a Playable Ad

Uploading Your Playable Ads Using Ads Manager

Playable Ad Metrics JavaScript API

Troubleshooting

Specifications

This section contains the specifications for a playable ad:

Lead-in Video

Single HTML Page

Zip Files

Lead-In Video

  • All aspect ratios are supported, including Landscape, Square, and Vertical. Learn more about Facebook's standard video requirements.
  • Lead in videos are required when running playable ads, however the lead in video will only deliver as part of the playable experience on Newsfeed. On Audience Network placements, no lead in video is delivered.

Single HTML Page

  • Limit the file size to less than 2MB.
  • Use HTML5 for the playable game. Use the filename extension html or htm. Do not use a binary for the game.
  • Use a single file for the playable ad that contains all assets as part of that single HTML file. Convert all binary assets to base64 encoded strings and then add the strings to the HTML file.
  • Do not use the Mobile Rich Media Ad Interface Definitions framework (mraid.js) in the playable game.
  • The payable game must not make any HTTP requests.
  • Do not use the JavaScript function FbPlayableAd.onCTAClick() when the viewer chooses the call-to-action in the playable code.
  • Do not use JavaScript redirects in the assets.
  • Do not use dynamic asset loading through external network.

Zip File

  • Playable ads in a zip format works in all placements on Android and iOS.
  • Limit the zip file size to less than 5MB.
  • The file name extension should be html or htm.
  • Limit the file size of the index.html file to less than 2MB. We recommend the size to be 100Kb. Put the file at the root level.
  • Store all assets in the directory structure of the zip file. Load the resource into the index.html file by using a reference path to the asset must be relative to the index.html file. For example, if the asset is in ./assets/splash.png, then point to the file in the following way: <image src=”assets/splash.png”/>.
  • All assets can be in their native format.
  • All assets must be in the zip file and not in an external network location. Do not use the XMLHttpRequest object.
  • Use portrait mode for the playable game.
  • Use a responsive design for the playable game to work in multiple types of devices at different resolutions.
  • Do not use the Mobile Rich Media Ad Interface Definitions framework (mraid.js) in the playable game.
  • The payable game must not make any HTTP requests.
  • Do not use the JavaScript function FbPlayableAd.onCTAClick() when the viewer chooses the call-to-action in the playable code.
  • Do not use JavaScript redirects in the assets.
  • The assets must not contain any JavaScript redirects.

Creating a Playable Ad

This section shows you how to create a playable ad.

Single HTML Page

Your playable ad is built as an HTML file that is uploaded to your ad account. To create a playable ad using the process described below, you will need the following:

  • A lead-in video to show in the News Feed.
  • The HTML file contained in the ad.
  • A name to differentiate the ad from other playable ads in the ad account.
  • An access token. The access token can be generated with the Graph API Explorer tool.
  • The ad account ID.

After you create your single HTML page, you can upload your ad using an API or by using the Ads Manager.

The steps to create the playable ad using an API are:

  1. Create your campaign.
  2. Create an ad set.
  3. Upload your single HTML page to an ad account.
  4. Upload the introductory video to an ad account.
  5. Create the ad creative.
  6. Create the ad.

To Upload Using An API

  1. Create your campaign.
    curl -X POST \
      -F 'name=My Campaign Name' \
      -F 'objective=APP_INSTALLS' \
      -F 'status=PAUSED' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/campaigns

  2. Create an ad set.
    You can include the ad set in one or more of the following placements: * Facebook News Feed * Instagram Feed * Instagram Stories * Audience Network Classic * Audience Network's Rewarded Video. The playable version of the ad can run only in Facebook News Feed, Audience Network Classic, or Audience Network's Rewarded Video. If your ad set also uses other placements, you can choose to upload more than one video for the ad, and specify which video is to be used in each placement. The following example uses publisher_platforms, facebook_positions, and audience_network_positions.
    curl \
      -F 'name=Playables Ad Set Test' \
      -F 'promoted_object={"application_id":"<APP_ID>","object_store_url":"<APP_STORE_URL>"}' \
      -F 'optimization_goal=APP_INSTALLS' \
      -F 'billing_event=IMPRESSIONS' \
      -F 'bid_amount=2' \
      -F 'daily_budget=1000' \
      -F 'campaign_id=<CAMPAIGN_ID>' \
      -F '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"]
      }' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adsets

  3. Upload your HTML file to an ad account. Upload your HTML file to an ad account using the following CURL statement:
    curl \
      -X POST \
      -F "name=playable_sample_name" \
      -F "source=@<SOURCE_LOCATION>" \
      -F "access_token=<ACCESS_TOKEN>" \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adplayables
    If the call is successful, you will receive a JSON response containing your playable asset ID. This ID is used in a later step.

  4. Upload the introductory video file to an ad account. News Feed shows a video before redirecting to the Playable Ad.
    curl \
      -F 'source=@<SOURCE_LOCATION>' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph-video.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/advideos

  5. Create the ad creative.
    curl \
      -F 'name=Playable Ad Creative' \
      -F 'object_story_spec={
        "page_id": "<PAGE_ID>",
        "video_data": {
          "call_to_action": {
            "type":"INSTALL_MOBILE_APP",
            "value":{
              "application":<APP_ID>,
              "link":"<APP_STORE_URL>"
            }
          },
          "image_url": "<THUMBNAIL_URL>",
          "link_description": "try it out",
          "video_id": "<VIDEO_ID>"
        }
      }' \
      -F 'playable_asset_id=<PLAYABLE_ASSET_ID>' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adcreatives
    If the call is successful, you will receive a JSON response containing your creative ID. Use this ID in the next step.

  6. Create the ad.
    curl -X POST \
      -F 'name=Playable Ads Sample Name' \
      -F 'status=PAUSED' \
      -F 'adset_id=<AD_SET_ID>' \
      -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/ads

Zip File

Your playable ad is a compressed archive of files (.zip) that includes all the assets needed for the ad: Javascript, CSS, images, and sounds.

The playable ad must follow the specifications described in Ads Help Center, Specifications for Playable Ads.

If you will be compressing the playable ad source files into a .zip archive, you must follow these additional requirements:

  • You need A lead-in video to show in the News Feed.
  • Put an index.html file located at the root of the directory structure, ./index.html.
  • Other resources anywhere in the directory structure are referenced relative to index.html; for example, ./assets/splash.png is referenced as <image src="assets/splash.png"/>.
  • Use a unique name to differentiate the ad from other playable ads in the ad account.
  • Use an access token generated with the Graph API Explorer tool.
  • You need the ad account ID.

After you create your zip file, you can upload your ad using an API or by using the Ads Manager.

The steps to create the playable ad using an API are:

  1. Create your campaign.
  2. Create an ad set.
  3. Upload your zip file to an ad account.
  4. Upload the introductory video to an ad account.
  5. Create the ad creative.
  6. Create the ad.

To Upload Using An API

  1. Create your campaign.
    curl -X POST \
      -F 'name=My Campaign Name' \
      -F 'objective=APP_INSTALLS' \
      -F 'status=PAUSED' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/campaigns

  2. Create an ad set.
    The ad set placements can include one or more of Facebook News Feed, Instagram Feed, Instagram Stories, Audience Network Classic, and Audience Network's Rewarded Video. The playable version of the ad can run only in Facebook News Feed, Audience Network Classic, or Audience Network's Rewarded Video. If your ad set also uses other placements, you can choose to upload more than one video for the ad, and specify which video is to be used in each placement. The following example uses publisher_platforms, facebook_positions, and audience_network_positions.
    curl \
      -F 'name=Playables Ad Set Test' \
      -F 'promoted_object={"application_id":"<APP_ID>","object_store_url":"<APP_STORE_URL>"}' \
      -F 'optimization_goal=APP_INSTALLS' \
      -F 'billing_event=IMPRESSIONS' \
      -F 'bid_amount=2' \
      -F 'daily_budget=1000' \
      -F 'campaign_id=<CAMPAIGN_ID>' \
      -F '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"]
      }' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adsets

  3. Upload your zip file to an ad account. Upload your zip file to an ad account using the following CURL statement:
    curl \
      -X POST \
      -F "name=playable_sample_name" \
      -F "source_zip=@<SOURCE_LOCATION>" \
      -F "access_token=<ACCESS_TOKEN>" \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adplayables
    If the call is successful, you will receive a JSON response containing your playable asset ID. This ID is used in a later step.

  4. Upload the introductory video file to an ad account. News Feed shows a video before redirecting to the Playable Ad.
    curl \
      -F 'source_zip=@<SOURCE_LOCATION>' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph-video.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/advideos

  5. Create the ad creative.
    curl \
      -F 'name=Playable Ad Creative' \
      -F 'object_story_spec={
        "page_id": "<PAGE_ID>",
        "video_data": {
          "call_to_action": {
            "type":"INSTALL_MOBILE_APP",
            "value":{
              "application":<APP_ID>,
              "link":"<APP_STORE_URL>"
            }
          },
          "image_url": "<THUMBNAIL_URL>",
          "link_description": "try it out",
          "video_id": "<VIDEO_ID>"
        }
      }' \
      -F 'playable_asset_id=<PLAYABLE_ASSET_ID>' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adcreatives
    If the call is successful, you will receive a JSON response containing your creative ID. Use this ID in the next step.

  6. Create the ad.
    curl -X POST \
      -F 'name=Playable Ads Sample Name' \
      -F 'status=PAUSED' \
      -F 'adset_id=<AD_SET_ID>' \
      -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/ads

Uploading Your Playable Ad Using Ads Manager

You can upload your playable ad using Ads Manager.

To Upload Your Playable Ad Using Ads Manager

  1. Go to Ads Manager and create a new campaign.

  2. Click App Installs as your campaign objective.

  3. Choose an app you want to promote before uploading to playable asset. You can search for your app by name or by using the exact store URL. Make sure the promoted App is registered to your ad account. If you don't choose an app or if you try to use the store URL of an app you don't have permission to, you will encounter an error when uploading a playable asset.

  4. At the Ad Set under Placements, select Edit Placements. Then under Platforms you can select the Facebook Feeds placement, or under More Apps and Sites you can select the Audience Network Native, Banner and Interstitial placement or the Audience Network Rewarded Videos placement.

  5. At the Ad, under Format, select Single Image or Video. Under Media select Video/Slideshow. Check the option for Add a Playable Asset and under Create New, click the Upload Playable button. This will open a new window titled Playable Upload.

  6. In the Playable Upload dialog box, click the Upload button and upload your HTML single or zip file. Then click Done. If you see an error message during uploading, got to Troubleshooting for more information.

  7. Under Media, upload a video asset.

  8. Enter the text for your ad.

  9. Click Confirm when done.

After you successfully upload your playable asset, you should see a preview next to the upload dialog.

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.

Error: 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.

Error: 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.

Error: Uploaded Bundle Too Many SubAssets

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

Error: Upload Too Large

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

Error: 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.

Error: Uploaded File Contains Redirect to External Link

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

Error: Unsupported HTML For Playable Ad

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

Error: 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.

Error: Unsupported Placement For Playable Ads

You selected a placement that Playable Ads does not support. Select one of the supported placements:

  • Facebook News Feed
  • Audience Network Interstitial
  • Audience Network Rewarded Video
  • Instagram Feed-lead-in video only appears. No playable ad.
  • Instagram Stories-lead-in video only appears. No playable