本指南将详细说明如何使用 Campaign Manager 360 API Conversions
服务修改转化数据。在继续阅读之前,我们建议您查看概览,简要了解线下转化和熟悉本指南中介绍的概念。
准备工作
通过此修改工作流程,您可以修改现有在线和线下转化的quantity
和value
。为此,您需要提供唯一标识要修改的转化的值。根据您要修改的转化类型,您将以不同的方式获得这些值:
标识在线转化所需的值可从数据传输中获取。
用于标识线下转化所需的值会在成功的
batchinsert
请求的ConversionsBatchInsertResponse
中返回。
在您成功修改任一类型的转化后,ConversionsBatchUpdateResponse
将包含执行后续修改所需的值。
配置转化资源
修改工作流的第一步涉及创建一个或多个 Conversion
资源对象。
以下字段用于标识要修改的转化。这些字段为必填字段,并且必须与现有转化完全一致。
字段 | 说明 |
---|---|
|
生成相应转化事件的经过加密的用户 ID、Google 点击 ID、展示广告点击 ID、匹配 ID 或移动设备 ID。 |
floodlightActivityId |
转化归因于的 Floodlight 活动。 |
floodlightConfigurationId |
指定活动使用的 Floodlight 配置。 |
ordinal |
与转化相关联的重复信息删除标识符。 |
timestampMicros |
转化的时间戳(以与 Unix 计时原点之间相隔的微秒数表示)。 |
下面列出了可修改的字段。这些字段为必填字段,您提供的值将覆盖要修改的转化之前存在的值。
字段 | 说明 |
---|---|
quantity |
与转化相关联的商品数量。 |
value |
转化带来的收入金额。 |
参考文档中提及的所有其他字段均不受支持,且无法修改。在修改请求中添加不受支持的字段会导致错误。如果正在修改的转化包含任何不受支持的字段的现有值,系统将自动保留这些值。
以下示例展示了如何创建要修改的简单转化资源对象:
C#
// Find the Floodlight configuration ID based on the provided activity ID. FloodlightActivity floodlightActivity = service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute(); long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId; // Construct the conversion object with values that identify the conversion to update. Conversion conversion = new Conversion(); conversion.EncryptedUserId = conversionUserId; conversion.FloodlightActivityId = floodlightActivityId; conversion.FloodlightConfigurationId = floodlightConfigurationId; conversion.Ordinal = conversionOrdinal; conversion.TimestampMicros = conversionTimestamp; // Set the fields to be updated. These fields are required; to preserve a value from the // existing conversion, it must be copied over manually. conversion.Quantity = newQuantity; conversion.Value = newValue;
Java
// Create a conversion object populated with values that identify the conversion to update. Conversion conversion = new Conversion(); conversion.setEncryptedUserId(encryptedUserId); conversion.setFloodlightActivityId(floodlightActivityId); conversion.setFloodlightConfigurationId(floodlightConfigurationId); conversion.setOrdinal(ordinal); conversion.setTimestampMicros(timestampMicros); // Set the fields to be updated. These fields are required; to preserve a value from the // existing conversion, it must be copied over manually. conversion.setQuantity(newQuantity); conversion.setValue(newValue);
PHP
// 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(); // Create a conversion object with values that identify the conversion to // update. $conversion = new Google_Service_Dfareporting_Conversion(); $conversion->setEncryptedUserId($values['encrypted_user_id']); $conversion->setFloodlightActivityId($values['floodlight_activity_id']); $conversion->setFloodlightConfigurationId($floodlightConfigId); $conversion->setOrdinal($values['ordinal']); $conversion->setTimestampMicros($values['timestamp']); // Set the fields to be updated. These fields are required; to preserve a // value from the existing conversion, it must be copied over manually. $conversion->setQuantity($values['new_quantity']); $conversion->setValue($values['new_value']);
Python
# Construct the conversion object with values that identify the conversion # to update. conversion = { 'encryptedUserId': encrypted_user_id, 'floodlightActivityId': floodlight_activity_id, 'floodlightConfigurationId': floodlight_config_id, 'ordinal': ordinal, 'timestampMicros': timestamp } # Set the fields to be updated. These fields are required; to preserve a # value from the existing conversion, it must be copied over manually. conversion['quantity'] = new_quantity conversion['value'] = new_value
Ruby
# Look up the Floodlight configuration ID based on activity ID. floodlight_activity = service.get_floodlight_activity(profile_id, existing_conversion[:floodlight_activity_id]) floodlight_config_id = floodlight_activity.floodlight_configuration_id # Construct the conversion with values that identify the conversion to # update. conversion = DfareportingUtils::API_NAMESPACE::Conversion.new( encrypted_user_id: existing_conversion[:encrypted_user_id], floodlight_activity_id: existing_conversion[:floodlight_activity_id], floodlight_configuration_id: floodlight_config_id, ordinal: existing_conversion[:ordinal], timestamp_micros: existing_conversion[:timestamp] ) # Set the fields to be updated. These fields are required; to preserve a # value from the existing conversion, it must be copied over manually. conversion.quantity = new_quantity conversion.value = new_value
指定加密信息
如果要修改的转化与经过加密的用户 ID 相关联,您需要在修改请求中提供与此类用户 ID 相关的加密详情。如需了解详情,请参阅上传转化数据指南。
如有必要,创建指定这些值的 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] )
生成更新请求
该流程的最后一步是通过调用 batchupdate
修改转化事件。此方法会接受 ConversionsBatchUpdateRequest
对象,而该对象会将要修改的一组转化与关联的加密信息组合在一起(如有必要):
C#
// Insert the conversion. ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest(); request.Conversions = new List<Conversion>() { conversion }; request.EncryptionInfo = encryptionInfo; ConversionsBatchUpdateResponse response = service.Conversions.Batchupdate(request, profileId).Execute();
Java
ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest(); request.setConversions(ImmutableList.of(conversion)); request.setEncryptionInfo(encryptionInfo); ConversionsBatchUpdateResponse response = reporting.conversions() .batchupdate(profileId, request).execute();
PHP
$batch = new Google_Service_Dfareporting_ConversionsBatchUpdateRequest(); $batch->setConversions([$conversion]); $batch->setEncryptionInfo($encryptionInfo); $result = $this->service->conversions->batchupdate( $values['user_profile_id'], $batch );
Python
# Update the conversion. request_body = { 'conversions': [conversion], 'encryptionInfo': encryption_info } request = service.conversions().batchupdate( profileId=profile_id, body=request_body) response = request.execute()
Ruby
# Construct the batch update request. batch_update_request = DfareportingUtils::API_NAMESPACE::ConversionsBatchUpdateRequest.new( conversions: [conversion], encryption_info: encryption_info ) # Update the conversion. result = service.batchupdate_conversion(profile_id, batch_update_request)
请注意,Campaign Manager 360 会尽最大努力修改您请求中的每次转化,而不是将整个批次更新为全部更新。如果某个批次中的某些转化未能更新,其他转化可能仍会成功更新。因此,建议您检查返回的 ConversionsBatchUpdateResponse
,以确定每次转化的状态:
C#
// Handle the batchinsert response. if (!response.HasFailures.Value) { Console.WriteLine("Successfully updated conversion for encrypted user ID {0}.", conversionUserId); } else { Console.WriteLine("Error(s) updating 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 updated conversion for encrypted user ID %s.%n", encryptedUserId); } else { System.out.printf("Error(s) updating 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 updated conversion for encrypted user ID %s.', $values['encrypted_user_id'] ); } else { printf( 'Error(s) updating 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 updated conversion for encrypted user ID %s.' % encrypted_user_id) else: print('Error(s) updating 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) updating conversion for encrypted user ID %s.', existing_conversion[: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 updated conversion for encrypted user ID %s.', existing_conversion[:encrypted_user_id]) end
如上所示,对于原始请求中包含的每次转化,响应的 status
字段都包含一个 ConversionStatus
对象。如果您只关心未更新的转化,可使用 hasFailures
字段快速确定所提供的批次中是否有任何转化失败。