调用 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 分钟，然后再上传转化数据。如果您在相应访问发生后的 30 分钟内上传，Search Ads 360 可能无法识别此访问的点击 ID。在极少数情况下，您可能需要等待 4 小时，Search Ads 360 才能识别此 clickId。
确保每次上传的数据中都包含最新的转化数据。在单个上传请求中，允许出现各条目未按时间顺序排列的情况。但是，出价策略可能无法考虑您稍后在其他请求中上传的较早的转化数据。
如果您在为某个 Floodlight 活动上传转化数据之前等待的时间超过 24 小时，请发送适用范围时间戳。
适用范围时间戳应为以下其中一项：
- 如果您在过去 24 小时内记录了转化，但尚未上传转化数据，则时间戳应为上次上传转化发生的时间。此列会告知 Search Ads 360 过去 24 小时内可能发生了转化，但您尚未提供相关数据。出价策略和其他自动化系统将仅考虑您最近一次上传转化数据时的效果历史记录。
- 如果过去 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 对象。
在 Search Ads 360 生成点击 ID 后，请至少等待 30 分钟，然后再上传转化数据。 如果您收到“未找到点击 ID”错误，请等待 4 小时，然后重新上传转化数据。 所有转化数据都应在生成点击 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 界面或 Reporting 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 个字符）格式指定币种。
仅适用于 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：这是关键字标识符。要获取criterionId，只需将TrackerId宏添加到着陆页网址中即可。如需了解如何获取关键字 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 界面或 Reporting 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 个字符）格式指定币种。
仅适用于 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 对象。
在 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，但 Campaign Manager ID 不同于 Search Ads 360 ID，并且不能用于对转化进行归因。）如需查看 Floodlight 活动的 Search Ads 360 ID，请（通过 Search Ads 360 界面或 Reporting 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 个字符）格式指定币种。
仅适用于 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 包含两个项：
- 用于标识错误类型的十六进制代码。您可以使用自己的脚本中的代码来识别错误。
- 对验证错误的说明。
有关详情，请参阅 Search Ads 360 针对转化数据上传错误返回的代码和说明列表。
其他类型的错误
所有其他类型的错误（internalError、transactionFailed 或 lateStageRequestError）都表示 Search Ads 360 中存在内部问题。
响应错误
如果请求失败，请稍后尝试重新提交整个请求调用。对于已上传的所有转化数据，Search Ads 360 都会报告 requestValidation 错误，但会尝试上传其余的转化数据。
如果您在重新提交后仍然看到错误，请参阅问题排查部分，了解如何继续操作。