Dynamic Media

Dynamic media allows advertisers to deliver video assets from their catalog in their Advantage+ catalog ads.

Before You Begin

You will need:

A product catalog with existing products
A video for each product item in a downloadable video URL format

See the Advantage+ catalog ads documentation to learn more about how they work.

Limitations

Currently, this feature can support video for up to 30,000 products per catalog.
We recommend a minimum of 20 products, but there are no required minimums.
Each video size should not exceed 200MB. There are no length restrictions.
Videos must be in one of the following formats: 3g2, 3gp, 3gpp, asf, avi, dat, divx, dv, f4v, flv, gif, m2ts, m4v, mkv, mod, mov, mp4, mpe, mpeg, mpeg4, mpg, mts, nsv, ogm, ogv, qt, tod, ts, vob, or wmv.
The video_fetch_status may show as NO_STATUS until the video is used in an ad or another event that requires the video is triggered.

Add Videos to Your Catalog

There are 3 ways to add videos to product items in your catalog: catalog feed file, catalog batch API, and manual upload via your Commerce Manager.

Add videos with the catalog feed file

Using the catalog feed file, you can provide <= 30,000 products with product-level video URLs.

Step 1. Prepare Your Catalog Feed File

You can use one of the following processes to implement your catalog feed file.

Process 1: Change the main feed
- Add a video[0].url column to your existing catalog feed file, populate the video URL to only the selected products, and leave it empty for other product rows.
- Additional videos for the same product can be added with additional columns: video[1].url, video[2].url, video[3].url, etc.
- Tags may be added to the videos by including the tags in separate columns. For example: video[0].tag[0], video[0].tag[1], video[1].tag[0], and so on.
Process 2: Supplemental feed
Prepare a supplementary catalog feed file to supplement an existing feed upload. This supplemental feed can only add or replace videos to already existing product items. Add a video[0].url column and an ID column to associate the video with the product item ID.

Optional:
Instead of the video[0].url column, you can create a column called video and add tags to the video. The video column can contain multiple video URLs per product and multiple tags per URL encoded in a JSON format. If you choose to use a tag column for the product set filter, you’ll need to add this column to the feed file too.

Example video column format:

[{"url": "http://www.jaspersmarket-example1.com/video-file.avi", "tag": ["Optional Tag1", "Optional Tag2"]},{"url": "http://www.jaspersmarket-example2.com/video-file.avi", "tag": ["Optional Tag1", "Optional Tag2"]}]

For an XML feed, video URLs can be added using <video> tags like:

<video>
    <url>https://{URL1}</url>
    <tag>video_product_set1</tag>
    <tag>video_product_set2 </tag>
</video>
<video>
    <url>https://{URL2}</url>
    <tag>video_product_set1</tag>
</video>

Add videos with the catalog batch API

Updates to product items are supported using the /{product_catalog_id}/items_batch endpoint. You can make a POST API call with the video field, which is an array of URLs.

curl \
  -d @body.json \
  -H "Content-Type: application/json"

> cat body.json
{
  "access_token": "<ACCESS_TOKEN>",
  "item_type": "PRODUCT_ITEM",
  "requests": [
    {
      "method": "CREATE",
      "data": {
        "id": "retailer-2",
        "availability": "in stock",
        "brand": "BrandName",
        "google_product_category": "t-shirts",
        "description": "product description",
        "image_link": "http://www.images.example.com/t-shirts/1.png",
        "title": "product name",
        "price": "10.00 USD",
        "shipping": [
          {
            "shipping_country": "US",
            "shipping_region": "CA",
            "shipping_service": "service",
            "shipping_price_value": "10",
            "shipping_price_currency": "USD"
          }
        ],
        "condition": "new",
        "link": "http://www.images.example.com/t-shirts/1.png",
        "item_group_id": "product-group-1",
        "video": [
          {"url": "http://www.jaspersmarket-example1.com/video-file.avi", "tag": ["Optional Tag1", "Optional Tag2"]}, 
          {"url": "http://www.jaspersmarket-example2.com/video-file.avi", "tag": ["Optional Tag1", "Optional Tag2"]}
        ]
      }
    },
    {
      "method": "UPDATE",
      "data": {
        "availability": "out of stock",
        "id": "retailer-3",
        "video": [
          {
            "url": "https://yourvideo.com/demo.mp4?q=1411"
          },
          {
            "url": "https://yourvideo.com/demo.mp4?q=1421"
          }
        ]
      }
    }
  ]
}

See this example in the Graph API Explorer.

Create Ads with Dynamic Media

When creating ads, there are two types of options that leverage video from the catalog:

Dynamic media type (Carousel/Collection) (recommended)
Show video when available (only available for single video format)

Note: Selecting dynamic media type with the API is similar to selecting the Dynamic Media options in Ads Manager.

Dynamic media type ads

When creating an ad creative object with the act_<AD_ACCOUNT_ID>/adcreatives endpoint

Set the media_type_automation key to be OPT_IN.
This key works with both Carousel and Collection formats.

curl \
-F 'name=Dynamic Media Ad Creative' \
-F 'object_story_spec={
    ...
  }' \
-F 'degrees_of_freedom_spec={
    "creative_features_spec": {
      "media_type_automation": {
        "enroll_status": "OPT_IN"
      }
    }
  }' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
https://graph.facebook.com/v18.0/act_<AD_ACCOUNT_ID>/adcreatives

Or when creating an ad object with the act_<AD_ACCOUNT_ID>/ads endpoint, set the media_type_automation key to be OPT_IN.

curl \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={
    "name": "Dynamic Media Ad Creative",
    "object_story_spec": {
      ...
    },
    "degrees_of_freedom_spec": {
      "creative_features_spec": {
        "media_type_automation": {
          "enroll_status": "OPT_IN"
        }
      }
    },
    "product_set_id": "<PRODUCT_SET_ID>"
  }' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads

Dynamic media ads (with Collection format)

Dynamic media only replaces hero media. Product thumbnails in pre-click experience and in Instant Experiences will always be images.
If opted into dynamic media and if the product video is available, we will replace the dynamic video hero media with a product video.
Dynamic media only replaces dynamic video hero media when opted-in. Currently a static hero image and video won’t be replaced by a product video, i.e., The image slideshow experience is replaced with a product video.

Example Creative Spec for Collection with Dynamic Media

curl \
-F 'name=Dynamic Media Ad Creative' \
-F 'object_story_spec={
      "template_data": {
          ...
          "format_option": "collection_video",
          "link": "https://fb.com/canvas_doc/<CANVAS_ID>",
          "message": "Your Collection Ad",
          ...
    }
  }' \
-F 'degrees_of_freedom_spec={
    "creative_features_spec": {
      "media_type_automation": {
        "enroll_status": "OPT_IN"
      }
    }
  }' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adcreatives

Dynamic media ads (Show videos when available)

In the object_story_spec, change format_option to single_video. This is only available for single image/video format.

curl \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={
    "name": "Dynamic Media Ad Creative",
    "object_story_spec": {
      "page_id": "<PAGE_ID>",
      "template_data": {
        ...
        "format_option": "single_video",
        ...
      }
    },
    "product_set_id": "<PRODUCT_SET_ID>"
    }' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads