Este guia contém instruções detalhadas para editar conversões usando o serviço Conversions
da API Campaign Manager 360. Antes de continuar, consulte a Visão geral para ver uma introdução às conversões off-line e se familiarizar com os conceitos discutidos neste guia.
Antes de começar
Esse fluxo de trabalho de edição permite modificar os quantity
e value
das conversões on-line e off-line existentes. Para isso, você precisará fornecer valores que identifiquem de forma exclusiva as conversões a serem editadas. Dependendo do tipo de conversão que você estiver editando, esses valores serão recebidos de maneiras diferentes:
Veja os valores necessários para identificar conversões on-line na Transferência de dados.
Os valores necessários para identificar conversões off-line são retornados no
ConversionsBatchInsertResponse
de solicitaçõesbatchinsert
bem-sucedidas.
Depois que você editar uma conversão de qualquer tipo, o ConversionsBatchUpdateResponse
conterá os valores necessários para fazer as edições seguintes.
Configurar recursos de conversão
A primeira etapa no fluxo de trabalho de edição envolve a criação de um ou mais objetos de recurso Conversion
.
Os campos a seguir são usados para identificar uma conversão a ser editada. Esses campos são obrigatórios e precisam corresponder exatamente a uma conversão existente.
Campo | Descrição |
---|---|
|
O ID do usuário criptografado, o ID de clique do Google, o ID de clique da Rede de Display, o ID de correspondência ou o ID do dispositivo móvel que gerou a conversão. |
floodlightActivityId |
A atividade do Floodlight à qual a conversão é atribuída. |
floodlightConfigurationId |
A configuração do Floodlight usada pela atividade especificada. |
ordinal |
O identificador da eliminação de duplicação associado à conversão. |
timestampMicros |
O carimbo de data/hora da conversão, em microssegundos, a partir do Unix epoch. |
Os campos que podem ser editados estão listados abaixo. Esses campos são obrigatórios, e os valores fornecidos substituirão os valores preexistentes na conversão que está sendo editada.
Campo | Descrição |
---|---|
quantity |
Número de itens associados à conversão. |
value |
O valor da receita gerada pela conversão. |
Todos os outros campos mencionados na documentação de referência não são compatíveis nem podem ser modificados. A inclusão de campos incompatíveis na sua solicitação de edição resultará em um erro. Se a conversão editada tiver valores pré-existentes para os campos não compatíveis, eles serão preservados automaticamente.
O exemplo abaixo ilustra a criação de um objeto de recurso de conversão simples para editar:
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
Especificar informações de criptografia
Se as conversões que estão sendo editadas estiverem associadas a códigos de usuário criptografados, você precisará fornecer detalhes sobre como elas são criptografadas como parte da solicitação de edição. Consulte o guia Como fazer o upload de conversões para detalhes.
Quando necessário, a segunda etapa no fluxo de trabalho de edição é criar um objeto EncryptionInfo
que especifique esses valores:
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] )
Gerar uma solicitação de atualização
A etapa final do processo é editar as conversões com uma chamada para batchupdate
. Esse método aceita um objeto ConversionsBatchUpdateRequest
, que combina o conjunto de conversões a ser editado com as informações de criptografia associadas (quando necessário):
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)
O Campaign Manager 360 tenta editar cada conversão da solicitação da melhor forma possível, em vez de atualizar todo o lote como uma transação "tudo ou nada". Se algumas conversões em um lote não forem atualizadas, outras ainda poderão ser atualizadas. Portanto, é recomendável inspecionar o ConversionsBatchUpdateResponse
retornado para determinar o status de cada conversão:
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
O campo status
da resposta, como visto acima, conterá um objeto ConversionStatus
para cada conversão incluída na solicitação original. Se você só tiver interesse nas conversões que não foram atualizadas, use o campo hasFailures
para determinar rapidamente se alguma conversão do lote fornecido teve falha.