Playable Ads for Mobile Apps

Playable ads are an interactive video ad that allow mobile app advertisers to offer a short preview of their app before a person chooses 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 “tap to try” tip (but 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

  • The file size should be less than 2MB.
  • The file name extension should be html or htm.
  • The playable game must be in the game. Do not use a binary for the game.
  • The playable game must be in portrait mode.
  • The playable game must have a responsive design to support multiple types of devices in different resolutions.
  • All binary assets, scripts, and style sheets (CSS) must be in the file. Convert all binary assets to base64 encoded strings and add the strings to the HTML file.
  • The playable game must not require the Mobile Rich Media Ad Interface Definitions (mraid.js).
  • The payable game must not make any HTTP request.
  • The playable code in the ad must use the JavaScript function FbPlayableAd.onCTAClick() when the viewer interacts chooses the call-to-action.
  • The assets must not contain any JavaScript redirects.

Zip File

  • The zip file size should be less than 5MB.
  • The file name extension should be html or htm.
  • The index.html file is located at the root level and must be less than 2MB. We recommend the size to be 100Kb.
  • 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.
  • The playable game must be in portrait mode.
  • The playable game must have a responsive design to support multiple types of devices in different resolutions.
  • The playable game must not require the Mobile Rich Media Ad Interface Definitions (mraid.js).
  • The payable game must not make any HTTP request.
  • The playable code in the ad must use the JavaScript function FbPlayableAd.onCTAClick() when the viewer interacts chooses the call-to-action.
  • 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. In order 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.
    The ad set's 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 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:

  • A lead-in video to show in the News Feed.
  • 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"/>.
  • 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 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's 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.

Playable Ad Metrics JavaScript API

Use the Playable Ads Metrics JavaScript API to gain insights about how people interact with your playable ad. Call these APIs from the HTML file that contains your playable ad. The API can log various types of events that occur when people interact with your playable ad. Facebook receives the events, makes sure there is no sensitive user data, and forwards the events to your chosen URL.

The HTML can include JavaScript calls to the Playable Ads Metrics JavaScript API. If you want to get more insight into how people interact with your playable ad, include any of these optional calls in your HTML file.

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