添加新的转化

调用 Conversion.insert() 方法以添加一个或多个转化。为了正确归因转化，您的请求需要指定广告客户用于报告线下转化的 Floodlight 活动的名称，以及关键字、广告的 ID，以及可能导致转化的点击的 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，但 Campaign Manager ID 不同于 Search Ads 360 ID，无法用于归因转化。）如需查看 Floodlight 活动的 Search Ads 360 ID，请下载转化报告（通过 Search Ads 360 界面或报告 API 下载）。如果在报告的时间范围内至少有 1 次转化归因于 Floodlight 活动，您会在报告中看到 Search Ads 360 ID。

  • type：转化的类型，即 ACTION 或 TRANSACTION。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，但 Campaign Manager ID 不同于 Search Ads 360 ID，无法用于归因转化。）如需查看 Floodlight 活动的 Search Ads 360 ID，请下载转化报告（通过 Search Ads 360 界面或报告 API 下载）。如果在报告的时间范围内至少有 1 次转化归因于 Floodlight 活动，您会在报告中看到 Search Ads 360 ID。

  • type：转化的类型，即 ACTION 或 TRANSACTION。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：设置为外部归因模型。 了解详情
  • 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，但 Campaign Manager ID 不同于 Search Ads 360 ID，无法用于归因转化。）如需查看 Floodlight 活动的 Search Ads 360 ID，请下载转化报告（通过 Search Ads 360 界面或报告 API 下载）。如果在报告的时间范围内至少有 1 次转化归因于 Floodlight 活动，您会在报告中看到 Search Ads 360 ID。

  • type：转化的类型，即 ACTION 或 TRANSACTION。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 ..."
       }
    ]
  }
}

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

requestValidation 错误

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

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

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

其他类型的错误

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

响应错误

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

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