动态再营销

动态再营销广告是针对每次展示机会定制的展示广告，展示与用户之前对广告客户网站的访问相关的产品。使用 AdWords API，您可以维护展示广告网络上的动态再营销广告所依托的 Feed、FeedMapping 和 FeedItem。本指南将介绍两个使用 Feed 来更新动态再营销广告的示例。

前提条件

本指南假设您已通过 AdWords 界面设置了动态展示广告 Feed，并且您拥有相应的 Feed ID。

或者，您可以使用 API 创建 Feed、FeedMapping 和 FeedItem，以与您的动态再营销广告一起使用。有关每种类型的再营销 Feed 必需的属性和占位符字段 ID 的列表，请参阅 Feed 占位符页。

使用案例 1：添加和移除房产信息

假设您为您的房产网站制作了动态再营销广告。新信息将添加到目录，而已售出的房产将被移除。目标是更新动态再营销广告，以反映您最新的房产目录。

第 1 步 - 了解您的房产信息设置

为了管理您的房产信息，您需要提取 Feed 和房地产行业的占位符类型的 FeedMapping。FeedMapping 会告诉您 Feed 中对应于每个占位符字段的 FeedAttribute。下面的代码示例定义了提取 FeedMapping 并构建占位符 fieldId 键到 feedAttributeId 值的映射的方法。

/**
 * Returns a map from placeholder field ID to feed attribute ID for the given
 * combination of feed ID and placeholder type.
 */
public static Map<Integer, Long> getPlaceholderToAttributeMap(Long feedId,
    Integer placeholderType, AdWordsSession session, AdWordsServices adWordsServices)
    throws ApiException, RemoteException {
  Selector selector = new SelectorBuilder()
    .fields("AttributeFieldMappings")
    .equals("FeedId", feedId.toString())
    .equals("Status", FeedMappingStatus.ENABLED.getValue())
    .equals("PlaceholderType", placeholderType.toString())
    .build();

  // Get the FeedMappingService.
  FeedMappingServiceInterface feedMappingService =
    adWordsServices.get(session, FeedMappingServiceInterface.class);

  // Submit the 'get' request.
  FeedMapping feedMapping = feedMappingService.get(selector).getEntries(0);

  // Build a map from placeholder field ID to feed attribute ID from the FeedMapping.
  Map<Integer, Long> fieldMap = Maps.newHashMap();
  for(AttributeFieldMapping attributeFieldMapping :
      feedMapping.getAttributeFieldMappings()) {
    fieldMap.put(attributeFieldMapping.getFieldId(),
        attributeFieldMapping.getFeedAttributeId());
  }
  return fieldMap;
}

第 2 步 - 构造添加新房产信息的操作

既然上述实用工具方法已经就绪，构建用于添加新信息的操作就很简单明了了。每条新信息的基本步骤如下：

1. 使用实用工具方法获取占位符字段 ID 到 Feed 属性 ID 的映射。
2. 对于信息的每个属性（信息 ID、信息名称、图片网址等），请创建 FeedItemAttributeValue，其 feedAttributeId 设置为相应占位符字段的映射中找到的 ID。
3. 在 FeedItemAttributeValue 上，为属性的占位符字段设置适当的值字段。例如，对于信息 ID，因为 LISTING_ID 字段的数据类型为 STRING，请设置 stringValue 字段。
4. 获得所有 FeedItemAttributeValue 之后，创建一个新的 FeedItem，并将其 feedId 设置为您的 Feed 的 ID，其 attributeValues 设置为 FeedItemAttributeValue 的集合。
5. 创建新的 FeedItemOperation，其中运算符设置为 ADD，操作数设置为 FeedItem。

Long feedId = Long.valueOf("INSERT_FEED_ID_HERE");

List<FeedItemOperation> newFeedItemOperations = Lists.newArrayList();

// First, get the mapping from placeholder field ID to feed attribute ID.
// Note that 16 is the placeholder type ID for the Real Estate vertical.
Map<Integer, Long> fieldMap = getPlaceholderToAttributeMap(feedId,
  16, session, adWordsServices);

FeedItemAttributeValue listingId = new FeedItemAttributeValue();
listingId.setFeedAttributeId(fieldMap.get(1));
listingId.setStringValue("ABC123DEF");

FeedItemAttributeValue listingName = new FeedItemAttributeValue();
listingName.setFeedAttributeId(fieldMap.get(2));
listingName.setStringValue("Two bedroom with magnificent views");

FeedItemAttributeValue finalUrl = new FeedItemAttributeValue();
finalUrl.setFeedAttributeId(fieldMap.get(12));
finalUrl.setStringValues(new String[] {"http://www.example.com/listings/"});

// Insert additional attributes here, such as address, city, description, etc.

FeedItemAttributeValue imageUrl = new FeedItemAttributeValue();
imageUrl.setFeedAttributeId(fieldMap.get(8));
imageUrl.setStringValue("http://www.example.com/listings/images?listing_id=ABC123DEF");

FeedItemAttributeValue contextualKeywords = new FeedItemAttributeValue();
contextualKeywords.setFeedAttributeId(fieldMap.get(11));
contextualKeywords.setStringValues(
    new String[] {"beach community", "ocean view", "two bedroom"});

// Create the FeedItem, specifying the Feed ID and the attributes created above.
FeedItem feedItem = new FeedItem();
feedItem.setFeedId(feedId);
feedItem.setAttributeValues(new FeedItemAttributeValue[]{
    listingId,
    listingName,
    finalUrl,
    // Include additional attributes...
    imageUrl,
    contextualKeywords});

// Create an operation to add each FeedItem.
FeedItemOperation feedItemOperation = new FeedItemOperation();
feedItemOperation.setOperator(Operator.ADD);
feedItemOperation.setOperand(feedItem);
newFeedItemOperations.add(feedItemOperation);

// Repeat the above for additional new listings.

第 3 步 - 构造移除已售出房产信息的操作

移除已售出房产信息的程序更简单，只需每条已售出房产的 feedId 和 feedItemId 即可。

提示：如果您没有已售出房产信息的 feedItemId，则可以使用 FeedItemService.get 检索包含 feedItemId 的 FeedItem。

对于要移除的每条房产信息，请执行以下基本步骤：

1. 创建新的 FeedItem，并将其 feedId 设置为您的 Feed 的 ID，将其 feedItemId 设置为信息的项目 ID。
2. 创建新的 FeedItemOperation，其中运算符设置为 REMOVE，操作数设置为 FeedItem。

Long feedId = Long.valueOf("INSERT_FEED_ID_HERE");

List<Long> feedItemIds = Lists.newArrayList(
    // feed item ID 1,
    // feed item ID 2,
    // ...
    );

List<FeedItemOperation> removeFeedItemOperations = Lists.newArrayList();
for(Long feedItemId : feedItemIds) {
  // When removing you can simply specify the feedId and the feedItemId.
  FeedItem feedItemToRemove = new FeedItem();

  feedItemToRemove.setFeedId(feedId);
  feedItemToRemove.setFeedItemId(feedItemId);

  FeedItemOperation removeOperation = new FeedItemOperation();
  removeOperation.setOperator(Operator.REMOVE);
  removeOperation.setOperand(feedItemToRemove);

  removeFeedItemOperations.add(removeOperation);
}

第 4 步 - 提交添加和移除操作

此步骤与 API 中的任何其他 mutate 操作一样。要实际应用更改，只需将上面创建的 FeedItemOperation 的两个集合的并集传递给 FeedItemService.mutate 即可。

// Get the FeedItemService
FeedItemServiceInterface feedItemService =
    adWordsServices.get(session, FeedItemServiceInterface.class);

// Combine the lists of operations.
List<FeedItemOperation> allOperations = Lists.newArrayList(newFeedItemOperations);
allOperations.addAll(removeFeedItemOperations);

// Pass the collection of FeedItemOperations to the mutate method.
FeedItemReturnValue itemsUpdateReturnValue =
    feedItemService.mutate(allOperations.toArray(new FeedItemOperation[allOperations.size()]));

System.out.printf("Updated %d items%n", itemsUpdateReturnValue.getValue().length);

使用案例 2：更新机票价格

假设您有设置了动态再营销广告的机票预订网站，希望更新某些航班的销售价格，并移除其他航班的销售价格。为确保您的广告为每个航班显示正确的价格，您需要更新每个航班相应 FeedItem 上的价格。

第 1 步 - 构造更新销售价格的操作

该过程与创建新的 FeedItem 类似，唯一的区别是您可以仅指定要修改的 FeedItemAttributeValue，占位符字段 ID 将来自机票行业的字段列表。

对于要修改的每条航班信息，请执行以下基本步骤：

1. 使用实用工具方法获取占位符字段 ID 到 Feed 属性 ID 的映射。
2. 对于航班的每个属性（销售价格、航班全价等），请创建 FeedItemAttributeValue，其 feedAttributeId 设置为相应占位符字段的映射中找到的 ID。
3. 在 FeedItemAttributeValue 上，为属性的占位符字段设置适当的值字段。
4. 获得所有 FeedItemAttributeValue 之后，创建一个新的 FeedItem，并将其 feedId 设置为您的 Feed 的 ID，其 feedItemId 设置为航班 Feed 项 ID 的 ID，其 attributeValue 设置为 FeedItemAttributeValue 的集合。
5. 创建新的 FeedItemOperation，其中运算符设置为 SET，操作数设置为 FeedItem。

Long feedId = Long.valueOf("INSERT_FEED_ID_HERE");

List<FeedItemOperation> updateFeedItemOperations = Lists.newArrayList();

// First, get the mapping from placeholder field ID to feed attribute ID.
// Note that 13 is the placeholder type ID for the Flights vertical.
Map<Integer, Long> fieldMap = getPlaceholderToAttributeMap(feedId,
  13, session, adWordsServices);

// Update the sale price on the first flight
Long newSalePriceFeedItemId = Long.valueOf("INSERT_FEED_ITEM_ID");
FeedItemAttributeValue salePrice = new FeedItemAttributeValue();
salePrice.setFeedAttributeId(fieldMap.get(12));
salePrice.setStringValue("1,309.89 USD");

FeedItem feedItemForNewSalePrice = new FeedItem();
feedItemForNewSalePrice.setFeedId(feedId);
feedItemForNewSalePrice.setFeedItemId(newSalePriceFeedItemId);
feedItemForNewSalePrice.setAttributeValues(new FeedItemAttributeValue[] {salePrice});

// Clear the sale price on the second flight, and update its regular price
Long removedSalePriceFeedItemId = Long.valueOf("INSERT_FEED_ITEM_ID");
FeedItemAttributeValue removedSalePrice = new FeedItemAttributeValue();
removedSalePrice.setFeedAttributeId(fieldMap.get(12));

FeedItemAttributeValue newFlightPrice = new FeedItemAttributeValue();
newFlightPrice.setFeedAttributeId(fieldMap.get(6));
newFlightPrice.setStringValue("499.99 USD");

FeedItem feedItemForRemovedSalePrice = new FeedItem();
feedItemForRemovedSalePrice.setFeedId(feedId);
feedItemForRemovedSalePrice.setFeedItemId(removedSalePriceFeedItemId);
feedItemForRemovedSalePrice.setAttributeValues(
    new FeedItemAttributeValue[] {removedSalePrice, newFlightPrice});

// Create the FeedItemOperations to update the FeedItems.
for(FeedItem feedItemToUpdate : new FeedItem[]{ feedItemForNewSalePrice,
                                                feedItemForRemovedSalePrice}) {
  FeedItemOperation updateFeedItemOperation = new FeedItemOperation();
  updateFeedItemOperation.setOperator(Operator.SET);
  updateFeedItemOperation.setOperand(feedItemToUpdate);

  updateFeedItemOperations.add(updateFeedItemOperation);
}

第 2 步 - 提交更新操作

与添加和移除操作一样，要实际应用这些更改，只需将上面创建的 FeedItemOperation 的集合传递给 FeedItemService.mutate 即可。

报告

要收集动态再营销广告效果统计信息，只需使用与任何其他展示广告网络广告系列相同的报告即可。

注意：动态再营销 Feed 和 Feed 项的 Impressions 和 Cost 等效果指标不会显示在 PLACEHOLDER_REPORT 或 PLACEHOLDER_FEED_ITEM_REPORT 中。不过，您可以将 PLACEHOLDER_FEED_ITEM_REPORT 用作结构报告来检索动态再营销 Feed 项及其属性值，前提是您的请求不包含任何根据展示次数得到的效果指标或字段（例如 CampaignId 或 AdGroupId）。

更多信息

本指南用的是房产和机票的例子。如果您的动态再营销广告定位到其他行业，请查看动态再营销占位符类型的完整列表，以获取相应的占位符类型 ID 和占位符字段 ID。

如 Feed 服务指南中所述，您只应通过 CampaignFeedService 在广告系列一级关联动态再营销 Feed。您可以成功地在客户或广告组一级添加关联，但系统会忽略该关联。