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 soit compatible avec les conversions hors connexion pour Campaign Manager 360 et Display & Video 360, les données relatives au panier ne sont disponibles pour aucun de ces produits. En savoir plus sur les données relatives au panier.

Configurer les ressources de conversion

La première étape du processus d'importation des conversions consiste à créer un ou plusieurs Conversion objets de ressource. 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.

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

Champ	Description
encryptedUserId	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 obtenus à partir de la macro de correspondance %m ou du transfert de données. Le premier de ces ID avec une exposition Floodlight enregistrée avant le timestampMicros spécifié sera utilisé. Si aucun des ID ne correspond à une exposition existante, une erreur sera générée.
dclid	Un identifiant de clic 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 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 d'au moins 1 pour que la conversion soit prise en compte dans certaines métriques (comme le nombre total de conversions).
value	Montant en dollars associé à la conversion. Interprété 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=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
)

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 devrez notamment connaître les éléments suivants :

1. La source de chiffrement, qui décrit l'origine d'un lot d'ID chiffrés. Les valeurs acceptables sont AD_SERVING pour les ID provenant de la macro de correspondance %m, ou DATA_TRANSFER pour les ID provenant de 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 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. 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 EncryptionInfo objet 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 EncryptionInfo objet. 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 en appelant batchinsert. Cette méthode accepte un ConversionsBatchInsertRequest objet, qui combine l'ensemble des 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=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)

Sachez que Campaign Manager 360 tente d'insérer chaque conversion de votre requête au mieux de ses capacités, plutôt que d'insérer l'ensemble du lot comme une transaction tout ou rien. Si certaines conversions d'un lot ne sont pas insérées, d'autres peuvent l'être. Par conséquent, nous vous recommandons d'inspecter le renvoyé ConversionsBatchInsertResponsepour 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

Le champ status de la réponse, comme indiqué ci-dessus, contient un ConversionStatus objet pour chaque conversion incluse dans la requête d'origine. Si vous ne vous intéressez qu'aux conversions qui n'ont pas été 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 d'attribution, ceux-ci renvoient par défaut les conversions attribuées (associées à une annonce) et non attribuées. Ils sont donc idéaux pour vérifier rapidement si les conversions que vous avez envoyées ont bien été transmises à 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.