Collection Ads

An ad format that makes it easier for people to discover, browse and purchase products and services from their mobile device in a visual and immersive way. Feature products in a fullscreen canvas with four products under a hero image or video, which displays in mobile News Feed. There are two types of collection ads: image-based and video-based.

You can use a canvas to design your collection ad; this provides a fullscreen experience for mobile devices. Choose a canvas fullscreen template for your collection ad or create your own customized canvas. For background, see Ads Help Center, Canvas.

You can also bring Facebook's Collections Ads creation user interfaces to your website using the JavaScript SDK. Learn more about the Collections Ads Dialog below.

For general information on using collections, see:

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:

Collection Ads from Product Sets

Before you create a canvas collection ads, provide ad creative and a canvas. 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 a canvas in the background. This limited your access to the underlying canvas; you could not use it to retarget audiences with canvas engagement audiences. As of 3.0, when you create a collection ad from product sets, you must also explicitly create a canvas with the correct elements. When you use this canvas in a collection ad, Facebook automatically generates the collection ad. You canvas should contain:

For example, you first create a canvas ad, 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 a canvas 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 canvas 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 canvas:

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 canvas is a photo, you must set object_type to SHARE:

curl \
  -F 'name=Collection Sample Image Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "image_hash": "<IMAGE_HASH>", 
      "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 canvas 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 canvas 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:

Field Name Description Type

picture

URL of hero image in ad. Provide picture or image_hash.

string

image_hash

Hash of hero image. Provide picture or image_hash.

string

link

Redirect viewer to this URL.

string

caption

URL for the CTA button at the bottom of the creative.

string

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:

Field Name Description Type

video_id

Unique ID for hero video.

string

image_hash

Thumbnail image for video. Provide image_hash or image_url.

string

image_url

URL for video thumbnail. Provide image_hash or image_url.

string

link

Redirect viewer to this URL.

string

link_caption

Clean URL for the CTA button at the bottom of the creative.

string

link_format

Use VIDEO_LPP.

string

Post-Click Configuration Ads

Post-Click configuration fields include:

Field Name Description Example

post_click_configuration

Provide a content or product field template for the product headline and description.

post_click_item_headline

Item headline. Displays with template tag.

For example {{product.name}}

post_click_item_description

Item description. Displays with template tag or hidden.

For example {{product.brand}}. To hide this field, use: {{field.hide}}

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 a canvas 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 Canvas Ads, Using Canvas Templates.

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

Field NameDescriptionTypeRequired

link

Redirect viewer to canvas

string

Yes

collection_thumbnails

Array of thumbnails. Four thumbnails required.

array

Yes

The thumbnail fields are as follows:

Field NameDescriptionTypeRequired

element_id

Photo or product list element ID. An image associated with this ID appears in the canvas after someone clicks the ad. A hero image element ID is invalid.

numeric string

Yes

element_child_index

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 product list elements

integer greater than or equal to zero

Yes, for photo element with product tags and product list element

element_crops

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

AdsImageCrops.

Yes, for photo element

Create an Image-Based Ad

curl 
  -F 'name=Canvas 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=Canvas 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 canvas ads, see Canvas Ads, Engagement Audiences

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

Create an Audience that Opened a Canvas

curl \
    -F 'name=Collection Engagement Audience' 
    -F 'subtype=ENGAGEMENT' 
    -F 'description=People who opened this Canvas' 
    -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 'subtype=ENGAGEMENT' 
    -F 'description=People who clicked any links in this Canvas' 
    -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 Canvas Ads with a template. Therefore, to create a Collection Ad using a dialog, you will use the Canvas Ads 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:

The JavaScript SDK relies on the logged in user's permissions to create a Canvas. If the user does not have the necessary permissions to create a Canvas 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: 'canvas_editor',
  ad_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 Required Description

display

Yes

Necessary parameter with set value of popup

method

Yes

Necessary parameter with set value of canvas_editor

ad_account_id

Yes

Your ad account ID

business_id

Yes

Your business ID

page_id

Yes

Page ID you want to associate the canvas with

template_id

Yes

ID of template you want to use

product_catalog_id

No

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

product_set_id

No

ID of product set to be used in collection

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 Canvas Preview Dialog.

The plugin provides this response on success:

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

The Canvas ID returned will be an unpublished Canvas. 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 Canvas. The user might have saved the Canvas, but not finished it. You can pull all Canvases that belong to a page using the Graph API to see if there are any unfinished Canvas.