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.

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:

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

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

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:

• Facebook Feed
• Facebook Reels
• Instagram Feed (See Instant Experiences: Instant Experiences and Instagram Ads.)
• Instagram Stories (See Instant Experiences: Instant Experiences and Instagram Ads.)

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 catalog. A collection ad has three products under a hero image or video and displays in mobile Feed. You can use slideshow videos with this feature.

The ad appears in 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 Advantage+ catalog ads and already have a product catalog set up. See Advantage+ Catalog Ads and Advantage+ Catalog 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:

• An image, as either a Canvas Photo, Canvas Video, or Canvas Template Video.
• A product set with show_in_feed set to true. (See Canvas Product Set, Reference.)
• A footer (See Canvas Footer, Reference.)

The Instant Experience image

Create an Instant Experience with an image:

curl \
  -F 'canvas_photo={ 
    "photo_id": "PHOTO_ID", 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/PAGE_ID/canvas_elements
Open In Graph API Explorer

Or create an Instant Experience with a video:

curl \
  -F 'canvas_video={ 
    "video_id": "VIDEO_ID", 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/PAGE_ID/canvas_elements
Open In Graph API Explorer

Or create an Instant Experience with a template video:

curl -X POST \
  -F canvas_template_video={
      "name": "Cover Image or Video",
	"bottom_padding": "0",
	"top_padding": "0",
	"product_set_id": <Product_Set_ID>,
	"template_video_spec": {
	    "customization": {
	        "text_color": "FFFFFF",
	        "text_background_color": "000000",
		  "name_template": "{{product.name}}",
		  "body_template": "{{product.current_price strip_zeros}}"
	    },
	}
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.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,
    },
    "storefront_setting": {
        "enable_sections": true,
        "customized_section_titles": [
            { "title_id": "popular", "customized_title": "My Populars" },
            { "title_id": "favorites", "customized_title": "My Favorites" }
        ],
        "product_set_layout": {
            "layout_type": "GRID_3COL"
        }
    },
    "retailer_item_ids": [0, 0, 0],
    "show_in_feed": true
  }' \
  https://graph.facebook.com/v21.0/<PAGE_ID>/canvas_elements

Note: In the example above, item_headline, item_description, image_overlay_spec, storefront_setting, 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 storefront_setting parameter supports the product_set_layout, enable_sections, and customized_section_titles fields.

The product_set_layout fields

In order to use customized_section_titles, enable_sections must be set to true. The customized_section_titles field expects an array of objects, each with title_id and customized_title parameters.

The customized_section_titles fields

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"
    }
  }' \
 -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/PAGE_ID/canvas_elements
Open In Graph API Explorer

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

curl \
  -F 'canvas_footer={ 
    "child_elements": [BUTTON_ELEMENT_ID]
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/PAGE_ID/canvas_elements
Open In Graph API Explorer

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

curl \
  -F 'body_element_ids=[
    PHOTO/VIDEO_ELEMENT_ID,
    PRODUCT_SET_ELEMENT_ID,
    FOOTER_ELEMENT_ID
  ]' \
  -F 'is_published=true' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/PAGE_ID/canvases
Open In Graph API Explorer

To create the Instant Experience with a template video, product set, button, store location and optional footer you set up, you will need to include the source_template_id parameter:

curl \
  -F 'body_element_ids=[
    TEMPLATE_VIDEO_ELEMENT_ID,
    PRODUCT_SET_ELEMENT_ID,
    FOOTER_ELEMENT_ID
  ]' \
  -F 'name="Dynamic Video Instant Experience"' \
  -F 'source_template_id="1932289657009030"' \
  -F 'is_published=true' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<PAGE_ID>/canvases
Open In Graph API Explorer

For a Storefront template, you need to specify source_template_id = 1932289657009030, it is defined in Instance Experiences, Using templates. The layout for each template is fixed; however, you can replace the default content with your own dynamic videos, products, text and links. For more information, see Instant Experiences, Using Templates.

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

Open In Graph API Explorer

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

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

curl -X POST \
  -F 'name="Dynamic Video Collection Ad"' \
  -F 'adset_id=<ADSET_ID>' \
  -F 'status=PAUSED \
  -F 'creative={
       "object_story_spec": {
         "instagram_actor_id": "<INSTAGRAM_PAGE_ID>",
         "page_id": "<MAIN_PAGE_ID>",
         "template_data":{
           "call_to_action":{
             "type":"LEARN_MORE"
           },
           "format_option":"collection_video",
           "link":"https://fb.com/canvas_doc/CANVAS_ID",   
           "name":"Test Dynamic Ads with dynamic video",
           "retailer_item_ids":[
             "0",
             "0",
             "0",
             "0"
           ]
         }
       },
       "object_type": "SHARE",
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads

Ad Previews

If you have Ad Preview capability, you can provide an ad_format and User access token to generate previews based on your ad or ad creative.

curl -X GET \
  -d 'ad_format="MOBILE_FEED_STANDARD"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CREATIVE_ID>/previews

Open In Graph API Explorer

Note: For template video Instant Experience ads, the supported formats are BIZ_DISCO_FEED_MOBILE, GROUPS_MOBILE, MOBILE_FEED_STANDARD, SUGGESTED_VIDEO_DESKTOP, SUGGESTED_VIDEO_MOBILE, WATCH_FEED_MOBILE.

See Ad Previews for more information.

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

Parameters

The collection_thumbnails fields

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

Open In Graph API Explorer

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/v21.0/AD_ACCOUNT_ID/customaudiences
    
Open In Graph API Explorer

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:

• 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. 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:

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",
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/PAGE_ID/canvas_elements
Open In Graph API Explorer