添加新的转化

调用 Conversion.insert() 方法可添加一个或多个转化。为了正确归因转化，您的请求需要指定广告客户用于报告线下转化的 Floodlight 活动的名称，以及促成转化的关键字、广告和可能发生的点击的 ID。如需了解如何获取 Search Ads 360 ID，请参阅 Search Ads 360 ID 和转化。

如需了解有关上传历史转化的限制，请访问 Search Ads 360 帮助中心。

如果您的 Conversion.insert() 请求指定了多个转化，Search Ads 360 会尽力上传每个转化，而不是将整个批次作为一个整体进行上传。即使该批次中有些转化事件上传失败，其他转化事件也仍可能上传成功。转化上传可能会因请求无效或出现瞬时网络或系统故障而失败。因此，我们建议您为每次插入的转化读取响应，以确保上传成功。

多长时间之后即可使用上传的数据？

如果您为某转化指定今天或昨天的 conversionTimestamp，那么此转化的指标会在相关数据上传后的 1 小时内显示在 Search Ads 360 界面中。如果您指定的 conversionTimestamp 早于昨天，系统会在几个小时内更新相应指标。

将所有转化时间戳转换为纪元时间（也称为 Unix 时间）。

我可以通过 API 创建 Floodlight 活动吗？

如果广告客户尚未创建用于跟踪线下转化的 Floodlight 活动，您可以 使用 Campaign Manager API 创建一个。您无法使用该 API 指定 Floodlight 活动主要用于线下转化，而当出价策略将使用转化数据时，这是一种最佳实践。

我们建议，在您使用 API 创建 Floodlight 活动后，Search Ads 360 用户登录 Search Ads 360 并更改该活动的设置，以表明转化主要来自线下活动。

添加转化的最佳实践

我们建议您在添加转化时遵循以下最佳实践：

  1. 请 Search Ads 360 用户登录 Search Ads 360，然后更改您用于报告线下转化的每项 Floodlight 活动的设置。设置应表明转化的主要来源是线下活动。如需查看相关说明，请参阅 Search Ads 360 帮助中心。

  2. 获得转化数据后尽快上传。如果您要 将转化归因于具体的访问，请在相应访问发生后至少等待 6 小时，然后再上传转化数据。如果您在相应访问发生后的 6 小时内进行上传，那么 Search Ads 360 可能无法识别此访问的点击 ID。在极少数情况下，您可能需要等待长达 24 小时，Search Ads 360 才能识别点击 ID。

    确保每次上传的数据中均包含最新的转化数据。在单个上传请求中，条目可以不按时间顺序排列。不过，出价策略可能会无法考虑您晚些时候在其他请求中上传的较早的转化数据。

发送插入请求

您可以发送 Conversion.insert() 请求来执行以下任一操作：

  • 将转化归因于特定访问
  • 仅将转化归因于某个关键字

Conversion.insert() 请求中所需的字段取决于您要将转化归因于哪个事件或商品。以下部分列出了您可以将转化归因于的每个事件或商品的必需字段和选填字段。

将转化归因于特定访问

当客户点击一个或多个广告并进入广告客户的网站时，Search Ads 360 会将客户在广告客户网站上的会话视为一次访问。 如需将转化归因于某次访问，请在 Conversion.insert() 请求中指定以下内容：

必填字段

  • clickId：相应访问的区分大小写的点击 ID。在广告客户的网络日志中查找点击 ID 或列出转化，然后使用来自其他转化的点击 ID。Search Ads 360 会将转化归因于促成访问的关键字、广告和其他 Search Ads 360 对象。
    在 Search Ads 360 生成点击 ID 后，至少等待 6 小时，然后再上传转化数据。 如果您收到“找不到点击 ID”错误，请等待 24 小时，然后再次上传转化数据。 所有转化都应在生成点击 ID 后的 90 天内上传。 否则，Search Ads 360 API 可能无法识别相应访问。
  • conversionId：对于线下转化，此 ID 由广告客户提供。广告客户可以指定对他们有意义的任何 ID。请求中的每次转化都必须指定一个唯一 ID，并且 ID 和时间戳的组合在相应广告客户的所有转化中必须是唯一的。 对于线上转化，Search Ads 360 会根据广告客户的 Floodlight 指令将 dsConversionId 或 floodlightOrderId 复制到此属性中。
  • conversionTimestamp：表示转化发生的日期和时间。例如，如果转换发生在 2016 年 8 月 5 日（星期五）上午 11:53:22（美国东部夏令时 [GMT -4:00]），请以纪元毫秒为单位指定时间戳：1470412402000。
  • segmentationType：指定您要将转化上传到的转化系统的类型。目前仅支持 Floodlight 转化，因此始终需要指定 FLOODLIGHT。
  • segmentationName：广告客户用于报告转化的 Floodlight 活动的名称。

    如果您的广告客户包含名称相同的活动（如果活动属于不同的 Floodlight 组，可能会出现这种情况），建议您重命名其中一个活动。

    或者，如果您知道 Search Ads 360 为某个 Floodlight 活动分配的 ID， 则可以在 segmentationId 中指定该 ID，而不是在 segmentationName 字段中指定名称。（Campaign Manager 也会为 Floodlight 活动分配一个 ID，但该 ID 与 Search Ads 360 ID 不同，不能用于归因转化。）如需查看 Floodlight 活动的 Search Ads 360 ID，请下载转化报告（通过 Search Ads 360 界面或报告 API 下载）。如果至少有一次转化在报告的时间范围内归因于该 Floodlight 活动，您会在报告中看到 Search Ads 360 ID。

  • type：转换类型，即 ACTION 或 TRANSACTION。操作转化没有货币价值，而交易转化有货币价值。例如，电子邮件列表订阅（操作）与电子商务购买交易（交易）。

    如果您指定 TRANSACTION，则还需要指定以下字段：

    • revenueMicros：转化的货币价值。

可选字段

  • quantityMillis：相应转化中的商品数量。例如，订阅电子邮件简报的人数或售出的商品总数量。 如果您未为 ACTION 转化指定此字段，Search Ads 360 会自动插入值 1000。
  • currencyCode：交易收入的币种。默认情况下，收入以广告客户的币种为单位。如果您指定其他币种，Search Ads 360 会将指定的收入金额转换为广告客户的币种。 了解详情
    请使用 ISO 4217 字母（3 个字符）格式指定币种。
    仅适用于交易型转化。
  • customMetric 和 customDimension：上传有关转化的其他数据，例如所购商品的配送国家/地区、商品 ID，甚至电话通话时长。详细了解如何上传自定义 Floodlight 变量的数据。
  • deviceType：指定发生转化的设备类型。如需查看此字段接受的值的列表，请参阅相关文档。

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue
    "currencyCode": "USD"
  }]
}

Java

  /**
   * Instantiate the Doubleclicksearch service, create conversions, and upload them.
   */
  public static void main(String[] args) throws Exception {

    Doubleclicksearch service = getService(); // See Set Up Your Application.

    // Set up a List to keep track of each conversion you create.
    List<Conversion> conversions = new Vector<Conversion>();

    // Add a conversion to the List.
    addTransactionConversionForVisit(conversions, "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
        "test_" + System.currentTimeMillis(), 10000000L, 1378710000000L);

    // Upload the List and handle the response.
    uploadConversions(conversions, service);
  }


  /**
   * Create a TRANSACTION conversion and add it to a List<Conversion>. This sample hard-codes
   * the segmentation name and currency. You probably wouldn't want your production code to be so brittle.
   */
  private static List<Conversion> addTransactionConversionForVisit(List<Conversion> conversions,
      String clickId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion().setClickId(clickId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }


  /**
   * Convert the List of conversions to a DS ConversionList, send an insert request to DS,
   * and output the response to a file.
   */
  private static void uploadConversions(List<Conversion> conversions, Doubleclicksearch service)
      throws IOException {

    FileOutputStream outputStream =
        new FileOutputStream(new File("./", "InsertConversionsResponse.txt"));
    final PrintStream printStream = new PrintStream(outputStream);

    try {
      // Convert the List to a ConversionList.
      ConversionList conversionList = new ConversionList().setConversion(conversions);

      // Insert an upload request and download the response to a file.
      service.conversion().insert(conversionList).executeAndDownloadTo(printStream);
      printStream.close();
    } catch (GoogleJsonResponseException e) {
      System.err.println("Get request was rejected.");
      for (ErrorInfo error : e.getDetails().getErrors()) {
        System.err.println(error.getMessage());
      }
      System.exit(e.getStatusCode());
    }
  }

Python

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a visit.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with a click ID from your site
              'conversionId': 'test_20140206_00',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '10000000', // 10 million revenueMicros is equivalent to $10 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

仅将转化归因于某个关键字

如果您主要关注的是将转化归因于关键字，而不关注将转化归因于广告，那么您可以省略大部分 Search Ads 360 标识符，仅指定关键字的标识符以及其他几个字段：

必填字段

  • criterionId：这是关键字标识符。您可以通过向着陆页网址添加 TrackerId 宏来获取 criterionId。如需了解如何获取关键字 ID，请参阅 Search Ads 360 ID 和转化。
  • conversionId：对于线下转化，此 ID 由广告客户提供。广告客户可以指定对他们有意义的任何 ID。请求中的每次转化都必须指定一个唯一 ID，并且 ID 和时间戳的组合在相应广告客户的所有转化中必须是唯一的。 对于线上转化，Search Ads 360 会根据广告客户的 Floodlight 指令将 dsConversionId 或 floodlightOrderId 复制到此属性中。
  • conversionTimestamp：表示转化发生的日期和时间。例如，如果转换发生在 2016 年 8 月 5 日（星期五）上午 11:53:22（美国东部夏令时 [GMT -4:00]），请以纪元毫秒为单位指定时间戳：1470412402000。
  • segmentationType：指定您要将转化上传到的转化系统的类型。目前仅支持 Floodlight 转化，因此始终需要指定 FLOODLIGHT。
  • segmentationName：广告客户用于报告转化的 Floodlight 活动的名称。

    如果您的广告客户包含名称相同的活动（如果活动属于不同的 Floodlight 组，可能会出现这种情况），建议您重命名其中一个活动。

    或者，如果您知道 Search Ads 360 为某个 Floodlight 活动分配的 ID， 则可以在 segmentationId 中指定该 ID，而不是在 segmentationName 字段中指定名称。（Campaign Manager 也会为 Floodlight 活动分配一个 ID，但该 ID 与 Search Ads 360 ID 不同，不能用于归因转化。）如需查看 Floodlight 活动的 Search Ads 360 ID，请下载转化报告（通过 Search Ads 360 界面或报告 API 下载）。如果至少有一次转化在报告的时间范围内归因于该 Floodlight 活动，您会在报告中看到 Search Ads 360 ID。

  • type：转换类型，即 ACTION 或 TRANSACTION。操作转化没有货币价值，而交易转化有货币价值。例如，电子邮件列表订阅（操作）与电子商务购买交易（交易）。

    如果您指定 TRANSACTION，则还需要指定以下字段：

    • revenueMicros：转化的货币价值。

可选字段

  • quantityMillis：相应转化中的商品数量。例如，订阅电子邮件简报的人数或售出的商品总数量。 如果您未为 ACTION 转化指定此字段，Search Ads 360 会自动插入值 1000。
  • currencyCode：交易收入的币种。默认情况下，收入以广告客户的币种为单位。如果您指定其他币种，Search Ads 360 会将指定的收入金额转换为广告客户的币种。 了解详情
    请使用 ISO 4217 字母（3 个字符）格式指定币种。
    仅适用于交易型转化。
  • customMetric 和 customDimension：上传有关转化的其他数据，例如所购商品的配送国家/地区、商品 ID，甚至电话通话时长。详细了解如何上传自定义 Floodlight 变量的数据。
  • deviceType：指定发生转化的设备类型。如需查看此字段接受的值的列表，请参阅相关文档。

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "criterionId": "43700003491981017", // Replace with your ID
    "conversionId": "customerTransaction73126",
    "conversionTimestamp": "1351196386000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "Offline Purchase",
    "type": "TRANSACTION",
    "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue
    "currencyCode": "USD"
  }]
}

Java

  /**
   * Creates a TRANSACTION conversion, attributes it to a keyword only, and adds it to a List<Conversion>.
   * The example in the preceding section contains the uploadConversions method,
   * which can submit the list as an insert() request.
   */
  private static List<Conversion> addTransactionConversionForKeyword(List<Conversion> conversions,
      Long criterionId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion()
        .setCriterionId(criterionId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }

Python

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a keyword only.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'criterionId': '43700004289911004', // Replace with your ID
              'conversionId': 'test_1378710000000',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '20000000', // 20 million revenueMicros is equivalent to $20 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

上传第三方归因模型中的数据

归因模型可在转化路径中的所有活动之间分配转化功劳。例如，如果消费者在进行转化前点击了一个付费搜索广告、一个展示广告以及另一个付费搜索广告，线性归因模型便会向每次点击分配 33% 的转化功劳。

虽然 Search Ads 360 提供归因模型，但如果您使用第三方服务或您自己开发的某项服务向点击分配功劳，则可将第三方归因数据上传到 Search Ads 360，并可在报告和 Search Ads 360 出价策略中使用这些数据。

前期准备

在 Campaign Manager 中，创建一个自定义归因模型，然后将该模型导入 Search Ads 360。请务必将此模型命名为外部归因模型。 这样一来，Search Ads 360 功能便可识别出您上传的转化数据已应用了某个归因模型。了解详情

必填字段

如需将第三方归因模型应用于转化，请在 Conversion.insert() 请求中指定以下所有内容：

  • clickId：相应访问的区分大小写的点击 ID。在广告客户的网络日志中查找点击 ID 或列出转化，然后使用来自其他转化的点击 ID。Search Ads 360 会将转化归因于促成访问的关键字、广告和其他 Search Ads 360 对象。
    在 Search Ads 360 生成点击 ID 后，至少等待 30 分钟，然后再上传包含该 ID 的转化。 否则，Search Ads 360 API 可能无法识别相应访问。
  • attributionModel：设置为 External Attribution Model。 了解详情
  • countMillis：要分配给相应点击的转化信用额度。 仅当请求还包含 attributionModel 字段时适用。

    请勿将此字段与 quantityMillis 混淆，后者是一个可选字段，用于指定一次转化涉及的商品数量（例如，购物车购买交易中的商品数量）。

  • conversionId：对于线下转化，此 ID 由广告客户提供。广告客户可以指定对他们有意义的任何 ID。请求中的每次转化都必须指定一个唯一 ID，并且 ID 和时间戳的组合在相应广告客户的所有转化中必须是唯一的。 对于线上转化，Search Ads 360 会根据广告客户的 Floodlight 指令将 dsConversionId 或 floodlightOrderId 复制到此属性中。
  • conversionTimestamp：表示转化发生的日期和时间。例如，如果转换发生在 2016 年 8 月 5 日（星期五）上午 11:53:22（美国东部夏令时 [GMT -4:00]），请以纪元毫秒为单位指定时间戳：1470412402000。
  • segmentationType：指定您要将转化上传到的转化系统的类型。目前仅支持 Floodlight 转化，因此始终需要指定 FLOODLIGHT。
  • segmentationName：广告客户用于报告转化的 Floodlight 活动的名称。

    如果您的广告客户包含名称相同的活动（如果活动属于不同的 Floodlight 组，可能会出现这种情况），建议您重命名其中一个活动。

    或者，如果您知道 Search Ads 360 为某个 Floodlight 活动分配的 ID， 则可以在 segmentationId 中指定该 ID，而不是在 segmentationName 字段中指定名称。（Campaign Manager 也会为 Floodlight 活动分配一个 ID，但该 ID 与 Search Ads 360 ID 不同，不能用于归因转化。）如需查看 Floodlight 活动的 Search Ads 360 ID，请下载转化报告（通过 Search Ads 360 界面或报告 API 下载）。如果至少有一次转化在报告的时间范围内归因于该 Floodlight 活动，您会在报告中看到 Search Ads 360 ID。

  • type：转换类型，即 ACTION 或 TRANSACTION。操作转化没有货币价值，而交易转化有货币价值。例如，电子邮件列表订阅（操作）与电子商务购买交易（交易）。

    如果您指定 TRANSACTION，则还需要指定以下字段：

    • revenueMicros：转化的货币价值。

如果您跟踪转化收入，请确保您的模型可向转化路径中的每个接触点分配收入。例如，如果您的模型使用了线性方法（向每个接触点平均分配收入），那么在包含 3 次广告点击的转化路径中，系统便会向每次点击分别分配 33% 的转化收入。如果相应转化带来了 100 美元的收入，请确保您的模型会向每次点击分别分配 33 美元的收入，并确保 revenueMicros 会仅为每次点击指定 33 美元的收入。

可选字段

  • quantityMillis：相应转化中的商品数量。例如，订阅电子邮件简报的人数或售出的商品总数量。 如果您未为 ACTION 转化指定此字段，Search Ads 360 会自动插入值 1000。
  • currencyCode：交易收入的币种。默认情况下，收入以广告客户的币种为单位。如果您指定其他币种，Search Ads 360 会将指定的收入金额转换为广告客户的币种。 了解详情
    请使用 ISO 4217 字母（3 个字符）格式指定币种。
    仅适用于交易型转化。
  • customMetric 和 customDimension：上传有关转化的其他数据，例如所购商品的配送国家/地区、商品 ID，甚至电话通话时长。详细了解如何上传自定义 Floodlight 变量的数据。
  • deviceType：指定发生转化的设备类型。如需查看此字段接受的值的列表，请参阅相关文档。

示例

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "PP5K8iI6ul7Vw09JZZDEp", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "attributionModel": "External Attribution Model",
    "countMillis": "330",
    "revenueMicros": "33000000", // 33 million revenueMicros is equivalent to $33 of revenue
    "currencyCode": "USD"
  }]
}

处理 Search Ads 360 响应

仅当请求中的所有转化都已成功验证并上传时，Search Ads 360 的响应才会指示成功。

如果请求成功

如果请求成功，响应将包含每个上传转化的完整 Search Ads 360 内部表示形式，例如广告系列 ID、广告组 ID 和关键字（条件）ID。

{
 "kind": "doubleclicksearch#conversionList",
 "conversion": [
  {
   "agencyId": "12300000000000456",
   "advertiserId": "45600000000010291",
   "engineAccountId": "700000000042441",
   "campaignId": "71700000002044839",
   "adGroupId": "58700000032026064",
   "criterionId": "43700004289911004",
   "adId": "0",
   "dsConversionId": "48719131694768384",
   "conversionId": "test_1383157331951",
   "state": "ACTIVE",
   "type": "TRANSACTION",
   "revenueMicros": "20000000",
   "currencyCode": "USD",
   "segmentationType": "FLOODLIGHT",
   "segmentationId": "25700000001464141",
   "segmentationName": "Test",
   "conversionTimestamp": "1378710000000",
   "conversionModifiedTimestamp": "1383157332368"
  },
  ...
 ]
}

如果请求未成功

如果一个或多个转化未能通过验证或上传，响应会包含每项失败的转化上传对应的消息。响应不包含有关成功上传的转化的消息。

以下是未完全成功的请求的示例响应：

{
 "error": {
    "errors": [
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details: [0x0000011F: Advertiser conversion ID ..."
       },
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details:  [0x00000101: Click ID ..."
       }
    ]
  }
}

每条失败消息都包含两个重要字段：原因和详细的错误消息。原因字段可以包含 requestValidation、internalError、transactionFailed 或 lateStageRequestError。

requestValidation 错误

requestValidation 错误表示转化上传请求中存在数据问题（例如，转化已上传，或者找不到 clickId）。在此类错误中，消息详细信息包含两项内容：

  • 用于标识错误类型的十六进制代码。您可以在自己的脚本中使用该代码来识别错误。
  • 验证错误的说明。

如需了解详情，请参阅 Search Ads 360 针对转化上传错误可返回的代码和说明列表。

其他类型的错误

所有其他类型的错误（internalError、transactionFailed 或 lateStageRequestError）都表示 Search Ads 360 存在内部问题。

应对错误

如果请求失败，请稍后尝试重新提交整个请求调用。Search Ads 360 会针对已上传的所有转化报告 requestValidation 错误，但会尝试上传剩余的转化。

如果您在重新提交后仍看到错误，请参阅问题排查部分，了解如何继续操作。