Instant Experiences

Instant Experiences are a full-screen, post-click ad destination that loads nearly instantaneously from ads in News Feed.

If you see any mentions of canvas in the API, it is a reference to Instant Experiences. Canvas was the previous name of this format.

Before You Start

To create and manage Instant Experiences, you need:

Limitations

  • You can only update an unpublished Instant Experience.
  • The Instant Experiences API is available for Instagram on a limited basis.
  • Ads using Instant Experiences are not supported for Facebook Stories.

Create

To create an Instant Experience, you will need the ID of a Facebook Page (PAGE-ID) and any elements, such as photos, buttons, and text, you wish to include in your experience.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'background_color' => 'FFFFFF',
  'body_element_ids' => array(<CANVAS_PHOTO_ID>),
  'is_hidden' => false,
  'is_published' => false,
  'name' => 'Canvas Name',
);

$data = Api::instance()->call(
  '/' . <PAGE_ID> . '/canvases',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/canvases

Elements

NameDescription

Button

A button within an Instant Experience. The button_style field is required.

Carousel

A carousel for the Instant Experience.

Footer

A footer for the Instant Experience.

Header

A header for the Instant Experience.

Photo

A photo within an Instant Experience. You should provide a PHOTO-ID for a photo uploaded to a Facebook Page.

Product List

A list of products for an Instant Experience.

Product Set

A set of products from a Dynamic Ads product catalog that are displayed in an Instant Experience.

Store Locator

A store locator within an Instant Experience.

Text

The text and its styling displayed within an Instant Experience.

Video

A video within an Instant Experience. You should provide a VIDEO-ID for a video uploaded to a Facebook Page.

Delete an Element

To delete an element, send a DELETE request with the ID of the element you wish to delete.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ELEMENT_ID>

Get an Existing Instant Experiences

To get information about an existing Instant Experience, you will need the ID of the Instant Experience (CANVAS-ID).

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'body_elements',
    'canvas_link',
    'id',
    'is_hidden',
    'is_published',
    'name',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ID>

Get All Instant Experiences for a Page

To get information about all existing Instant Experiences for a Facebook Page, you will need the ID of the Page (PAGE-ID).

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'background_color',
    'body_elements',
    'canvas_link',
    'id',
    'is_hidden',
    'is_published',
    'last_editor',
    'name',
    'owner',
    'update_time',
  ),
);

$data = Api::instance()->call(
  '/' . <PAGE_ID> . '/canvases',
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "background_color", 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "last_editor", 
    "name", 
    "owner", 
    "update_time" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/canvases

Update an Instant Experience

To update an Instant Experience, the experience must be unpublished and you will need the ID of the Instant Experience (CANVAS-ID) and any element IDs you want to update.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'background_color' => 'FFFFFF',
  'body_element_ids' => array(<CANVAS_PHOTO_ID>),
  'is_hidden' => false,
  'is_published' => false,
  'name' => 'Canvas Name',
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ID>

Use a Template

You can use a template as quick way to create an Instant Experience for a specific business goal. The layout for each template is fixed, however you can replace default content with your own images, videos, products, text, and links.

API Template NameTemplate IDDescription

Get New Customers

133471657203838

Drive conversions with a mobile landing page that encourages action. Customer Acquisition template in the Ads Manager.

Showcase Your Business

1063217037112304

Give people an engaging way of exploring your brand, product or service. Storytelling template in Ads Manager.

Sell Products (Without Catalog)

424787857903852

Create a mobile shopping experience by uploading your product information instead of using a catalog. Sell Products (Without Catalog) template in Ads Manager.

Sell Products: Lifestyle Layout

1369752616394017

Let people explore your products in action by featuring them in photos.Lookbook template in Ads Manager.

Sell Products: Grid Layout

1932289657009030

Use your product catalog to create an experience that lets people shop straight from their mobile device. Storefront template in Ads Manager.

Collect Contact Info

1309632222469576

Use a form to build a list of prospective customers. Only available via the API.

AR Experience

The AR Experience template is only available via the Ads Manager.

Get Element Types for a Template

Step 1. Get the Document Information for the Template

Send a GET request to determine which elements are needed for a particular template, Get New Customers in the following example.

curl -i -X GET \
 "https://graph.facebook.com/VERSION/133471657203838?fields=document&access_token=ACCESS-TOKEN"

Example Response

{
  "document": {
    "name": "Get New Customers",
    "id": "397246414010297"
  },
  "id": "133471657203838"
}

Step 2. Get the Element Types

Use ID for the document field to get specific elements available for a particular template.

curl -i -X GET \
 "https://graph.facebook.com/VERSION/397246414010297?fields=body_elements&access_token=ACCESS-TOKEN"

The list returned show element types that are available for use in the Get New Customers template.

    {
  "body_elements": [
    {
      "name": "Cover Image or Video",
      "element_type": "PHOTO",
      "id": "397271930674412"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271920674413"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271910674414"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271914007747"
    },
    {
      "name": "Carousel",
      "element_type": "CAROUSEL",
      "id": "397271940674411"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271917341080"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271924007746"
    }
  ],
  "id": "397246414010297"
}

Publish

To publish your Instant Experience ad send a POST request to your Instant Experience ID (CANVAS-ID) and set the is_published field to true.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'is_published' => true,
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'is_published=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ID>

Create an Ad Creative

Create an ad creative using the link for an existing Instant Experience (CANVAS-LINK).

curl -X POST \ -F 'image_hash="<IMAGE_HASH>"' \ -F 'object_story_spec={ "page_id": "<PAGE_ID>", "link_data": { "image_hash": "<IMAGE_HASH>", "link": "<CANVAS_LINK>", "name": "Creative message", "call_to_action": { "type": "LEARN_MORE" } } }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v12.0/act_<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'image_hash' : '<imageHash>', 'object_story_spec' : {'page_id':'<pageID>','link_data':{'image_hash':'<imageHash>','link':'<canvasURI>','name':'Creative message','call_to_action':{'type':'LEARN_MORE'}}}, }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'image_hash' => '<imageHash>', 'object_story_spec' => array('page_id' => '<pageID>','link_data' => array('image_hash' => '<imageHash>','link' => '<canvasURI>','name' => 'Creative message','call_to_action' => array('type' => 'LEARN_MORE'))), ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'image_hash': '<imageHash>', 'object_story_spec': {'page_id':'<pageID>','link_data':{'image_hash':'<imageHash>','link':'<canvasURI>','name':'Creative message','call_to_action':{'type':'LEARN_MORE'}}}, } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdCreative() .setImageHash(\"<imageHash>\") .setObjectStorySpec( new AdCreativeObjectStorySpec() .setFieldLinkData( new AdCreativeLinkData() .setFieldCallToAction( new AdCreativeLinkDataCallToAction() .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_LEARN_MORE) ) .setFieldImageHash(\"<imageHash>\") .setFieldLink(\"<canvasURI>\") .setFieldName(\"Creative message\") ) .setFieldPageId(\"<pageID>\") ) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ image_hash: '<imageHash>', object_story_spec: {'page_id':'<pageID>','link_data':{'image_hash':'<imageHash>','link':'<canvasURI>','name':'Creative message','call_to_action':{'type':'LEARN_MORE'}}}, })

Once the ad creative is ready, you can then go on to create the ad group, ad set, and ad campaign.

Instant Experiences Ads Dialog

You can use the Instant Experiences Ads Dialog to provide the Facebook Instant Experiences ad-creation user interfaces in your website. For details about the UI component, see Dialogs.

Set up the Facebook SDK for JavaScript, see:

The JavaScript SDK relies on the logged in user's permissions to create an Instant Experience. If the user does not have the necessary permissions to create an Instant Experience for the supplied page and business, the dialog will show an error. To ensure no errors, the user must be in the business and have 'create ads' permissions for the page.

Then trigger the dialog:

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_builder',
  business_id: '<BUSINESS_ID>',
  page_id: '<PAGE_ID>'
}, function(response) {
  // callback
});

You can provide these settings for the plugin:

NameRequiredDescription

display

Yes

Necessary parameter with set value of popup

method

Yes

Necessary parameter with set value of instant_experiences_builder

business_id

Yes

Your business ID

page_id

Yes

Page ID you want to associate the Instant Experience with

canvas_id

No

ID of Instant Experience you want to edit

The parameter canvas_id is optional and is meant to allow a user to edit or preview an existing Instant Experience. If an Instant Experience is complete, you cannot edit it. To preview an Instant Experience, we recommend using the Instant Experiences Preview Dialog.

The plugin provides this response on success:

{
  "success": true,
  "id": "CANVAS-ID"
}

The ID returned is a published Instant Experience. You can now use it in ad campaigns. If no response or an undefined response is returned, that means a viewer closed the dialog before finishing the Instant Experience. The user may have saved the Instant Experiences, but not finished it. You can pull all Instant Experiences that belong to a page using the Graph API to see if there are any unfinished experiences.

Preview an Instant Experience

You can use this dialog to provide a preview of an Instant Experience as someone on Facebook would see it from your website. For details about the UI component, see Dialogs.

Set up the Facebook SDK for JavaScript, see:

The JavaScript SDK relies on the logged in user's permissions to create an Instant Experience. If the user does not have the necessary permissions to view the Instant Experience, the dialog shows an error.

Then trigger the preview dialog:

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_preview',
  canvas_id: 'CANVAS-ID'
});

You can provide these settings for the plugin:

NameRequiredDescription

display

Yes

Necessary parameter with set value of popup

method

Yes

Necessary parameter with set value of instant_experiences_preview

canvas_id

Yes

ID of Instant Experience you want to preview

Preview an Ad

If you want to preview your ad before publishing it, you can trigger a notification sent to your phone:

curl \
-F 'user_ids=[USER_ID]' \
-F 'access_token=ACCESS_TOKEN' \
https://graph.facebook.com/VERSION/CANVAS_ID/preview_notifications

Create Audiences for Instant Experiences

To create an engagement audience, an audience of people who have engaged with an Instant Experience, set the object_id parameter of the rule field to the Instant Experience ID (CANVAS-ID) in your POST /act_AD-ACCOUNT/customaudiences call.

People who opened the Instant Experience

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who opened this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_document_open"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

People who clicked any links in the Instant Experience

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who clicked any links in this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_element_click"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

For more information about custom audiences, see Custom Audience, Reference.

Instant Experiences and Instagram Ads

Implementing Instant Experiences with Instagram uses the same API calls you use for Instant Experience on Facebook. Note there are limitations when you use Instagram and Instant Experiences:

  • Placements - Available for Instagram Feed and Instagram Stories. If you select Instagram Stories, you should select this as your exclusive ads placement.
  • Instant Experience Elements - Fully supports headers and product sets.

We partially support these Instant Experience elements on Instagram:

  • Footer - No swipe to open in clients this renders as Tap to open.
  • Carousel - No photos that link to another Instant Experience; in the client appears as a non-clickable link. For photos and videos, no fit to height, no fit to width or tilt to pan; this renders as fit to width.
  • Button - Cannot link to another Instant Experience or to the App Store.
  • Text - No RTL language support.
  • Video - No 360 videos.
  • Store Locators - Not supported.

Ad Insights

See Ad Insights for an overview and descriptions for available metrics.

See Also