Fazer o upload das conversões

Este guia contém instruções detalhadas para upload de conversões off-line 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.

Configurar recursos de conversão

A primeira etapa no processo de upload de conversões é criar um ou mais objetos de recurso Conversion. Cada um desses objetos representa um único evento de conversão e contém alguns campos obrigatórios:

Campo	Descrição
floodlightActivityId	A atividade do Floodlight a que esta conversão será associada.
floodlightConfigurationId	A configuração do Floodlight usada pela atividade especificada.
ordinal	Um valor usado para controlar como a duplicação das conversões do mesmo dispositivo ou usuário no mesmo dia é eliminada. Consulte as Perguntas frequentes para mais informações.
timestampMicros	O carimbo de data/hora da conversão, em microssegundos, a partir do Unix epoch.

Além disso, cada objeto precisa conter um dos seguintes campos:

Campo	Descrição
encryptedUserId	Um único ID do usuário criptografado, extraído da macro de correspondência%m ou da Transferência de dados.
encryptedUserIdCandidates[]	Uma lista de IDs de usuário criptografados, extraída da macro de correspondência%m ou da Transferência de dados. O primeiro desses IDs com uma exposição do Floodlight registrada antes da timestampMicros especificada será usado. Se nenhum dos IDs corresponder a uma exposição existente, será gerado um erro.
dclid	É um identificador de clique de display gerado pelo Campaign Manager 360 ou pelo Display & Video 360.
gclid	É um identificador de clique do Google gerado pelo Google Ads ou pelo Search Ads 360.
matchId	É um identificador exclusivo criado pelo anunciante e transmitido para o Campaign Manager 360 usando uma tag do Floodlight.
mobileDeviceId	Um ID de dispositivo móvel não criptografado no formato IDFA ou AdID ou um IFA (Identificador de publicidade conectado) de uma plataforma de dispositivo de smart TV compatível (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). O Google não é compatível com IFAs de smart TV do YouTube.

Os campos opcionais estão descritos na documentação de referência. O campo de quantidade, embora opcional, precisa ser pelo menos 1 para que a conversão seja contabilizada em determinadas métricas (como "Total de conversões") ao gerar relatórios.

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

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=profile_id, id=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
)

Especificar informações de criptografia

Observação: esta seção só se aplica ao upload de conversões que contenham um encryptedUserId ou encryptedUserIdCandidates[].

Se você planeja atribuir conversões off-line a códigos de usuário criptografados, como no exemplo anterior, será necessário fornecer alguns detalhes sobre como eles são criptografados como parte da solicitação de inserção. Você precisará saber:

1. A fonte de criptografia, que descreve a origem de um lote de códigos criptografados. Os valores aceitáveis são AD_SERVING para códigos da macro de correspondência %m ou DATA_TRANSFER para códigos de arquivos da Transferência de dados.

2. A entidade de criptografia, que é um conjunto exclusivo de valores usado para criptografar códigos de usuário. Esses valores normalmente estão relacionados a uma conta do Campaign Manager 360, quando a origem é a Transferência de dados, ou a um anunciante do Campaign Manager 360, quando a fonte é a macro %m, mas esse nem sempre é o caso. Se não tiver certeza, entre em contato com o representante da conta do Campaign Manager 360 ou com o suporte do Campaign Manager 360 para mais informações.

Quando necessário, criar um objeto EncryptionInfo que especifica esses valores é a segunda etapa no processo de upload de conversões:

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]
)

Cada solicitação de inserção pode conter apenas um objeto EncryptionInfo. Isso significa que todas as conversões incluídas em uma determinada solicitação precisam ser provenientes da mesma origem e usar a mesma entidade de criptografia.

Gerar uma solicitação de inserção

A etapa final do processo é fazer upload das conversões com uma chamada para batchinsert. Esse método aceita um objeto ConversionsBatchInsertRequest, que combina o conjunto de conversões a serem enviadas com as informações de criptografia associadas (quando necessário):

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=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)

O Campaign Manager 360 tenta inserir cada conversão na solicitação da melhor forma possível, em vez de inserir todo o lote como uma transação "tudo ou nada". Se algumas conversões em um lote não forem inseridas, outras ainda poderão ser inseridas. Portanto, é recomendável inspecionar o ConversionsBatchInsertResponse retornado para determinar o status de cada conversão:

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

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 inseridas, use o campo hasFailures para determinar rapidamente se alguma conversão do lote fornecido teve falha.

Verificar se as conversões foram processadas

As conversões enviadas geralmente serão processadas e estarão disponíveis para relatórios em até 24 horas. Para verificar se as conversões enviadas foram processadas, é recomendável gerar um relatório Impressões do Floodlight. Ao contrário de outros relatórios de atribuição, eles retornam conversões atribuídas (associadas a um anúncio) e não atribuídas por padrão. Por isso, esse tipo é ideal para verificar rapidamente se as conversões enviadas chegaram ao Campaign Manager 360.

Observação: os testes de verificação precisam ser realizados usando conversões recentes. Os relatórios de impressões do Floodlight não refletirão as conversões enviadas mais de 28 dias após o carimbo de data/hora.