Esta página foi traduzida pela API Cloud Translation.

Editar conversões

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 saber mais sobre as conversões off-line e os conceitos discutidos neste guia.

Antes de começar

Com esse fluxo de trabalho de edição, é possível modificar os valores de quantity e value das conversões on-line e off-line existentes. Para fazer isso, será preciso adicionar valores que identifiquem de maneira exclusiva as conversões que serão editadas. Dependendo do tipo dessas conversões, há maneiras diferentes de encontrar esses valores:

Os valores necessários para identificar conversões on-line podem ser obtidos na Transferência de dados.
Os valores necessários para identificar conversões off-line são retornados no ConversionsBatchInsertResponse das solicitações batchinsert bem-sucedidas.

Depois que você editar uma conversão de qualquer tipo, o ConversionsBatchUpdateResponse vai conter os valores necessários para fazer as edições seguintes.

Configurar recursos de conversão

A primeira etapa do fluxo de trabalho de edição envolve a criação de um ou mais objetos de recurso Conversion.

Os seguintes campos são usados para identificar uma conversão que será editada. Esses campos são obrigatórios e precisam corresponder exatamente a conversões existentes.

Campo	Descrição
`encryptedUserId`, `gclid`, `dclid`, `matchid` ou `mobileDeviceId`	É o ID do usuário criptografado, o ID de clique do Google, o ID de clique do Display, o ID de correspondência ou o ID do dispositivo móvel de origem da conversão. O campo `encryptedUserIdCandidates` não pode ser usado para edições.
`floodlightActivityId`	A atividade do Floodlight com a conversão atribuída.
`floodlightConfigurationId`	Mostra 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 desde a Era Unix.

Os campos que podem ser editados estão listados abaixo.

Esses campos são obrigatórios, e os valores fornecidos vão substituir os valores preexistentes na conversão editada.

Campo	Descrição
`quantity`	É o número de itens associados à conversão.
`value`	O valor da receita gerada pela conversão.

Estes campos são opcionais. O valor não será alterado se não for definido.

Campo	Descrição
`customVariables`	As variáveis personalizadas do Floodlight da conversão. Atualiza ou insere o valor se a variável estiver definida. O valor da variável não será alterado se não for definido.

Todos os outros campos mencionados na documentação de referência não são compatíveis nem podem ser modificados. Incluir campos incompatíveis na solicitação de edição causará um erro. Se a conversão a ser editada tiver valores preexistentes em campos incompatíveis, esses valores serão automaticamente mantidos.

O exemplo abaixo ilustra a criação de um objeto de recurso de conversão simples para edição:

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 editadas estiverem associadas a IDs de usuário criptografados, será preciso incluir detalhes sobre essa criptografia na solicitação de edição. Consulte o guia Como fazer upload de conversões para mais detalhes.

Quando necessário, a segunda etapa no fluxo de trabalho de edição é criar um objeto EncryptionInfo para especificar 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 une o conjunto de conversões que serão editadas às 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 de um lote não forem atualizadas, talvez outras recebam a atualização. 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, terá 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.