Instant Experiences

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

Before You Start

To create and manage Instant Experiences, you need:

• The pages_manage_ads permission
• The pages_read_engagement permission
• The pages_show_list permission
• To be able to perform the ADVERTISE task on the Page

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.

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/v21.0/<PAGE_ID>/canvases

Elements

Delete an Element

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

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<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).

curl -G \
  --data-urlencode 'fields=[ 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<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).

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/v21.0/<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.

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/v21.0/<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.

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.

curl \
  -F 'is_published=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<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/v21.0/act_<AD_ACCOUNT_ID>/adcreatives

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:

• Quickstart guide
• Initialization reference

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:

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

Iframe Preview API

You can generate a preview an Instant Experience by calling the previews API which returns an iframe, similar to the ad previews API:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v18.0/<CANVAS_ID>/preview
  
Open In Graph API Explorer

The API returns something like this, which can be viewed by embedding the returned iframe element in HTML:

{
"data": [
    {
      "body": "<iframe src=\"https://www.facebook.com/ads/canvas/preview?d=AQKELApdJxoVp2f3PHl8-pRtYuAh4-_eDupMDbh-pS9zde_EFxckhYQCXu7NYUi4PhhBA7uskIo2Ys3IjIVNGZiS&t=AQKGOPqGI-NWcv1YKbA\" width=\"405\" height=\"720\" scrolling=\"yes\" style=\"border: none;\"></iframe>"
    }
  ],
  "__www_request_id__": "AQnyr47Qp2r5M-ISqSiMgrw"
}

Facebook SDK

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:

• Quickstart guide
• Initialization reference

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:

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
Open In Graph API Explorer

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
Open In Graph API Explorer

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

• Facebook Ads Guide: Instant Experience Specs
• Business Help Center: Learn about Instant Experience