Collection Ads

The collection ad format includes an Instant Experience and makes it easier for people to discover, browse, and purchase products and services from their mobile device in a visual and immersive way. Your in-feed ad will feature three 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.

Consider all references of “Canvas” to represent Instant Experience as Canvas is the previous name for this format.

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 more information, see Ads Help Center, Instant Experience.

You can also include Facebook's ad creation user interfaces for the collection format in your website by using the JavaScript SDK to create a Collections Ads Dialog.

For general information on using collections, see:

To create collections used in Shops or add metadata to a product set, see Commerce Platform, Product Set Collection API.

For API calls, your AD_ACCOUNT_ID should be formatted as act_XXXXXXXXXXXXXXX.

Supported Objectives and Placements

You can use collection ads with the following objectives:

  • Traffic
  • Conversions
  • Product Catalog Sales (Supported when you use collections with a product set.)
  • Store Visits (Supported when you use collections with a product set.)
  • Brand Awareness
  • Reach

For Traffic and Conversions objectives, you can also use slideshow videos. To get more information, see Business Help Center: Choose the Right Ad Objective.

The following placements are supported:

For more information about placements, see Business Help Center: About placements and Business Help Center: Available ad placements for marketing objectives.

Collection Ads from Product Sets

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

Create collection ads from your Dynamic Ads catalog. A collection ad has three 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 on 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.

Creating Ads

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 Experience in a collection ad, Facebook automatically generates the collection ad. Your Instant Experience should contain:

The Instant Experience image

Create an Instant Experience with an image:

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

Or create an Instant Experience with a video:

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

The Instant Experience product set

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],
    "show_in_feed": true
  }' \
  https://graph.facebook.com/v12.0/PAGE_ID/canvas_elements

Note: In the example above, 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.

Provide any required fields in the image_overlay_spec parameter. For more information, see Marketing API, Reference, Ad Creative Link Data, Image Overlay Spec.

The Instant Experience footer

Create the Instant Experience footer with a link.

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/v12.0/PAGE_ID/canvas_elements

If you want, you can also create a button to use in the footer.

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

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

The complete Instant Experience

Create the Instant Experience using the image, product set, and footer you set up.

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

Create the collection ad with the Instant Experience

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/v12.0/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",
        }
      },
      "image_url": "THUMBNAIL_IMAGE_URL",
      "message": "AD_MESSAGE",
      "title": "AD_HEADLINE", 
    }, 
    "page_id": "PAGE_ID" 
  }' \
  -F 'object_type=VIDEO' \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/v12.0/AD_ACCOUNT_ID/adcreatives

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 the default content with your own images, videos, products, text and links. For more information, 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 an ad creative, you can create an ad.

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_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/v12.0/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_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/v12.0/AD_ACCOUNT_ID/adcreatives

Parameters

NameDescription

link

string

Required
Redirects the viewer to an Instant Experience.

collection_thumbnails

array

Required
An array of thumbnails. Four thumbnails are required.

The collection_thumbnails fields

NameDescription

element_id

numeric string

Required
The Canvas photo element ID or the product list element ID. The Canvas photo needs to be associated with the Instant Experience attached to this collection ad. An image associated with this ID appears in the Instant Experience after someone clicks the ad. A hero image element ID is invalid.

element_child_index

integer

Required for a photo element with product tags and product list element
The product index from an array of photo element IDs with product tags. Or a product index from an array of product_id_list, which contains the product list elements.
Note: Must be a positive integer.

element_crops
AdsImageCrops

Required for a photo element
A JSON object defining crop dimensions for the image specified. Only 100x100 crop key allowed.

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. For more information, see Instant Experiences, Engagement Audiences.

You can target your Instant Experience ads with a fullscreen view at people who tapped on 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 make a rule to track one of the events.

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/v12.0/AD_ACCOUNT_ID/customaudiences

Create an audience that clicked on a collection ad

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

To set up the Facebook SDK for JavaScript, see:

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. In order to ensure no errors, the user must have access to the Business Manager and have permissions to create ads for the page.

Then you can 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:

Name Description

display

Required
Necessary parameter set to the value of popup.

method

Required
Necessary parameter set to the value of instant_experiences_builder.

account_id

Required
Your ad account ID.

business_id

Required
Your business ID.

page_id

Required
The Page ID you want to associate with the Instant Experience.

template_id

Required
The ID of the template you want to use.

product_catalog_id

Optional
The ID of the product catalog to be used in the collection. This is necessary if product_set_id is provided.

product_set_id

Optional
The ID of the product set to be used in the collection.

All valid template types and the corresponding ID can be found in Instant Experiences: Use a Template.

The product_catalog_id and product_set_id parameters 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. To preview 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 there is no response or an undefined response is returned, that means the user closed the dialog before finishing the Instant Experience, or that the user saved the Instant Experience, but did not finished it. You can query the Graph API to see all the Instant Experiences that belong to a page; this will allow you to see if there are any unfinished Instant Experiences.

Including Destination Catalogs

You can show ad creatives from a 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 more information, see Destination Catalog.

Note these limitations:

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

To use this feature, add the destination_set_id parameter when creating your canvas_photo element, then follow the other standard steps to create your Instant Experience and collection ad.

Example

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