Fazer o upload das conversões

Importante: faça upgrade dos seus fluxos de trabalho de conversões off-line para a API Data Manager e tenha uma experiência de desenvolvedor melhor e acesso a mais recursos. Não recomendamos implementar novos fluxos de trabalho de conversão off-line usando a API Campaign Manager 360.

Este guia contém instruções detalhadas para fazer 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 saber mais sobre as conversões off-line e os conceitos analisados neste guia.

Observação: embora a API seja compatível com conversões off-line para o Campaign Manager 360 e o Display & Video 360, os dados do carrinho não estão disponíveis para nenhum desses produtos. Saiba mais sobre os dados do carrinho.

Configurar recursos de conversão

A primeira etapa do 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 que será associada a essa conversão.
floodlightConfigurationId	Mostra a configuração do Floodlight usada pela atividade especificada.
ordinal	Contém um valor usado para controlar como eliminar a duplicação de conversões do mesmo dispositivo ou usuário no mesmo dia. Consulte as perguntas frequentes para mais informações.
timestampMicros	É o carimbo de data/hora da conversão em microssegundos desde a época Unix.

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

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

Por fim, cada conversão tem duas métricas:

Campo	Descrição
quantity	Obrigatório. É o número de itens associados à conversão. Precisa ser pelo menos 1 para que a conversão seja contabilizada em determinadas métricas (como total de conversões).
value	O valor monetário associado à conversão. Interpretado na moeda do anunciante proprietário da configuração do Floodlight.

Os campos opcionais são descritos na documentação de referência.

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

Especificar informações de criptografia

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

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

1. A origem da criptografia, que descreve de onde veio um lote de IDs criptografados. Os valores aceitáveis são AD_SERVING para IDs provenientes da macro de correspondência %m ou DATA_TRANSFER para IDs provenientes de arquivos da Transferência de dados.

2. A entidade de criptografia, que é um conjunto exclusivo de valores usados para criptografar IDs de usuário. Esses valores normalmente se relacionam 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 origem é a macro %m, mas nem sempre é esse o caso. Se você não tiver certeza, entre em contato com o representante da sua conta do Campaign Manager 360 ou com o suporte do Campaign Manager 360 para mais informações.

Quando necessário, a segunda etapa no processo de upload de conversões é 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]
)

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 ter a mesma origem e usar a mesma entidade de criptografia.

Gerar uma solicitação de inserção

A etapa final do processo é fazer o upload das conversões com uma chamada para batchinsert. Esse método aceita um objeto ConversionsBatchInsertRequest, que une o conjunto de conversões que serão enviadas às 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=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)

O Campaign Manager 360 tenta inserir cada conversão da 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 de um lote não forem inseridas, talvez outras sejam. 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 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 inseridas, use o campo hasFailures para determinar rapidamente se alguma conversão do lote fornecido teve falha. Para orientações sobre como lidar com cada código do erro e quais conversões com falha tentar novamente (INTERNAL e NOT_FOUND), consulte as Perguntas frequentes.

Verificar se as conversões foram processadas

As conversões enviadas geralmente são processadas e disponibilizadas para relatórios em até 24 horas. Para verificar se as conversões que você enviou foram processadas, recomendamos gerar um relatório de 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. Isso o torna ideal para verificar rapidamente se as conversões enviadas chegaram ao Campaign Manager 360.

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