Importer des conversions

Ce guide fournit des instructions détaillées sur l'importation 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 prenne en charge 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 de la conversion consiste à créer un ou plusieurs objets de ressources 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 sera associée.
floodlightConfigurationId	Configuration Floodlight utilisée par l'activité spécifiée.
ordinal	Valeur utilisée pour contrôler la façon dont les conversions provenant du même appareil ou de l'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.

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

Champ	Description
encryptedUserId	Un seul ID utilisateur chiffré obtenu à partir de la macro de correspondance%m ou de Transfert de données.
encryptedUserIdCandidates[]	Liste d'ID utilisateur chiffrés obtenus à partir de la macro de correspondance%m ou de Transfert de données. Le premier de ces ID avec une exposition Floodlight enregistrée avant la timestampMicros spécifiée sera utilisé. Si aucun des ID ne correspond à une exposition existante, une erreur est générée.
dclid	Identifiant de clic sur une annonce display généré par Campaign Manager 360 ou Display & Video 360.
gclid	Un 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 via un tag Floodlight.
mobileDeviceId	Un ID mobile non chiffré au format IDFA ou AdID, ou un identifiant publicitaire pour la TV connectée (IFA) provenant d'une plate-forme d'appareils TV connectés compatible (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung ou Vizio). Notez que Google n'est pas compatible avec les IFA YouTube pour la télévision connectée.

Les champs facultatifs sont décrits dans la documentation de référence. Notez que le champ "Quantité", bien qu'il soit facultatif, doit être d'au moins 1 pour que la conversion soit comptabilisée dans certaines métriques (telles que le nombre total de conversions) lorsque vous exécutez 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 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 issus de la macro de correspondance %m ou DATA_TRANSFER pour les ID issus de fichiers de transfert de données.

2. L'entité de chiffrement, qui est un ensemble unique de valeurs utilisé pour chiffrer les ID utilisateur. Ces valeurs font normalement référence à un compte Campaign Manager 360 lorsque la source est "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 le représentant de votre 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 à l'aide d'un appel à 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 dans votre requête de la manière la plus précise possible, plutôt que d'insérer l'ensemble du lot en tant que transaction tout ou rien. Si l'insertion de certaines conversions d'un lot échoue, d'autres peuvent toujours être insérées. Par conséquent, nous vous recommandons d'inspecter l'ConversionsBatchInsertResponse renvoyée 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 pour 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 renvoient à la fois des conversions attribuées (associées à une annonce) et des conversions non attribuées par défaut. Il est donc idéal pour vérifier rapidement si les conversions que vous avez envoyées ont bien été reçues par Campaign Manager 360.

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