Collection Ads

This ad format includes an Instant Experience, formerly known as Canvas, and it makes it easier for people to discover, browse and purchase products and services from their mobile device in a visual and immersive way. Your ad in feed will feature four products under a hero image or video that opens into a full-screen Instant Experience when someone interacts with your ad. There are two types of collection ads: image-based and video-based.

We recently announced that Canvas is renamed to Instant Experiences, to better reflect the value it delivers for people as a full-screen, post-click destination that loads nearly instantaneously from ads in News Feed. We will soon update the API to reflect this change; in the meantime, consider all references of “canvas” to represent Instant Experience.

You can create an ad with the collection format by building an Instant Experience. Start with a template or choose your own customized layout. For background, see Ads Help Center, Instant Experience.

You can also include Facebook's ad creation user interfaces for the collection format in your website with the JavaScript SDK. Learn more about the Collections Ads Dialog below.

For general information on using collections, see:

• Facebook for Business: Collection
• Create a collection with a product catalog
• Create a collection without a product catalog

Collection ads for Facebook Stories is not supported.

Objectives and Placements

You can use collection ads with the following objectives:

• Traffic
• Conversions
• Product Catalog Sales - When you use collections with a product set.
• Store Visits - Available on a limited basis to whitelisted partners and advertisers

Supported formats and placements:

• You can also use slideshow videos, however this format is only available for the Traffic and Conversions objectives and only compatible with mobile placements.
• Collection ads are available on mobile devices for Facebook news feed and with some limited features on Instagram feed. You can see more about those limitations at Instagram and Instant Experiences. You can also more about objectives and placements for your ads at Ads Help Center, About advertising objectives and Ads Help Center, About placements.

Collection Ads from Product Sets

Before you create a collection ad, provide ad creative and an Instant Experience. You must provide at least four elements that represent photos or four elements representing products with product tags. Child photo elements in a carousel element are also valid.

Create collection ads from your Dynamic Ads catalog. A collection ad has four products under a hero image or video and displays in mobile News Feed. You can use slideshow videos with this feature.

The ad appears in News Feed, and people can see more in a fullscreen experience that opens when they tap the ad.

To use a product set, you should be familiar with Dynamic Ads and already have a product catalog set up. See Dynamic Ads and Dynamic Ads, Product Catalog for more information.

Create Ads

Prior to v3.0 of Marketing API, every time you created a collection ad, Facebook created an Instant Experience in the background. This limited your access to the underlying Instant Experience; you could not use it to retarget audiences with Instant Experiences engagement audiences. As of 3.0, when you create a collection ad from product sets, you must also explicitly create an Instant Experience with the correct elements. When you use this Instant Experiences in a collection ad, Facebook automatically generates the collection ad. Your Instant Experience should contain:

• An image, known as Canvas Photo or video, see Canvas Video, Reference
• A product set with show_in_feed set to true. See Canvas Product Set, Reference
• A footer, see Canvas Footer, Reference

For example, you first create an Instant Experience, such as one with an image:

curl \
  -F 'canvas_photo={ 
    "photo_id": "<PHOTO_ID>", 
  }' \
  https://graph.facebook.com/VERSION/<PAGE_ID>/canvas_elements

Or create an Instant Experience with a video:

curl \
  -F 'canvas_video={ 
    "video_id": "VIDEO_ID", 
  }' \
  https://graph.facebook.com/<VERSION>/<PAGE_ID>/canvas_elements

Then you create a canvas_product_set with a product_set_id from your product catalog. You must set show_in_feed to true to create a collection ad:

curl \
  -F 'canvas_product_set={ 
    "max_items": 50,
    "product_set_id": "<PRODUCT_SET_ID>",
    "item_headline": "{{product.name}}",
    "item_description": "{{product.current_price}}"
    "image_overlay_spec": {
      "overlay_template": "pill_with_text",
      "text_type": "price",
      "text_font": "dynads_hybrid_bold",
      "position": "top_left",
      "theme_color": "background_e50900_text_ffffff",
      "float_with_margin": true,
    },
    "retailer_item_ids": [0, 0, 0, 0],
    "show_in_feed": true
  }' \
  https://graph.facebook.com/<VERSION>/<PAGE_ID>/canvas_elements

Note in the example above that item_headline, item_description, image_overlay_spec and retailer_item_ids are all optional fields. In the past, you provided these in the same call to create the collection ad and underlying Instant Experience asset. Now you provide them in this call.

In image_overlay_spec provide any required fields, see Marketing API, Reference, Ad Creative Link Data, Image Overlay Spec.

Then you should provide a footer, for example:

curl \
  -F 'canvas_button={ 
    "rich_text": {
      "plain_text": "See more at www.abc.com"
    },
    "open_url_action": {
      "url": "https://www.abc.com"
    }
  }' \
  https://graph.facebook.com/<VERSION>/<PAGE_ID>/canvas_elements

If you want, you can also create a button which you later use in the footer:

curl \
  -F 'canvas_footer={ 
    "child_elements": [<BUTTON_ELEMENT_ID>]
  }' \
  https://graph.facebook.com/<VERSION>/<PAGE_ID>/canvas_elements

The text you provide in your footer is relatively flexible, in the past you need to provide See more.... but you can now provide custom text with the button URL.

Then you create your Instant Experience:

curl \
  -F 'body_element_ids=[
    <PHOTO/VIDEO_ELEMENT_ID>,
    <PRODUCT_SET_ELEMENT_ID>,
    <FOOTER_ELEMENT_ID>
  ]' \
  -F 'is_published=true' \
  https://graph.facebook.com/<VERSION>/<PAGE_ID>/canvases

Finally, you need to create a collection ad. This enables people to click on your images or video element from your collection ad.

If the first element of your Instant Experience is a photo, you must set object_type to SHARE:

curl \
  -F 'name=Collection Sample Image Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "link": "https://fb.com/canvas_doc/<CANVAS_ID>", 
      "message": "Ad message",
      "name": "Ad headline", 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'object_type=SHARE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

If the first element of your Instant Experience is a video, make this request:

curl \
  -F 'name=Collection Sample Video Creative' \
  -F 'object_story_spec={ 
    "video_data": {
      "call_to_action": {
        "type":"LEARN_MORE",
        "value":{
          "link":"https://fb.com/canvas_doc/<CANVAS_ID>",
        }
      },
      "message": "Ad message",
      "title": "Ad headline", 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'object_type=SHARE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

Collection Ads from Product Sets, Deprecated

We deprecated the collections ads creation API as of v3.0. This API did not provide access to the underlying Instant Experience we created for your ad; therefore you could not build engagement audiences for your ad.

Image-Based Ads with Product Set Elements

curl \
  -F 'name=Collection Sample Image Creative' \
  -F 'object_story_spec={ 
    "link_data": {
      "link": "https://fb.com/canvas_doc/CANVAS_ID_WITH_PRODUCT_SET", 
      "message": "Ad message", 
      "name": "name", 
      "picture": 1000003, 
      "retailer_item_ids": [ 
        "RETAILER_ID_1", 
        "RETAILER_ID_2", 
        "RETAILER_ID_3", 
        "RETAILER_ID_4" 
      ] 
    }, 
    "page_id": "PAGE_ID" 
  }' \
  -F 'product_set_id=PRODUCT_SET_ID_IN_CANVAS' \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/adcreatives

Image-based options include:

Video Ads with Product Set Elements

curl \
  -F 'name=Collection Sample Video Creative' \
  -F 'object_story_spec={ 
    "page_id": "PAGE_ID", 
    "video_data": { 
      "call_to_action": {
        "type":"LEARN_MORE",
        "value":{
          "link":"https://fb.com/canvas_doc/CANVAS_ID_WITH_PRODUCT_SET",
          "link_format":"VIDEO_LPP"
        }
      }, 
      "image_url": 1000003, 
      "retailer_item_ids": [ 
        "RETAILER_ID_1", 
        "RETAILER_ID_2", 
        "RETAILER_ID_3", 
        "RETAILER_ID_4" 
      ], 
      "title": "My title", 
      "video_id": "VIDEO_ID" 
    } 
  }' \
  -F 'product_set_id=PRODUCT_SET_ID_IN_CANVAS' \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/adcreatives

Video-specific fields are:

Post-Click Configuration Ads

Post-Click configuration fields include:

You can also provide a text overlay for your collection ad based on a product set. This is text that appears as a layer over your ad. This is similar to using image and text overlays for Dynamic Ads, except you specify it in post_click_configuration under link_data and video_data.

Creating Standard Collection Ads

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. Also see Instant Experiences, Using Templates.

There are two types of collection ads with Instant Experiences: image-based and video-based, depending on the asset you provide. Once you have ad creative, you can create an ad with these fields:

The thumbnail fields are as follows:

Create an Image-Based Ad

curl 
  -F 'name=Instant Experiences Collection Sample Image Creative' 
  -F 'object_story_spec={ 
    "link_data": {
      "link": "https://fb.com/canvas_doc/ELIGIBLE_CANVAS_ID", 
      "message": "Ad message", 
      "name": "name", 
      "picture": "IMAGE_URL", 
      "collection_thumbnails": [
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_WITH_PRODUCT_TAGS_ID",},
        {"element_child_index": 0,"element_id": "",},
        {"element_child_index": 1,"element_id": "PRODUCT_LIST_ELEMENT_ID",},
      ],
    }, 
    "page_id": "PAGE_ID" 
  }' 
  -F 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/adcreatives

Create a Video-Based Ad

curl 
  -F 'name=Instant Experiences Collection Sample Video Creative' 
  -F 'object_story_spec={ 
    "page_id": "PAGE_ID", 
    "video_data": { 
      "call_to_action": {"type":"LEARN_MORE","value":{"link":"https://fb.com/canvas_doc/ELIGIBLE_CANVAS_ID"}}, 
      "image_url": "IMAGE_URL",
      "collection_thumbnails": [
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_child_index": 0,"element_id": "PHOTO_ELEMENT_WITH_PRODUCT_TAGS_ID",},
        {"element_child_index": 1,"element_id": "PRODUCT_LIST_ELEMENT_ID",},
      ],
      "title": "My title", 
      "video_id": "VIDEO_ID" 
    } 
  }' 
  -F 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/adcreatives

Create Engagement Audiences

You can automatically create audiences for people who interacted with your collection ad. This is similar to engagement audiences for standard Instant Experiences, see Instant Experiences, Engagement Audiences

As of September 20, 2018 we will not support subtype after v3.0 of Marketing API for custom audiences for websites, apps, engagement custom audiences, and audiences from offline conversion data. The one exception is that subtype will still be supported for engagement custom audiences for video.

Target your Instant Experience ads with a fullscreen view at people who tapped your Collection ad. We call this type of audience a Fullscreen Experience engagement audience. Build this audience by creating a Custom Audience, then set object_id to CANVAS_ID, and a rule to track one of the events demonstrated below.

Create an Audience that Opened an Instant Experience

curl \
    -F 'name=Collection 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

Create Audience that Clicked

Here we create an audiences of people that clicked any link in the collection:

curl \
    -F 'name=Collection 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

Collection Ads Dialog

Collection ads are based on Instant Experiences with a template. Therefore, to create a Collection Ad using a dialog, you will use the Instant Experiences dialog with additonal parameters. This will provide the Facebook Collection Ad creation UI flow 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 Instant Experiences. 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. The user must also have access to the product catalogs and sets. To ensure no errors, the user must be in the business and have 'create ads' permissions for the page.

Then trigger the Collection Ads dialog:

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

You can provide these settings for the plugin:

All valid template types and the corresponding ID can be found here.

The parameters product_catalog_id and product_set_id are optional. However, if you provide product_set_id, you will need to provide product_catalog_id. Once you provide these IDs, the user will not be able to change the collection in the UI. If neither parameter is provided, the user can select the catalog and product set in the UI. For previewing a Collection Ad, we recommend using the Instant Experiences Preview Dialog.

The plugin provides this response on success:

{
  "success": true,
  "id": "<CANVAS_ID>"
}

The ID returned will be an unpublished Instant Experience. It will need to be published before it can be used in ad campaigns. If no response or an undefined response is returned, that means the user closed the dialog before finishing the Instant Experience. The user might have saved the Instant Experience, 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 Instant Experiences.

Include Destination Catalogs

You can show ad creative from destination catalog in a collection ad's hero image. You can also display a carousel of hotel images at that destination. To do this, you must provide a fallback image that displays at the hero image in case we find no corresponding destination for hotels in the carousel. For background information, see Destination Catalog.

Note these limitations:

• Video creative is not supported.
• We only support display of destination and hotel catalog images combined.
• Wd do not support display of other catalog combinations.

To use this API, the only change you need to make to your current collection ads API is when create your canvas_photo element. Add the parameter destination_set_id, then follow the other standard steps to create your Instant Experience and collection ad. For example:

curl \
  -F 'canvas_photo={ 
    "photo_id": "<PHOTO_ID>", 
    "destination_set_id": "<DESTINATION_SET_ID>",
  }' \
  https://graph.facebook.com/VERSION/<PAGE_ID>/canvas_elements