Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

上传转化数据

本指南详细介绍了如何使用 Campaign Manager 360 API Conversions 服务上传线下转化数据。在继续之前，建议您先查看概览，了解线下转化，并熟悉本指南中讨论的概念。

配置转化资源

转化上传流程的第一步是创建一个或多个 Conversion 资源对象。其中每个对象都代表一个转化事件，并包含一些必填字段：

字段	说明
`floodlightActivityId`	此转化将关联到的 Floodlight 活动。
`floodlightConfigurationId`	指定活动使用的 Floodlight 配置。
`ordinal`	该字段的值用于控制如何对来自同一天中的同一设备或用户的转化数据执行重复数据删除操作。如需了解详情，请参阅常见问题解答。
`timestampMicros`	转化的时间戳，以自 Unix 纪元以来经历的微秒数表示。

此外，每个对象都必须包含以下字段中的一个：

字段	说明
`encryptedUserId`	从 %m 匹配宏或数据传输中获取的单个加密用户 ID。
`encryptedUserIdCandidates[]`	通过 %m 匹配宏或数据传输获取的加密用户 ID 列表。系统会使用这些 ID 中第一个在指定 `timestampMicros` 之前记录了 Floodlight 曝光的 ID。如果所有 ID 均与现有曝光不匹配，系统会抛出错误。
`dclid`	由 Campaign Manager 360 或 Display & Video 360 生成的展示广告点击标识符。
`gclid`	由 Google Ads 或 Search Ads 360 生成的 Google 点击标识符。
`matchId`	通过 Floodlight 代码传递到 Campaign Manager 360 的由广告客户创建的唯一标识符。
`mobileDeviceId`	IDFA 或 AdID 格式的未加密移动设备 ID，或支持的 CTV 设备平台（Roku、Fire TV、Android TV、Apple TV、Xbox、三星、Vizio）所用的联网电视 IFA（广告标识符）。

最后，每次转化都有两个指标：

字段	说明
`quantity`	必需。与转化关联的商品数量。必须至少为 1，转化才能计入某些指标（例如总转化次数）。
`value`	与转化关联的美元金额。以拥有 Floodlight 配置的广告客户币种解读。

参考文档介绍了选填字段。

以下示例展示了如何创建简单的转化资源对象：

C#

// Generate a timestamp in milliseconds since Unix epoch.
TimeSpan timeSpan = DateTime.UtcNow - new DateTime(1970, 1, 1);
long currentTimeInMilliseconds = (long) timeSpan.TotalMilliseconds;

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Create the conversion.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = currentTimeInMilliseconds.ToString();
conversion.TimestampMicros = currentTimeInMilliseconds * 1000;

Java

long currentTimeInMilliseconds = System.currentTimeMillis();

// Find Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity = reporting.floodlightActivities()
    .get(profileId, floodlightActivityId).execute();
long floodlightConfigurationId = floodlightActivity.getFloodlightConfigurationId();

Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(String.valueOf(currentTimeInMilliseconds));
conversion.setTimestampMicros(currentTimeInMilliseconds * 1000);

PHP

$currentTimeInMicros = time() * 1000 * 1000;

// Find Floodlight configuration ID based on provided activity ID.
$activity = $this->service->floodlightActivities->get(
    $values['user_profile_id'],
    $values['floodlight_activity_id']
);
$floodlightConfigId = $activity->getFloodlightConfigurationId();

$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($currentTimeInMicros);
$conversion->setTimestampMicros($currentTimeInMicros);

Python

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = (
    service.floodlightActivities()
    .get(profileId=str(profile_id), id=str(floodlight_activity_id))
    .execute()
)
floodlight_config_id = floodlight_activity['floodlightConfigurationId']

current_time_in_micros = int(time.time() * 1000000)

# Construct the conversion.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': current_time_in_micros,
    'timestampMicros': current_time_in_micros
}

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  floodlight_activity_id)
floodlight_config_id = floodlight_activity.floodlight_configuration_id

current_time_in_micros = DateTime.now.strftime('%Q').to_i * 1000

# Construct the conversion.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: encrypted_user_id,
  floodlight_activity_id: floodlight_activity_id,
  floodlight_configuration_id: floodlight_config_id,
  ordinal: current_time_in_micros,
  timestamp_micros: current_time_in_micros
)

指定加密信息

如果您打算将线下转化归因于加密的用户 ID（如上例所示），则需要在插入请求中提供有关这些 ID 的加密方式的一些详细信息。具体而言，您需要了解：

加密来源，用于描述一批加密 ID 的来源。可接受的值为 AD_SERVING（对于来自 %m 匹配宏的 ID）或 DATA_TRANSFER（对于来自数据传输文件的 ID）。
加密实体，这是一组用于加密用户 ID 的唯一值。当来源为数据传输时，这些值通常与 Campaign Manager 360 账号相关；当来源为 %m 宏时，这些值通常与 Campaign Manager 360 广告客户相关，但情况并非总是如此。如果您不确定，请与您的 Campaign Manager 360 客户代表或 Campaign Manager 360 支持团队联系，了解详情。

必要时，创建指定这些值的 EncryptionInfo 对象是转化上传流程中的第二步：

C#

// Create the encryption info.
EncryptionInfo encryptionInfo = new EncryptionInfo();
encryptionInfo.EncryptionEntityId = encryptionEntityId;
encryptionInfo.EncryptionEntityType = encryptionEntityType;
encryptionInfo.EncryptionSource = encryptionSource;

Java

// Create the encryption info.
EncryptionInfo encryptionInfo = new EncryptionInfo();
encryptionInfo.setEncryptionEntityId(encryptionEntityId);
encryptionInfo.setEncryptionEntityType(encryptionEntityType);
encryptionInfo.setEncryptionSource(encryptionSource);

PHP

$encryptionInfo = new Google_Service_Dfareporting_EncryptionInfo();
$encryptionInfo->setEncryptionEntityId($values['encryption_entity_id']);
$encryptionInfo->setEncryptionEntityType($values['encryption_entity_type']);
$encryptionInfo->setEncryptionSource($values['encryption_source']);

Python

# Construct the encryption info.
encryption_info = {
    'encryptionEntityId': encryption_entity_id,
    'encryptionEntityType': encryption_entity_type,
    'encryptionSource': encryption_source
}

Ruby

# Construct the encryption info.
encryption_info = DfareportingUtils::API_NAMESPACE::EncryptionInfo.new(
  encryption_entity_id: encryption[:entity_id],
  encryption_entity_type: encryption[:entity_type],
  encryption_source: encryption[:source]
)

请注意，每个插入请求只能包含一个 EncryptionInfo 对象。这意味着，给定请求中包含的所有转化都必须来自同一来源，并使用同一加密实体。

生成插入请求

此流程的最后一步是调用 batchinsert 来上传转化数据。此方法接受 ConversionsBatchInsertRequest 对象，该对象将要上传的转化集与其关联的加密信息（必要时）结合在一起：

C#

// Insert the conversion.
ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchInsertResponse response =
    service.Conversions.Batchinsert(request, profileId).Execute();

Java

ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchInsertResponse response = reporting.conversions()
    .batchinsert(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchInsertRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchinsert(
    $values['user_profile_id'],
    $batch
);

Python

# Insert the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchinsert(
    profileId=str(profile_id), body=request_body
)
response = request.execute()

Ruby

# Construct the batch insert request.
batch_insert_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchInsertRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Insert the conversion.
result = service.batchinsert_conversion(profile_id, batch_insert_request)

请注意，Campaign Manager 360 会尽力插入请求中的每次转化，而不是将整个批次作为全有或全无事务进行插入。如果一个批次中的某些转化未能插入，其他转化可能仍会成功插入。因此，建议您检查返回的 ConversionsBatchInsertResponse，以确定每次转化的状态：

C#

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully inserted conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) inserting conversion for encrypted user ID {0}:",
      conversionUserId);

  ConversionStatus status = response.Status[0];
  foreach(ConversionError error in status.Errors) {
    Console.WriteLine("\t[{0}]: {1}", error.Code, error.Message);
  }
}

Java

if (!response.getHasFailures()) {
  System.out.printf("Successfully inserted conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) inserting conversion for encrypted user ID %s:%n",
      encryptedUserId);

  // Retrieve the conversion status and report any errors found. If multiple conversions
  // were included in the original request, the response would contain a status for each.
  ConversionStatus status = response.getStatus().get(0);
  for (ConversionError error : status.getErrors()) {
    System.out.printf("\t[%s]: %s.%n", error.getCode(), error.getMessage());
  }
}

PHP

if (!$result->getHasFailures()) {
    printf(
        'Successfully inserted conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) inserting conversion for encrypted user ID %s:<br><br>',
        $values['encrypted_user_id']
    );

    $status = $result->getStatus()[0];
    foreach ($status->getErrors() as $error) {
        printf('[%s] %s<br>', $error->getCode(), $error->getMessage());
    }
}

Python

if not response['hasFailures']:
  print(
      'Successfully inserted conversion for encrypted user ID %s.'
      % encrypted_user_id
  )
else:
  print(
      'Error(s) inserting conversion for encrypted user ID %s.'
      % encrypted_user_id
  )

  status = response['status'][0]
  for error in status['errors']:
    print('\t[%s]: %s' % (error['code'], error['message']))

Ruby

if result.has_failures
  puts format('Error(s) inserting conversion for encrypted user ID %s.',
    encrypted_user_id)

  status = result.status[0]
  status.errors.each do |error|
    puts format("\t[%s]: %s", error.code, error.message)
  end
else
  puts format('Successfully inserted conversion for encrypted user ID %s.',
    encrypted_user_id)
end

响应的 status 字段将包含原始请求中包含的每个转化的 ConversionStatus 对象。如果您只对未能插入的转化感兴趣，可以使用 hasFailures 字段快速确定所提供批次中的任何转化是否失败。如需了解如何处理每个错误代码以及要重试哪些失败的转化（INTERNAL 和 NOT_FOUND），请参阅常见问题解答。

验证转化数据是否已处理

上传的转化数据通常会在 24 小时内处理完毕并可用于生成报告。如需验证您上传的转化数据是否已处理，建议您生成 Floodlight 展示报告。与其他归因报告不同，这些报告默认会返回已归因（与广告相关联）和未归因的转化。因此，该工具非常适合用于快速检查您发送的转化数据是否已成功传输到 Campaign Manager 360。

上传转化数据 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

配置转化资源

C#

Java

PHP

Python

Ruby

指定加密信息

C#

Java

PHP

Python

Ruby

生成插入请求

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

验证转化数据是否已处理

上传转化数据