调用 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 并更改该活动的 设置来指明 转化就是线下活动。
添加转化的最佳做法
我们建议您在添加转化时遵循以下最佳做法：
让 Search Ads 360 用户登录 Search Ads 360 并更改设置 （针对您用于报告线下转化数据的每个 Floodlight 活动）。设置应 表明离线活动是主要转化来源。请参阅 Search Ads 360 帮助中心 了解相关说明。
转化数据可用后，尽快上传。如果您是 将转化归因于特定访问，则要在发生转化后至少等待 30 分钟， 然后再上传转化数据如果出现以下情况，Search Ads 360 可能无法识别访问的点击 ID： 在光顾实体店后 30 分钟内上传。在极少数情况下，您可能需要 最多需要等待 4 小时，Search Ads 360 才能识别此 clickId。
确保每次上传的数据中都包含最新的转化数据。在单个 上传请求中，即使条目未按时间顺序排列也没关系。但出价策略可能会 无法考虑您稍后在其他请求中上传的较早的转化数据。
如果您在为 Floodlight 活动上传转化数据之前等待的时间超过 24 小时， 发送 库存状况时间戳。
适用范围时间戳应为以下其中一项：
- 如果您在过去 24 小时内记录了转化但尚未上传 但时间戳应为最后一次上传转化数据的时间 出现故障。这会告知 Search Ads 360 可能发生了转化 但您尚未提供数据。出价策略和 其他自动化系统将仅考虑过去一段时间内的效果历史记录 转化数据。
- 如果过去 24 小时内未发生任何转化，则时间戳为 当前时间和日期。这会告知 Search Ads 360 在过去 24 小时内获得了 次转化。出价策略和其他自动出价策略 系统会将过去 24 小时（没有转化的一整天）的数据纳入考量范围， 部分。
发送插入请求
您可以发送 Conversion.insert() 请求以执行以下任一操作：
- 将转化归因于特定访问
- 将转化仅归因于关键字
Conversion.insert() 请求中所需的字段取决于
事件或项。以下部分列出了
和可选属性。
将转化归因于特定访问
当客户在点击一个或多个广告后进入广告客户的网站时，
Search Ads 360 会将广告客户网站上的用户会话视为一次访问。
要将转化归因于某次访问，请在 Conversion.insert() 中指定以下内容
请求：
必填字段
clickId：访问的点击 ID（区分大小写）。在 广告客户的网络日志获取点击 ID 或列出转化，并使用 点击 ID。Search Ads 360 会将此次转化归因于 导致出现故障的关键字、广告和其他 Search Ads 360 对象 。
之后至少等待 30 分钟 Search Ads 360 会生成一个点击 ID 来上传转化数据。 如果您收到“未找到点击 ID”的错误消息出错，等待 4 小时，然后上传 再次获得转化。 所有转化数据均应在提交转化后的 90 天内上传， 点击 ID 即可生成。 否则，Search Ads 360 API 可能无法识别本次访问。conversionId：对于线下转化，广告客户应提供此 ID。广告客户可以 指定对他们有意义的任何 ID。请求中的每次转化都必须指定一个唯一 ID 并且 ID 和时间戳的组合在该广告客户的所有转化中必须是唯一的。 对于线上转化，Search Ads 360 会复制dsConversionId或floodlightOrderId此属性中。conversionTimestamp：表示 发生了转化。例如，如果 转换发生在 2016 年 8 月 5 日星期五上午 11:53:22（美国东部夏令时间 (GMT -4:00)）， 指定时间戳（以从公元纪年开始计算的毫秒数表示）：1470412402000。segmentationType：指定您要上传的转化系统的类型 。目前仅支持 Floodlight 转化，因此此字段 始终必须指定FLOODLIGHT。segmentationName：该广告客户的 Floodlight 活动的名称 来报告转化如果广告客户中包含同名的活动（如果这些活动 属于不同的 Floodlight 活动组），则建议采取的操作是 重命名其中一个活动。
或者，如果您知道 Search Ads 360 已将此 ID 分配给 Floodlight 活动， 则可以在
segmentationId中指定 ID，而不是在segmentationName字段中的值。（Campaign Manager 还会为此 Floodlight 活动分配一个 ID， 但 Campaign Manager ID 不同于 Search Ads 360 ID，因此无法用于归因 conversions.)要查看某个 Floodlight 活动的 Search Ads 360 ID，请下载 转化报告（来自 Search Ads 360 界面或报表 API）。如果在实施期间内已将至少一次转化归因于 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 个字符） format 以指定货币。
仅适用于 TRANSACTION 转化。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 会复制dsConversionId或floodlightOrderId此属性中。conversionTimestamp：表示 发生了转化。例如，如果 转换发生在 2016 年 8 月 5 日星期五上午 11:53:22（美国东部夏令时间 (GMT -4:00)）， 指定时间戳（以从公元纪年开始计算的毫秒数表示）：1470412402000。segmentationType：指定您要上传的转化系统的类型 。目前仅支持 Floodlight 转化，因此此字段 始终必须指定FLOODLIGHT。segmentationName：该广告客户的 Floodlight 活动的名称 来报告转化如果广告客户中包含同名的活动（如果这些活动 属于不同的 Floodlight 活动组），则建议采取的操作是 重命名其中一个活动。
或者，如果您知道 Search Ads 360 已将此 ID 分配给 Floodlight 活动， 则可以在
segmentationId中指定 ID，而不是在segmentationName字段中的值。（Campaign Manager 还会为此 Floodlight 活动分配一个 ID， 但 Campaign Manager ID 不同于 Search Ads 360 ID，因此无法用于归因 conversions.)要查看某个 Floodlight 活动的 Search Ads 360 ID，请下载 转化报告（来自 Search Ads 360 界面或报表 API）。如果在实施期间内已将至少一次转化归因于 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 个字符） format 以指定货币。
仅适用于 TRANSACTION 转化。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。请务必将此模型命名为External Attribution Model。 这样一来，Search Ads 360 功能便可识别归因模型已应用于 您上传的转化数据。学习 更多
必填字段
要对转化应用第三方归因模型，请在
您的 Conversion.insert() 请求：
clickId：访问的点击 ID（区分大小写）。在 广告客户的网络日志获取点击 ID 或列出转化，并使用 点击 ID。Search Ads 360 会将此次转化归因于 导致出现故障的关键字、广告和其他 Search Ads 360 对象 。
之后至少等待 30 分钟 Search Ads 360 会在上传具有点击 ID 的转化之前生成点击 ID。 否则，Search Ads 360 API 可能无法识别本次访问。attributionModel：设置为External Attribution Model。 了解详情countMillis：要分配给此次点击的转化功劳金额。 仅当请求还包含attributionModel字段时适用。请勿将它与
quantityMillis混淆，后者是一个可选字段，用于指定 一次转化涉及的商品数量（例如购物车中的商品数量） 购买）。conversionId：对于线下转化，广告客户应提供此 ID。广告客户可以 指定对他们有意义的任何 ID。请求中的每次转化都必须指定一个唯一 ID 并且 ID 和时间戳的组合在该广告客户的所有转化中必须是唯一的。 对于线上转化，Search Ads 360 会复制dsConversionId或floodlightOrderId此属性中。conversionTimestamp：表示 发生了转化。例如，如果 转换发生在 2016 年 8 月 5 日星期五上午 11:53:22（美国东部夏令时间 (GMT -4:00)）， 指定时间戳（以从公元纪年开始计算的毫秒数表示）：1470412402000。segmentationType：指定您要上传的转化系统的类型 。目前仅支持 Floodlight 转化，因此此字段 始终必须指定FLOODLIGHT。segmentationName：该广告客户的 Floodlight 活动的名称 来报告转化如果广告客户中包含同名的活动（如果这些活动 属于不同的 Floodlight 活动组），则建议采取的操作是 重命名其中一个活动。
或者，如果您知道 Search Ads 360 已将此 ID 分配给 Floodlight 活动， 则可以在
segmentationId中指定 ID，而不是在segmentationName字段中的值。（Campaign Manager 还会为此 Floodlight 活动分配一个 ID， 但 Campaign Manager ID 不同于 Search Ads 360 ID，因此无法用于归因 conversions.)要查看某个 Floodlight 活动的 Search Ads 360 ID，请下载 转化报告（来自 Search Ads 360 界面或报表 API）。如果在实施期间内已将至少一次转化归因于 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 个字符） format 以指定货币。
仅适用于 TRANSACTION 转化。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）。在本课中， 则 details 消息包含两项：
- 用于标识错误类型的十六进制代码。您可以使用自己的代码 以找出错误。
- 对验证错误的说明。
有关详情，请参阅 代码列表 说明。
其他类型的错误
所有其他类型的错误（internalError、transactionFailed、 或 lateStageRequestError）表示 Search Ads 360。
响应错误
如果请求失败，请稍后尝试重新提交整个请求调用。Search Ads 360 对于您之前未点击过的所有转化，系统都会报告 requestValidation 错误 ，但它会尝试上传剩余的转化数据。
如果您在重新提交后仍然看到错误，请查看 问题排查 部分，了解有关如何继续操作的信息。