Carga de conversiones

En esta guía, se proporcionan instrucciones detalladas para subir conversiones sin conexión con el servicio Conversions de la API de Campaign Manager 360. Antes de continuar, te recomendamos que revises la Descripción general para obtener una introducción a las conversiones sin conexión y familiarizarte con los conceptos que se analizan en esta guía.

Nota: Si bien la API admite las conversiones sin conexión para Campaign Manager 360 y Display & Video 360, los datos del carrito no están disponibles para ninguno de esos productos. Obtén más información sobre los datos del carrito.

Configura los recursos de conversión

El primer paso del proceso de carga de conversiones es crear uno o más objetos de recursos Conversion. Cada uno de estos objetos representa un solo evento de conversión y contiene algunos campos obligatorios:

Campo	Descripción
floodlightActivityId	Es la actividad de Floodlight con la que se asociará esta conversión.
floodlightConfigurationId	Es la configuración de Floodlight que usa la actividad especificada.
ordinal	Es un valor que se usa para controlar cómo se anulan las conversiones duplicadas del mismo dispositivo o usuario en el mismo día. Consulta las Preguntas frecuentes para obtener más información.
timestampMicros	Es la marca de tiempo de la conversión, en microsegundos desde la época de Unix.

Además, cada objeto debe contener uno de los siguientes campos:

Campo	Descripción
encryptedUserId	Es un solo ID de usuario encriptado que se obtiene de la macro de coincidencia%m o de la Transferencia de datos.
encryptedUserIdCandidates[]	Es una lista de IDs de usuario encriptados que se obtienen de la macro de coincidencia%m o de la Transferencia de datos. Se usará el primero de estos IDs con una exposición a Floodlight registrada antes del timestampMicros especificado. Si ninguno de los IDs coincide con una exposición existente, se generará un error.
dclid	Es un identificador de clics de Display generado por Campaign Manager 360 o Display & Video 360.
gclid	Un Identificador de clics de Google generado por Google Ads o Search Ads 360.
matchId	Es un identificador único creado por el anunciante que se pasa a Campaign Manager 360 por medio de una etiqueta de Floodlight.
mobileDeviceId	Es un documento de identidad digital no encriptado en formato IDFA o AdID, o un identificador de TV conectada para publicidad (IFA) de una plataforma de dispositivo de CTV admitido (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Ten en cuenta que Google no admite los IFA de TV conectada de YouTube.

Por último, cada conversión tiene dos métricas:

Campo	Descripción
quantity	Obligatorio. Es la cantidad de artículos asociados con la conversión. Debe ser, al menos, 1 para que la conversión se contabilice en ciertas métricas (como las conversiones totales).
value	Es el importe en dólares asociado con la conversión. Se interpreta en la moneda del anunciante propietario de la configuración de Floodlight.

Los campos opcionales se documentan en la documentación de referencia.

En el siguiente ejemplo, se ilustra la creación de un objeto de recurso de conversión simple:

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
)

Especifica la información de encriptación

Nota: Esta sección solo se aplica cuando se suben conversiones que contienen un encryptedUserId o un encryptedUserIdCandidates[].

Si planeas atribuir conversiones sin conexión a IDs de usuario encriptados, como en el ejemplo anterior, deberás proporcionar algunos detalles sobre cómo se encriptan como parte de tu solicitud de inserción. En particular, deberás saber lo siguiente:

1. La fuente de encriptación, que describe de dónde provino un lote de IDs encriptados. Los valores aceptables son AD_SERVING para los IDs obtenidos de la macro de coincidencia %m o DATA_TRANSFER para los IDs obtenidos de los archivos de Transferencia de datos.

2. La entidad de encriptación, que es un conjunto único de valores que se usa para encriptar los IDs de usuario. Estos valores suelen relacionarse con una cuenta de Campaign Manager 360 cuando la fuente es Transferencia de datos, o con un anunciante de Campaign Manager 360 cuando la fuente es la macro %m, pero no siempre es así. Si no tienes certeza, comunícate con tu representante de cuenta de Campaign Manager 360 o con el equipo de asistencia de Campaign Manager 360 para obtener más información.

Cuando sea necesario, crear un objeto EncryptionInfo que especifique estos valores es el segundo paso del proceso de carga de conversiones:

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

Ten en cuenta que cada solicitud de inserción solo puede contener un objeto EncryptionInfo. Esto significa que todas las conversiones incluidas en una solicitud determinada deben provenir de la misma fuente y usar la misma entidad de encriptación.

Genera una solicitud de inserción

El último paso de este proceso es subir tus conversiones con una llamada a batchinsert. Este método acepta un objeto ConversionsBatchInsertRequest, que combina el conjunto de conversiones que se subirán con su información de encriptación asociada (cuando sea necesario):

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)

Ten en cuenta que Campaign Manager 360 intenta insertar cada conversión en tu solicitud de la mejor manera posible, en lugar de insertar todo el lote como una transacción de todo o nada. Si no se pueden insertar algunas conversiones en un lote, es posible que otras se inserten correctamente. Por lo tanto, se recomienda que inspecciones el ConversionsBatchInsertResponse devuelto para determinar el estado de cada conversión:

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

El campo status de la respuesta, como se ve arriba, contendrá un objeto ConversionStatus para cada conversión incluida en la solicitud original. Si solo te interesan las conversiones que no se pudieron insertar, puedes usar el campo hasFailures para determinar rápidamente si falló alguna conversión en el lote proporcionado.

Verifica que se hayan procesado las conversiones

En general, las conversiones subidas se procesan y están disponibles para los informes en un plazo de 24 horas. Para verificar si se procesaron las conversiones que subiste, te recomendamos que ejecutes un informe de Impresiones de Floodlight. A diferencia de otros informes de atribución, estos mostrarán de forma predeterminada las conversiones atribuidas (asociadas a un anuncio) y las no atribuidas. Esto la hace ideal para verificar rápidamente si las conversiones que enviaste llegaron a Campaign Manager 360.

Nota: Las pruebas de verificación se deben realizar con conversiones recientes. Los informes de Impresiones de Floodlight no reflejarán las conversiones enviadas más de 28 días después de su marca de tiempo.