修改现有转化

调用 Conversion.update() 方法,对一个或多个现有转化进行以下类型的更改:

Search Ads 360 不支持更改以下内容:

  • 转化日期。
  • 转化类型。
  • 归因于转化的关键字或访问。
  • Floodlight 活动或活动名称。

不过,您可以随时将现有转化标记为 REMOVED,并上传包含更新日期、类型、归因 ID 或 Floodlight 活动的新转化(请务必同时指定新的 conversionId)。

您可以修改通过 Search Ads 360 API 上传的转化数据(线下转化数据)和 Search Ads 360 通过 Floodlight 代码记录的转化数据(线上转化数据),但须遵守以下时间限制:

  • 如果您通过 clickId 标识转化,则点击 ID 必须是在过去 60 天内生成的(否则会显示错误代码 0x0000012F)。
  • 通过 Floodlight 代码记录的转化只能在 conversionTimestamp 后的 28 天内修改(否则会显示错误代码 0x00000125)。

与 Conversion.insert() 一样,如果您的更新请求指定了多项转化,Search Ads 360 会尽力更新每项转化,而不是将整个批次作为一笔交易进行更新(要么全部更新,要么全部不更新)。如果批处理中的某些更新失败,其他更新可能仍会成功。我们建议您阅读每个更新后的转化的响应,以确保更新成功。

dsConversionId 的弃用

dsConversionId 字段已被弃用,无法再用于标识转化。您必须使用 conversionId(广告客户转化 ID)在 Search Ads 360 Conversion API 中修改转化。如果转化存在以下任一情况,Conversion.update() 会拒绝该转化,并显示错误代码 0x0000013C (Conversion editing using integer DS conversion ID is deprecated):

  • 指定 dsConversionId 字段,或
  • 在 conversionId 字段中传递 Search Ads 360 转化 ID(Search Ads 360 为每次转化生成的 17 位数字 ID)。

主要变化:

  • dsConversionId 弃用:Search Ads 360 Conversion API、Search Ads 360 Reporting API(称为 conversion.id)或报告界面(称为“转化 ID”)中不再支持 dsConversionID。
  • conversionId 要求:conversionId 是通过 Search Ads 360 Conversion API 修改转化数据的必填字段。

如何获取 conversionId:

  • 通过 Search Ads 360 API 上传的转化数据:使用您在插入转化数据时指定的 conversionId。
  • 通过 Floodlight 代码记录的转化:使用 Floodlight 代码针对转化报告的 Floodlight 订单 ID(ord 值),例如 Floodlight 销售活动的订单或交易 ID。
  • Search Ads 360 Reporting API:您可以使用 Search Ads 360 Reporting API 检索 advertiser_conversion_id。 此值对应于修改所需的 conversionId。
  • Search Ads 360 界面:您可以在 Search Ads 360 界面的转化报告页面中找到“广告客户转化 ID”。 SA360 报告中的转化 ID

发送更新请求

您在 Conversion.update() 中指定的大多数字段都用于标识要更新的转化。您可以使用以下任一方法来标识现有转化:

  • 指定转化的 clickId
    • 所有修改后的转化都必须在点击 ID 生成后的 60 天内发生。
  • 指定转化的关键字(customerId、campaignId、adGroupId 和 criterionId)

这两种方法都要求您指定转化的 conversionId、conversionTimestamp 和交易 type。conversionTimestamp 必须是现有转化的时间戳,采用世界协调时间 (UTC) 纪元毫秒数。如果时间戳与现有转化不匹配(例如,因为它是从本地时区转换而来的),Search Ads 360 将无法找到该转化,并会返回错误代码 0x0000011B。

对于 Search Ads 360 通过 Floodlight 代码记录的转化,您还必须指定转化的 Floodlight 活动(segmentationType 以及 segmentationName 或 segmentationId)。否则,请求会失败,并返回错误代码 0x0000010C。我们建议您在每个更新请求中指定 Floodlight 活动。

此外,如果原始转化指定了 revenueMicros 和 currencyCode 或 quantityMillis,则更新请求需要指定这些数据,即使您不更改这些数据也是如此。

按点击 ID 识别转化

如果转化最初指定了点击 ID,您可以发送指定以下字段的 Conversion.update() 请求:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • segmentationType 和 segmentationName(或 segmentationId)(对于通过 Floodlight 代码记录的转化,此参数为必填参数;对于所有转化,此参数为推荐参数)
  • state(仅当您想将状态更改为 REMOVED 或 ACTIVE 时才需要)
  • quantityMillis(仅当在原始转化中指定时)
  • revenueMicros(仅当在原始转化中指定时)
  • currencyCode(仅当在原始转化中指定时)

示例

以下是两个现有转化的示例:

{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA",
    "conversionId" : "test_20130906_10",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "100000000", // 100 million revenueMicros is equivalent to $100 of revenue
    "currencyCode": "USD"
  },
  {
   "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA",
   "conversionId": "test_1383337059137",
   "conversionTimestamp": "1378710000000",
   "segmentationType" : "FLOODLIGHT",
   "segmentationName" : "Test",
   "type": "ACTION",
   "quantityMillis": "1000"
  }]
}     

以下请求会更新上一个示例中的一个转化,并移除另一个转化:

JSON

请注意,Conversion.update() 请求使用 PUT HTTP 方法。

PUT 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 data from your site
   "conversionId": "test_20130906_10",
   "conversionTimestamp": "1378710000000",
   "segmentationType" : "FLOODLIGHT",
   "segmentationName" : "Test",
   "type": "TRANSACTION",
   "revenueMicros": "90000000", // 90 million revenueMicros is equivalent to $90 of revenue
   "currencyCode": "USD"
  },
  {
   "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site
   "conversionId": "test_1383337059137",
   "conversionTimestamp": "1378710000000",
   "segmentationType" : "FLOODLIGHT",
   "segmentationName" : "Test",
   "type": "ACTION",
   "quantityMillis": "1000",
   "state": "REMOVED"
  }
 ]
}        

Java

/**
 * Instantiate the Doubleclicksearch service, create a conversion that updates an existing conversion,
 * and upload the conversions.
 */
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>();

  // Create a conversion and add it to the conversion list.
  // Just to get a little fancy, the updateConversionFromVisit() method can be used for all
  // visit conversions, including conversions that don't specify quantity, revenue, or currency.
  // If quantityMillis wasn't specified in the original conversion, specify -1L for the
  // quantityMillis parameter. Likewise, if revenueMicros wasn't specified originally,
  // specify -1L for the revenueMicros parameter and an empty string for currency.
  conversionList = updateConversionFromVisit(
      conversionList,
      "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site
      "test_20130906_10",           // conversionId
      1378710000000L,               // timeStamp
      "TRANSACTION",                // type
      "",                           // state
      -1L,                          // quantityMillis
      90000000L,                    // revenueMicros. Equivalent to $90 of revenue
      "USD");                       // currencyCode

   // Here's a conversion that needs to be removed. Just set the state parameter to "REMOVED".
   conversionList = updateConversionFromVisit(
      conversionList,
      "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site
      "test_1383337059137",         // conversionId
      1378710000000L,               // timeStamp
      "ACTION",                     // type
      "REMOVED",                    // state
      1000L,                        // quantityMillis
      -1L,                          // revenueMicros
      "");                          // currencyCode

    // Upload the List and handle the response.
    uploadConversions(conversions, service); // See an example in Add New Conversions. 
  }

/**
 * Create a conversion and add it to a List<Conversion>.
 */
  private static List<Conversion> updateConversionFromVisit(List<Conversion> conversions,
      String clickId,
      String conversionId,
      Long timeStamp,
      String type,
      String state,
      Long quantity,
      Long revenue,
      String currency) {

    // Identifies the existing conversion. This sample hard-codes the segmentation name.
    Conversion conversion = new Conversion()
        .setClickId(clickId)
        .setConversionId(conversionId)
        .setConversionTimestamp(BigInteger.valueOf(timeStamp))
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType(type);

    // Only add these fields if the value is not empty greater than -1.
    if(!state.isEmpty()) conversion.setState(state);
    if (quantity > -1L) {
      conversion.setQuantityMillis(quantity);
    }
    if (revenue > -1L) {
      conversion.setRevenueMicros(revenue);
      if (!currency.isEmpty()) {
        conversion.setCurrencyCode(currency);
      } else {
        System.err.println(String.format(
            "Can't add conversion %s. It specifies revenue but no currency.",
            conversion.getConversionId()));
        return conversions;
      }
    }

    conversions.add(conversion);
    return conversions;
  }         

Python

def update_conversion(service):
  """Change the revenue for one existing conversion and remove another.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().update(
      body=
      {
          'conversion' : [{
              'clickId' : 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site
              'conversionId' : 'test_20130906_13',
              'conversionTimestamp' : '1378710000000',
              'segmentationType' : 'FLOODLIGHT',
              'segmentationName' : 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '90000000', // 90 million revenueMicros is equivalent to $90 of revenue
              'currencyCode': 'USD'
            },
            {
             'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site
             'conversionId': 'test_1383337059137_01',
             'conversionTimestamp': '1378710000000',
             'segmentationType' : 'FLOODLIGHT',
             'segmentationName' : 'Test',
             'type': 'ACTION',
             'quantityMillis': '1000',
             'state': 'REMOVED'
            }]
      }
  )

  pprint.pprint(request.execute())

按关键字 ID 识别转化

如果您无权访问点击 ID,或者转化最初归因于关键字或关键字/广告,则可以发送指定以下字段的 Conversion.update() 请求:

  • customerId、campaignId、adGroupId 和 criterionId(用于标识关键字的新版 Search Ads 360 ID)
  • conversionId
  • conversionTimestamp
  • type
  • state(仅当您想将状态更改为 REMOVED 或 ACTIVE 时才需要)
  • quantityMillis(仅当在原始转化中指定时)
  • revenueMicros(仅当在原始转化中指定时)
  • currencyCode(仅当在原始转化中指定时)

关键字 ID 仅在广告组内是唯一的,因此您需要指定所有这四个 ID。 如果转化指定了 criterionId,但未指定 customerId、campaignId 或 adGroupId,则更新会失败,并显示错误代码 0x0000012E。您无需指定其他 ID,例如转化的广告 ID。

示例

以下是现有转化的示例:

{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
   "customerId": "123-456-7890",
   "campaignId": "14660344555",
   "adGroupId": "105138634255",
   "criterionId": "948710340465",
   "conversionId": "test_1383157519886",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "1000",
   "segmentationType": "FLOODLIGHT",
   "segmentationName": "Test"
  }]
}     

以下请求会更新转化次数:

JSON

请注意,Conversion.update() 请求使用 PUT HTTP 方法。

PUT https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
 "conversion": [
  {
   "customerId": "123-456-7890", // Replace with your ID
   "campaignId": "14660344555", // Replace with your ID
   "adGroupId": "105138634255", // Replace with your ID
   "criterionId": "948710340465", // Replace with your ID
   "conversionId": "test_1383157519886",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "3000"
  }
 ]
}        

Java

    // Send conversion data to updateConversion, which creates a conversion and adds it
    // to the conversion list.
    conversionList =  updateConversionFromKeyword(conversionList,
        "123-456-7890",       // customerId. Replace with your ID
        14660344555L,         // campaignId. Replace with your ID
        105138634255L,        // adGroupId. Replace with your ID
        948710340465L,        // criterionId. Replace with your ID
        "test_1383157519886", // conversionId
        1378710000000L,       // timeStamp
        "ACTION",             // type
        "",                   // state
        3000L,                // quantityMillis
        -1L,                  // revenueMicros
        "");                  // currencyCode

  private static List<Conversion> updateConversionFromKeyword(List<Conversion> conversions,
       String customerId,
       Long campaignId,
       Long adGroupId,
       Long criterionId,
       String conversionId,
       Long timeStamp,
       String type,
       String state,
       Long quantity,
       Long revenue,
       String currency
    ) {

   Conversion conversion = new Conversion()
   .setCustomerId(customerId)
   .setCampaignId(campaignId)
   .setAdGroupId(adGroupId)
   .setCriterionId(criterionId)
   .setConversionId(conversionId)
   .setConversionTimestamp(BigInteger.valueOf(timeStamp))
   .setType(type);

   // Only add these fields if the value is not empty greater than -1.
   if(!state.isEmpty()) conversion.setState(state);
   if (quantity > -1L) {
     conversion.setQuantityMillis(quantity);
   }
   if (revenue > -1L) {
     conversion.setRevenueMicros(revenue);
     if (!currency.isEmpty()) {
       conversion.setCurrencyCode(currency);
     } else {
       System.err.println(String.format(
           "Can't add conversion %s. It specifies revenue but no currency.",
           conversion.getConversionId()));
       return conversions;
     }
   }

   conversions.add(conversion);
   return conversions;
   }                 

Python

def update_conversion(service):
  """Change the quantity of a conversion. Use the keyword's IDs (customerId,
  campaignId, adGroupId, and criterionId) to identify the conversion.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().update(
      body=
      {
          'conversion': [{
              'customerId': '123-456-7890', // Replace with your ID
              'campaignId': '14660344555', // Replace with your ID
              'adGroupId': '105138634255', // Replace with your ID
              'criterionId': '948710340465', // Replace with your ID
              'conversionId': 'test_1383157519886',
              'conversionTimestamp': '1378710000000',
              'type': 'ACTION',
              'quantityMillis': '3000'
            }]
      }
  )

  pprint.pprint(request.execute())

处理 Search Ads 360 响应

更新请求的响应与插入请求的响应相同:只有在请求中的所有转化都已成功更新时,Search Ads 360 才会指示成功。

如果请求成功,响应中会包含每个更新后的转化的完整 Search Ads 360 内部表示,例如新版 Search Ads 360 客户 ID、广告系列 ID、广告组 ID 和关键字(条件)ID。

如果一个或多个更新未能通过验证或上传失败,响应中会包含每个失败更新的失败消息。响应不包含有关已成功更新的转化的消息。 如需详细了解这些失败消息,请参阅处理 Search Ads 360 针对插入请求的响应。