Importer des conversions

Ce guide explique comment importer des conversions hors connexion à l'aide du service Conversions de l'API Campaign Manager 360. Avant de continuer, nous vous recommandons de consulter la section Présentation des conversions hors connexion et de vous familiariser avec les concepts abordés dans ce guide.

Configurer les ressources de conversion

La première étape du processus d'importation des conversions consiste à créer un ou plusieurs objets Conversion. Chacun de ces objets représente un seul événement de conversion et contient quelques champs obligatoires:

Champ	Description
floodlightActivityId	Activité Floodlight à laquelle cette conversion est associée.
floodlightConfigurationId	Configuration Floodlight utilisée par l'activité spécifiée.
ordinal	Valeur permettant de contrôler la façon dont les conversions en double issues d'un même appareil ou utilisateur le même jour sont dédupliquées. Pour en savoir plus, consultez les questions fréquentes.
timestampMicros	Horodatage de la conversion en microsecondes depuis l'epoch Unix.

De plus, chaque objet doit contenir un des champs suivants:

Champ	Description
encryptedUserId	Un ID utilisateur chiffré unique obtenu à partir de la macro de correspondance%m ou du transfert de données.
encryptedUserIdCandidates[]	Liste d'ID utilisateur chiffrés obtenu grâce à la macro de correspondance%m ou au transfert de données. Le premier ID associé à une exposition Floodlight enregistrée avant le timestampMicros spécifié sera utilisé. Si aucun des ID ne correspond à une exposition existante, une erreur est générée.
dclid	Identifiant de clic Display généré par Campaign Manager 360 ou Display & Video 360.
gclid	Identifiant de clic Google généré par Google Ads ou Search Ads 360.
matchId	Un identifiant unique créé par l'annonceur, transmis à Campaign Manager 360 via une balise Floodlight
mobileDeviceId	ID mobile non chiffré au format IDFA ou AdID, ou identifiant de télévision connectée (IFA) sur une plate-forme compatible (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Notez que Google n'est pas compatible avec les IFA de la TV connectée YouTube.

Les champs facultatifs sont présentés dans la documentation de référence. Bien que le champ "quantity" soit facultatif, il doit être au moins égal à 1 pour que la conversion soit comptabilisée dans certaines métriques (telles que le nombre total de conversions) lors de l'exécution des rapports.

L'exemple ci-dessous illustre la création d'un objet de ressource de conversion 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=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
)

Spécifier les informations de chiffrement

Remarque :Cette section ne s'applique que lorsque vous importez des conversions contenant un élément encryptedUserId ou encryptedUserIdCandidates[].

Si vous prévoyez d'attribuer des conversions hors connexion à des ID utilisateur chiffrés, comme dans l'exemple précédent, vous devez fournir des informations sur le chiffrement de vos requêtes d'insertion. Vous devez notamment savoir:

1. La source de chiffrement, qui décrit l'origine d'un lot d'ID chiffrés. Les valeurs acceptées sont AD_SERVING pour les ID provenant de la macro de correspondance %m ou DATA_TRANSFER pour les ID provenant des fichiers de transfert de données.

2. L'entité de chiffrement, qui est un ensemble unique de valeurs permettant de chiffrer les ID utilisateur. Ces valeurs sont normalement liées à un compte Campaign Manager 360 lorsque la source est le transfert de données ou à un annonceur Campaign Manager 360 lorsque la source est la macro %m, mais ce n'est pas toujours le cas. En cas de doute, contactez votre responsable de compte Campaign Manager 360 ou l'assistance Campaign Manager 360 pour en savoir plus.

Si nécessaire, la deuxième étape du processus d'importation des conversions consiste à créer un objet EncryptionInfo qui spécifie ces valeurs:

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

Notez que chaque requête d'insertion ne peut contenir qu'un seul objet EncryptionInfo. Cela signifie que toutes les conversions incluses dans une requête donnée doivent provenir de la même source et utiliser la même entité de chiffrement.

Générer une requête d'insertion

La dernière étape de ce processus consiste à importer vos conversions avec un appel à batchinsert. Cette méthode accepte un objet ConversionsBatchInsertRequest, qui combine l'ensemble de conversions à importer avec les informations de chiffrement associées (si nécessaire):

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)

Notez que Campaign Manager 360 tente d'insérer chaque conversion dans votre requête de la façon la plus optimale possible, plutôt que d'insérer le lot entier en tant que transaction "tout ou rien". Si l'insertion de certaines conversions d'un lot échoue, d'autres peuvent encore être insérées correctement. Par conséquent, nous vous recommandons d'inspecter le ConversionsBatchInsertResponse renvoyé pour déterminer l'état de chaque conversion:

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

Comme indiqué ci-dessus, le champ status de la réponse contient un objet ConversionStatus pour chaque conversion incluse dans la requête d'origine. Si vous ne vous intéressez qu'aux conversions dont l'insertion a échoué, le champ hasFailures peut être utilisé pour déterminer rapidement si une conversion du lot fourni a échoué.

Vérifier que les conversions ont été traitées

Les conversions importées sont généralement traitées et disponibles dans les rapports sous 24 heures. Pour vérifier si les conversions que vous avez importées ont été traitées, nous vous recommandons de générer un rapport Impressions Floodlight. Contrairement aux autres rapports sur l'attribution, ils renvoient par défaut les conversions attribuées (associées à une annonce) et les conversions non attribuées. Cela vous permet de vérifier rapidement si les conversions que vous avez envoyées sont bien parvenues à Campaign Manager 360.

Remarque :Les tests de validation doivent être effectués sur des conversions récentes. Les rapports sur les impressions Floodlight ne reflètent pas les conversions envoyées plus de 28 jours après leur horodatage.