设置目录

如需设置动态广告,您需要目录、目录信息库和商品系列。

您的目录是一个结构化数据文件,其中包含您要广告的商品的列表。每行都包含创建动态广告所需的全部信息。商品信息库是数据的动态上传,用于保持您的商品目录处于最新状态。

在本文档中,我们将向您介绍如何设置目录:

另请参阅动态广告入门通过 UI 设置动态广告

步骤 1:创建目录

如需为动态广告创建目录,请使用以下代码:

use FacebookAds\Object\ProductCatalog;
use FacebookAds\Object\Fields\ProductCatalogFields;

$product_catalog = new ProductCatalog(null, <BUSINESS_ID>);

$product_catalog->setData(array(
  ProductCatalogFields::NAME => "Catalog",
));

$product_catalog->create();
from facebookads.adobjects.productcatalog import ProductCatalog

product_catalog = ProductCatalog(parent_id=<BUSINESS_ID>)

product_catalog[ProductCatalog.Field.name] = 'Catalog'

product_catalog.remote_create()
ProductCatalog catalog = new Business(<BUSINESS_ID>, context).createProductCatalog()
  .setName("Catalog")
  .execute();
String catalog_id = catalog.getId();
curl \
  -F 'name=Catalog' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<BUSINESS_ID>/product_catalogs

如需使用目录 API,您需要适当的市场营销 API 访问级别并通过使用商务管理平台创建第一个目录来接受服务条款。请参阅目录参考

步骤 2:设置信息库

这是通过公司上传或获取的一组商品,因此您的商品目录为最新状态。产品项是您在线商店中的单个商品,如 SKU。您可以使用单个商品信息库表示目录中的所有产品,也可以使用多个商品信息库,其中每个信息库表示单个国家/地区或部门的产品。请参阅信息库参考商品参考

创建商品目录后,可以使用 catalog id 来创建并计划商品信息库

use FacebookAds\Object\ProductFeed;
use FacebookAds\Object\Fields\ProductFeedFields;
use FacebookAds\Object\Fields\ProductFeedScheduleFields;

$product_feed = new ProductFeed(null, <PRODUCT_CATALOG_ID>);

$product_feed->setData(array(
  ProductFeedFields::NAME => 'Test Feed',
  ProductFeedFields::SCHEDULE => array(
    ProductFeedScheduleFields::INTERVAL => 'DAILY',
    ProductFeedScheduleFields::URL =>'http://www.example.com/sample_feed.tsv',
    ProductFeedScheduleFields::HOUR => 22,
  ),
));

$product_feed->create();
from facebookads.adobjects.productfeed import ProductFeed

product_feed = ProductFeed(parent_id=<PRODUCT_CATALOG_ID>)

product_feed[ProductFeed.Field.name] = 'Test Feed'
product_feed[ProductFeed.Field.schedule] = {
    'interval': 'DAILY',
    'url': 'http://www.example.com/sample_feed.tsv',
    'hour': 22,
}

product_feed.remote_create()
ProductFeed productFeed = new ProductCatalog(<PRODUCT_CATALOG_ID>, context).createProductFeed()
  .setName("Test Feed")
  .setSchedule("{\"interval\":\"DAILY\",\"url\":\"http://www.example.com/sample_feed.tsv\",\"hour\":\"22\"}")
  .execute();
String product_feed_id = productFeed.getId();
curl \
  -F 'name=Test Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_feed.tsv", 
    "hour": 22 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_CATALOG_ID>/product_feeds

支持的格式

请提供采用下列格式之一的商品信息库:

信息库格式 描述 示例信息库

CSV

逗号分隔值。第一行是列标题。将包含逗号的字段放入 "双引号"

下载(点击右键并选择“将链接另存为”)

TSV

制表符分隔值。第一行是列标题。将包含逗号的字段放入 "双引号"

下载(点击右键并选择“将链接另存为”)

RSS XML

格式通常由自动信息库提供程序系统或网络服务器生成。一组商品 XML 节点表示产品列表,并且必须以 <?xml 声明标签开头。

下载(点击右键并选择“将链接另存为”)

ATOM XML

格式通常由自动信息库提供程序系统或网络服务器生成。一组商品 XML 节点表示产品列表,并且必须以 <?xml 声明标签开头。

下载(点击右键并选择“将链接另存为”)

必填字段

以英语命名所有列。

名称 类型 描述

id


最大大小:100

字符串

商品的唯一编号。可以是产品的变体。如果存在同一编号的多个实例,我们将忽略所有实例。在导入产品后,此项将映射到 retailer_id

availability

字符串

表示商品是否有货。接受的值为:


in stock - 商品可立即发货。


out of stock - 未计划进货。


preorder- 将来可用。


available for order - 将在 1 到 2 个星期内发货。


discontinued - 已停产


condition

字符串

产品条件:newrefurbishedused

description


最大大小:5000

字符串

描述产品的简短文本。

image_link


字符串

广告中使用的商品图像的链接。轮播广告格式使用方形 1:1 宽高比图像(600x600 像素),而单一产品广告使用 1.91:1 宽高比图像(1200x630 像素)。提供适合的图像供您使用。

link


字符串

可以从中购买商品的商家站点的链接。

title


最大大小:100

字符串

商品的标题。

price

字符串

商品的成本和货币。货币应遵循 ISO 4217 货币代码,如 9.99 USD

gtinmpnbrand


最大大小:70

字符串

gtin - 全球贸易项目代码 (GTIN) 可以包含 UPC、EAN、JAN 和 ISBN。



mpn - 产品的唯一制造商编号。



brand - 品牌名称。



gtinmpnbrand 是必填字段。

可选字段、产品深度链接

遵循应用链接规范,在商品信息库中提供深度链接。商品信息库中的深度链接信息优先于 Facebook 使用网络爬虫收集的应用链接元数据的任何相关信息。

如果您已有来自应用链接的深度链接信息,则无需指定此数据。Facebook 使用来自应用链接的信息显示正确的深度链接。如需在您的广告中显示深度链接,请参阅动态广告的广告模板

名称 描述 示例

ios_url

iOS 应用的自定义方案,以网址形式提供

example-ios://electronic

ios_app_store_id

App Store 的应用编号

1234

ios_app_name

要显示的应用的名称

Electronic Example iOS

iphone_url

iPhone 应用的自定义方案,以网址形式提供

example-iphone://electronic

iphone_app_store_id

App Store 的应用编号

5678

iphone_app_name

要显示的应用的名称

Electronic Example iPhone

ipad_url

iPhone 应用的自定义方案

example-ipad://electronic

ipad_app_store_id

App Store 的应用编号

9010

ipad_app_name

要显示的应用的名称

Electronic Example iPad

android_url

Android 应用的自定义方案,以网址形式提供

example-android://electronic

android_package

用于意向生成的完全限定程序包名称

com.electronic

android_app_name

要显示的应用的名称

Electronic Example Android

windows_phone_url

Windows Phone 应用的自定义方案,以网址形式提供

example-windows://electronic

windows_phone_app_id

App Store 的应用编号,以 GUID 形式表示

ee728e01-7727-4168-9c8f-85c7eef40112

windows_phone_app_name

要显示的应用的名称

Electronic Example Windows

对于 iOS,若与常规 iOS 应用不同,则仅提供 iPhone iPad 应用信息。

使用产品组对所有产品变体进行分组。提供产品组以识别几乎完全相同但存在变化(如,颜色、材料、大小或图案)的产品。借助产品组,可以更容易地为特定产品的其他颜色、样式或图案做广告。产品组中的所有产品都共享同一 item_group_id。在动态广告中,我们将根据从像素或应用中接收的信号仅选择组中的一件商品。

以下是您可以包含的可选字段:

名称 类型 最大大小

additional_image_link


最大大小:2000

字符串

您最多可以包含 10 张其他图像;以逗号分隔网址的形式提供。

age_group

字符串

产品的年龄段。接受的值为 newborninfanttoddlerkidsadult

color


最大大小:100

字符串

商品颜色。

expiration_date

ISO-8601 (YYYY-MM-DD)

产品到期日。如果产品已到期,Facebook 会将其从所有商品系列中排除并且不会在广告中显示该产品。

gender

字符串

选项包括:malefemaleunisex

item_group_id

字符串

用于作为产品变体的商品。为作为变体的所有商品提供同一 item_group_id。例如,“红色 Polo 衫”是“Polo 衫”的变体。在我们获得您的信息库后,Facebook 会将此项映射到 retailer_product_group_id。在动态广告中,我们将根据从像素或应用中接收的信号仅选择组中的一件商品。

google_product_category


最大大小:250

字符串

Google 产品分类法的预定义值。例如,Apparel & Accessories > Clothing > Dresses

material


最大大小:200

字符串

制造产品的材料,如leatherdenimcotton

pattern


最大大小:100

字符串

印在产品上的图案或图形。

product_type


最大大小:750

字符串

产品的零售商定义类别。

例如,
Home & Garden > Kitchen & Dining > Appliances > Refrigerators(TSV 格式)

例如,<product_type>Home & Garden > Kitchen & Dining > Appliances > Refrigerators</product_type>(XML 格式)

sale_price

字符串

如果商品参与促销活动,则为折扣价格。货币应指定为 ISO 4217 货币代码。指定为 9.99 USD

sale_price_effective_date

ISO-8601 (YYYY-MM-DD)

销售的开始日期与时间和结束日期与时间,以正斜杠分隔:


2014-11-01T12:00-0300/2014-12-01T00:00-0300

shipping

字符串

对于每个国家/地区和区域有不同价格的二进制大对象。不同的区域以逗号进行分隔。格式应为 COUNTRY:STATE:SHIPPING_TYPE:PRICE

例如

US:CA:Ground:9.99 USD,US:NY:Air:15.99 USD

shipping_weight

字符串

商品的装运重量。我们仅接受以下重量单位:lbozgkg。示例:3 lbs

size

字符串

商品尺寸。例如,衬衫的码数可以为SmallXL 码。

custom_label_0


最大大小:100

字符串

可选,商品的其他信息。

custom_label_1


最大大小:100

字符串

可选,商品的其他信息。

custom_label_2


最大大小:100

字符串

可选,商品的其他信息。

custom_label_3


最大大小:100

字符串

可选,商品的其他信息。

custom_label_4


最大大小:100

字符串

可选,商品的其他信息。

通过我们的商品信息库调试页面测试您的商品信息库。对于 CSV/TSV,复制第一行(列标题行)和几件产品;对于 XML,复制包含几件商品/几个条目的 XML,将这些行粘贴到文本区域并进行验证。

步骤 3:更新选项

如需保持产品信息处于最新状态,请使用以下选项之一:

  1. 计划商品信息库获取
  2. 直接上传商品信息库
  3. 更新产品

计划商品信息库获取

Facebook 可以按照您定义的计划从您的系统中获取商品信息库。您可以定义两类计划:update_scheduleschedule。通过 update_schedule 创建的上传操作将会创建新的商品,或以信息库文件中提供的信息更新现有商品。通过 schedule 创建的上传操作会完全刷新您的信息库,删除文件中不存在的商品,更新已有产品并创建新商品。您可以根据自己的需要使用其中一个计划,或同时使用两个计划。

例如:使用小时频率的 update_schedule 和使用每日频率的替换 schedule

我们建议设置 update_schedule 仅更新信息库文件中改变的数据以更快地处理信息库。这尤其适用于节日促销及频繁的价格和供货情况更新。我们还建议您将商品标记为“缺货”,而不是将其从信息库中删除,这样 Facebook 就可以将用户重新设置为类似有货商品的目标。

curl \
  -F 'name=Test Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_feed.tsv"
  }' \
  -F 'update_schedule={ 
    "interval": "HOURLY", 
    "url": "http:\/\/www.example.com\/sample_feed_updates.tsv",
    "hour": 22
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PRODUCT_CATALOG_ID>/product_feeds

响应如下:

{ "id" : {PRODUCT_FEED_ID} }

请参阅商品信息库参考商品信息库计划参考


直接上传商品信息库

除了计划的信息库获取之外,您还可以手动执行一次性上传:

以下为关于托管在公共位置的信息库文件的示例。

curl \
-F "url=http://www.example.com/sample_feed.xml" \
-F "access_token={ACCESS_TOKEN}" \
https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/uploads

以下为直接从本地机器上传信息库文件的示例。需要根据您的使用情况修改文件路径。

curl \
-F "file=@catalog.csv;type=text/csv" \
-F "access_token={ACCESS_TOKEN}" \
https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/uploads

或者,您可以将 update_only 设置为 true。我们将创建新的商品并更新已有商品,但不会从信息库中删除商品。您只需要提供 id 即可更新已有商品。这将缩短获取和处理您的文件所需的时间。

例如,如需仅更新信息库中 100 件商品的价格和自定义标签,请使用直接上传。提供仅包含这些商品的 idpricecustom_label_0 并且 update_only 设置为 true 的文件。我们支持所有列出的文件格式,最常用的格式为 TSV 和 CSV。

示例文件:

信息库格式 用例 示例信息库

CSV

更新一组商品的 priceavailability

下载(点击右键并选择“将链接另存为”)

TSV

重置 sale_price 和更新一组商品的 custom_label_0

下载(点击右键并选择“将链接另存为”)

请参阅手动上传参考

如果您在商品信息库中遇到错误,请参阅商品信息库上传错误参考


更新单件产品

实时更新单件产品的数据。在 HTTP POST 中包含更新后的字段:

https://graph.facebook.com/catalog:{PRODUCT_CATALOG_ID}:{base64urlencode(retailer_id)}

其中 retailer_id 是商品信息库中的产品编号。它必须为 base64url-encoded。请参阅商品目录产品参考中的产品字段。

请勿提供使用 API 进行单件产品更新、创建或删除的商品信息库。这会中断对您使用 API 创建的商品的任何更新或删除操作,因为我们不使用信息库追踪这些内容。

另请参阅:* 计划信息库获取参考 * 直接上传信息库参考 * 商品信息库参考 * 目录中的商品信息库 * 产品项参考 * 目录中的产品搜索

大目录的批量上传

上传包含数百万件产品并且库存快速变化的超大目录。您可以在单个 HTTP 请求中创建、更新和删除很多产品。API 有两个端点:

  • POST [/{product_catalog_id}/batch](#send-batch-request) - 发送一批在目录中创建、更新和删除商品的请求。
  • GET [/{product_catalog_id}/check_batch_request_status](#batch-request-status) - 检查请求的状态。

发送产品更新

如需在目录中创建、更新或删除产品,请结合您要进行的更改执行 HTTP POST。您在一次调用中最多可以执行 500 项更新。对于每个目录,您每小时最多可以执行 100 次调用。

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$requests =  array(
    array(
        'method' => 'CREATE',
        'retailer_id' => 'retailer-product-id-123',
        'data' => array(
          'availability' => 'in stock',
          'brand' => 'Niky',
          'category' => 't-shirts',
          'currency' => 'USD',
          'description' => 'This is the product description.',
          'image_url' => 'http://www.images.example.com/t-shirts/1.png',
          'name' => 'My product name',
          'price' => '100',
          'url' => 'http://www.example.com/t-shirts/1.html',
        ),
    ),
);


$data = Api::instance()->call(
  '/'.<CATALOG_ID>.'/batch',
  RequestInterface::METHOD_POST,
  array('requests' => $requests))->getContent();
curl \
  -F 'requests=[ 
    { 
      "method": "CREATE", 
      "retailer_id": "retailer-product-id-123", 
      "data": { 
        "availability": "in stock", 
        "brand": "Niky", 
        "category": "t-shirts", 
        "currency": "USD", 
        "description": "This is the product description.", 
        "image_url": "http:\/\/www.images.example.com\/t-shirts\/1.png", 
        "name": "My product name", 
        "price": "100", 
        "url": "http:\/\/www.example.com\/t-shirts\/1.html" 
      } 
    } 
  ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CATALOG_ID>/batch

此调用将返回您可用于检查批处理请求状态的句柄。请参阅获取请求状态

{
  "handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26I"]
}
参数 类型 描述

requests

对象

包含所有请求的 JSON 对象。

requests.method

字符串

CREATEUPDATEDELETE

requests.retailer_id

字符串

零售商提供的产品id

requests.data

对象

包含产品字段和值的 JSON 对象。当 methodCREATE 时,此项必须包含产品的所有必填字段。当 methodUPDATE 时,则可包含任何字段。Facebook 仅更新您提供的字段。

您可用于 CREATEUPDATE 商品的 data 字段中支持的值如下:

  • additional_image_urls
  • availability
  • age_group
  • applinks
  • brand
  • category
  • color
  • condition
  • currency
  • custom_label_0
  • custom_label_1
  • custom_label_2
  • custom_label_3
  • custom_label_4
  • description
  • gender
  • gtin
  • image_url
  • manufacturer_part_number
  • name
  • pattern
  • price
  • product_type
  • sale_price
  • sale_price_end_date
  • sale_price_start_date
  • shipping
  • size
  • url

您可以将 applinks 用于深度链接信息,此字段的工作方式类似于产品深度链接。格式如下:

"applinks" : {
  "ios": [{
    "url":"example-ios://electronic",
    "app_store_id":42,
    "app_name":"Electronic Example iOS"
  }],
  "iphone": [{
    "url":"example-iphone://electronic",
     "app_store_id":43,
     "app_name":"Electronic Example iPhone"
  }],
  "ipad": [{
    "url":"example-ipad://electronic",
     "app_store_id":44,
     "app_name":"Electronic Example iPad"
  }],
  "android": [{
    "url":"example-android://electronic",
     "package":"com.electronic",
     "class":"com.electronic.Example",
     "app_name":"Electronic Example Android",
  }],
  "windows_phone": [{
    "url":"example-windows://electronic",
     "app_id":"64ec0d1b-5b3b-4c77-a86b-5e12d465edc0",
     "app_name":"Electronic Example Windows"
  }]
}

请参阅商品目录创建参考

获取请求状态

如需获取批处理请求的状态,请使用对 {product_catalog_id}/batch 的调用中返回的句柄:

curl -G \
-d 'handle=AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26I'
-d 'access_token={ACCESS_TOKEN}'
https://graph.facebook.com/{API_VERSION}/{PRODUCT_CATALOG_ID}/check_batch_request_status

响应:

{
  "data": [
    {
      "handle": "AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q",
      "status": "finished",
      "errors_total_count": 1,
      "errors": [
        {
          "line": 0,
          "id": "retailer-4",
          "message": "Invalid value: Value passed at position 0 (id=retailer-199) is invalid: \"You cannot create a EntProductItem without required field Availability\""
        }
      ]
    }
  ]
}

请参阅商品目录参考,检查批处理状态

商品信息库规则

使用规则解决并避免长期信息库上传错误。您可以提供 Facebook 应用于每次信息库上传的规则。按照应该应用规则的属性(列)、规则类型和参数指定规则。您当前无法将规则与批处理 API 结合使用。可以提供以下类型的规则:

  • 映射规则 - 将信息库文件中的属性(列名称)映射到我们可以识别的属性。
  • 值映射规则 - 将信息库文件中的字段(列值)映射到我们可以识别的字段。
  • 字母大小写规则 - 更改字段中单词的大小写。例如,将所有大写描述更改为小写。

例如,可以使用映射和值映射规则解决以下问题:

  • 将属性 availability 错误地输入为 gavailability
  • 将无法识别的枚举 InStock 更正为 in stock
  • 将价格格式从 45$ 更正为 45.00 USD
  • 将要求:Neu 转换为要求:New

您可以使用字母大小写规则来解决以下类型的问题:

  • 将全部为大写字母的描述 BRAND NEW WITH LEATHER DETAIL... 更改为 Brand new with leather detail...
  • 将全部为大写字母的标题 FACEBOOK T-SHIRT 更正为 Facebook T-shirt

建议规则

您可以从 Facebook 获取建议规则,以解决信息库中的错误。如需查看上传会话的建议规则,请完成下列步骤。

  • 检索上传会话:
https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/uploads
  • 检索上传会话是否存在错误:
https://graph.facebook.com/{API_VERSION}/{UPLOAD_SESSION_ID}/errors
  • 检索上传错误的建议规则:
curl -i -X GET 
 "https://graph.facebook.com/{API_VERSION}/{UPLOAD_ERROR_ID}/suggested_rules?access_token={ACCESS_TOKEN}

包含建议的示例响应如下所示:

"data": [
  
    "attribute": "description",
    "type": "letter_case_rule",
    "params": [
      
        "key": "type",
        "value": "capitalize_first"
      
    ]
  
]

如需了解详细信息,请参阅建议规则 API 参考

端点

向信息库中添加规则

如需向信息库应用规则,您需要将规则关联到该信息库。对以下内容执行 HTTP POST 调用:

https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/rules?attribute={ATTRIBUTE}&amp;rule_type={RULE_TYPE}&amp;params={PARAMS}

例如:

curl -i -X POST 
 -d "attribute=google_product_category" 
 -d "rule_type=mapping_rule" 
 -d "params=%7B'map_from'%3A%20'gcategory'%7D" 
 -d "access_token={ACCESS_TOKEN}" 
 "https://graph.facebook.com/v2.9/{PRODUCT_FEED_ID}/rules" 
 // sample response
 
  "id": "{RULE_ID}"

您应该格式化params,如下所示:

规则类型 格式 示例 说明

映射规则

"map_from": <string>

"map_from": "gavailability"

值映射规则

<string> : <string>

"InStock": "in stock"

对于值映射规则,映射数量限制为 10 并且字符串长度限制为 20。

字母大小写规则

"type": 以下其中一项:"capitalize_first"、"capitalize_all"、"to_upper"、"to_lower"

"type": "capitalize_first"

如需了解详细信息,请参阅商品信息库规则 API 参考

获取当前规则

如需列出与信息库关联的所有规则,请对以下内容执行 HTTP GET 调用:

https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/rules

如需了解详细信息,请参阅商品信息库规则 API 参考

更新和删除规则

如需更改与信息库关联的规则,请执行 HTTP POST 调用以更新任何参数并执行 HTTP DELETE 以将其删除。您只能更新参数。如果要更改 attributerule_type,您必须删除并重新创建规则。

https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_RULE_ID}?params={PARAMS}

如需了解详细信息,请参阅商品信息库规则 API 参考

下一步:收集受众信号和构建产品受众

构建产品受众