Importer des conversions

Ce guide fournit des instructions détaillées pour 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 présentation pour découvrir les conversions hors connexion et vous familiariser avec les concepts abordés dans ce guide.

Remarque : Bien que l'API accepte les conversions hors connexion pour Campaign Manager 360 et Display & Video 360, les données du panier ne sont disponibles pour aucun de ces produits. En savoir plus sur les données du panier

Configurer les ressources de conversion

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

Champ	Description
floodlightActivityId	Activité Floodlight à laquelle cette conversion sera associée.
floodlightConfigurationId	Configuration Floodlight utilisée par l'activité spécifiée.
ordinal	Valeur utilisée pour vérifier la façon dont les conversions provenant du même appareil ou du même utilisateur le même jour sont dédupliquées. Pour en savoir plus, consultez les questions fréquentes.
timestampMicros	Code temporel de la conversion, en microsecondes depuis l'epoch Unix.

En outre, chaque objet doit contenir l'un des champs suivants :

Champ	Description
encryptedUserId	ID utilisateur unique chiffré obtenu à partir de la macro de correspondance %m ou du transfert de données.
encryptedUserIdCandidates[]	Liste des ID utilisateur chiffrés obtenus à partir de la macro de correspondance %m ou du transfert de données. Le premier de ces ID ayant enregistré une exposition Floodlight 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	Identifiant unique créé par l'annonceur et transmis à Campaign Manager 360 par le biais d'une balise Floodlight.
mobileDeviceId	ID mobile non chiffré au format IDFA ou AdID, ou identifiant publicitaire pour TV connectée issu d'une plate-forme d'appareils pour la TV connectée compatible (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Notez que Google ne prend pas en charge les identifiants publicitaires YouTube pour la TV connectée.

Enfin, chaque conversion comporte deux métriques :

Champ	Description
quantity	Obligatoire. Nombre d'articles associés à la conversion. Doit être au moins égal à 1 pour que la conversion soit comptabilisée dans certaines métriques (comme "Conversions totales").
value	Montant en dollars associé à la conversion. Interprétée dans la devise de l'annonceur propriétaire de la configuration Floodlight.

Les champs facultatifs sont décrits dans la documentation de référence.

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 qu'à l'importation de conversions contenant un encryptedUserId ou un encryptedUserIdCandidates[].

Si vous prévoyez d'attribuer des conversions hors connexion à des ID utilisateur chiffrés, comme dans l'exemple précédent, vous devrez fournir des informations sur la façon dont ils sont chiffrés dans votre requête d'insertion. Vous devez notamment savoir :

1. La source de chiffrement, qui décrit d'où provient un lot d'ID chiffrés. Les valeurs acceptées sont AD_SERVING pour les ID provenant de la macro %m match 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 utilisées pour chiffrer les ID utilisateur. Ces valeurs sont généralement 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. Si vous n'êtes pas sûr, contactez votre représentant 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]
)

Sachez 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 demande d'insertion

La dernière étape de ce processus consiste à importer vos conversions en appelant batchinsert. Cette méthode accepte un objet ConversionsBatchInsertRequest, qui combine l'ensemble des conversions à importer avec les informations de chiffrement associées (le cas échéant) :

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)

Sachez que Campaign Manager 360 tente d'insérer chaque conversion de votre demande de la manière la plus précise possible, plutôt que d'insérer l'ensemble du lot comme une transaction tout ou rien. Si l'insertion de certaines conversions d'un lot échoue, d'autres peuvent quand même être insérées. 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 qui n'ont pas pu être insérées, 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 d'exécuter un rapport sur les impressions Floodlight. Contrairement aux autres rapports sur l'attribution, ceux-ci renverront par défaut les conversions attribuées (associées à une annonce) et non attribuées. Il est donc idéal pour vérifier rapidement si les conversions que vous avez envoyées ont bien été enregistrées dans Campaign Manager 360.

Remarque : Les tests de validation doivent être effectués à l'aide de conversions récentes. Les rapports sur les impressions Floodlight n'incluent pas les conversions envoyées plus de 28 jours après leur code temporel.