Cette page a été traduite par l'API Cloud Translation.

Modifier les conversions

Ce guide fournit des instructions détaillées sur la modification des conversions à 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.

Avant de commencer

Ce workflow de modification vous permet de modifier les quantity et value des conversions en ligne et hors connexion existantes. Pour ce faire, vous devez fournir des valeurs qui identifient de manière unique les conversions à modifier. Selon le type de conversions que vous modifiez, vous obtiendrez ces valeurs de différentes manières:

Les valeurs nécessaires pour identifier les conversions en ligne peuvent être obtenues dans Transfert de données.
Les valeurs nécessaires pour identifier les conversions hors connexion sont renvoyées dans le ConversionsBatchInsertResponse des requêtes batchinsert réussies.

Une fois que vous avez modifié une conversion de l'un ou l'autre type, ConversionsBatchUpdateResponse contient les valeurs nécessaires pour effectuer les modifications ultérieures.

Configurer les ressources de conversion

La première étape du workflow de modification consiste à créer un ou plusieurs objets de ressources Conversion.

Les champs suivants permettent d'identifier une conversion à modifier. Ces champs sont obligatoires et doivent correspondre exactement à une conversion existante.

Champ	Description
`encryptedUserId`, `gclid`, `dclid`, `matchid` ou `mobileDeviceId`	ID utilisateur chiffré, ID de clic Google, ID de clic Display, ID de correspondance ou ID d'appareil mobile ayant généré la conversion. Le champ `encryptedUserIdCandidates` ne peut pas être utilisé pour les modifications.
`floodlightActivityId`	Activité Floodlight à laquelle la conversion est attribuée.
`floodlightConfigurationId`	Configuration Floodlight utilisée par l'activité spécifiée.
`ordinal`	Identifiant de déduplication associé à la conversion.
`timestampMicros`	Code temporel de la conversion, en microsecondes depuis l'epoch Unix.

Les champs modifiables sont listés ci-dessous.

Ces champs sont obligatoires, et les valeurs que vous fournissez remplacent toutes les valeurs préexistantes de la conversion en cours de modification.

Champ	Description
`quantity`	Nombre d'articles associés à la conversion.
`value`	Montant des revenus générés par la conversion.

Ces champs sont facultatifs. Si elle n'est pas définie, la valeur ne change pas.

Champ	Description
`customVariables`	Les variables Floodlight personnalisées de la conversion. Met à jour ou insère la valeur si la variable est définie. Si elle n'est pas définie, la valeur de la variable ne change pas.

Tous les autres champs mentionnés dans la documentation de référence ne sont pas compatibles et ne peuvent pas être modifiés. Si vous incluez des champs non compatibles dans votre demande de modification, une erreur s'affiche. Si la conversion en cours de modification contient des valeurs préexistantes pour des champs non compatibles, ces valeurs seront automatiquement conservées.

L'exemple ci-dessous illustre la création d'un objet de ressource de conversion simple à modifier:

C#

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Construct the conversion object with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = conversionOrdinal;
conversion.TimestampMicros = conversionTimestamp;

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.Quantity = newQuantity;
conversion.Value = newValue;

Java

// Create a conversion object populated with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(ordinal);
conversion.setTimestampMicros(timestampMicros);

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.setQuantity(newQuantity);
conversion.setValue(newValue);

PHP

// 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();

// Create a conversion object with values that identify the conversion to
// update.
$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($values['ordinal']);
$conversion->setTimestampMicros($values['timestamp']);

// Set the fields to be updated. These fields are required; to preserve a
// value from the existing conversion, it must be copied over manually.
$conversion->setQuantity($values['new_quantity']);
$conversion->setValue($values['new_value']);

Python

# Construct the conversion object with values that identify the conversion
# to update.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': ordinal,
    'timestampMicros': timestamp
}

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion['quantity'] = new_quantity
conversion['value'] = new_value

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  existing_conversion[:floodlight_activity_id])
floodlight_config_id = floodlight_activity.floodlight_configuration_id

# Construct the conversion with values that identify the conversion to
# update.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: existing_conversion[:encrypted_user_id],
  floodlight_activity_id: existing_conversion[:floodlight_activity_id],
  floodlight_configuration_id: floodlight_config_id,
  ordinal: existing_conversion[:ordinal],
  timestamp_micros: existing_conversion[:timestamp]
)

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion.quantity = new_quantity
conversion.value = new_value

Spécifier les informations de chiffrement

Si les conversions modifiées sont associées à des ID utilisateur chiffrés, vous devrez fournir des informations sur leur chiffrement dans la demande de modification. Pour en savoir plus, consultez le guide Importer des conversions.

Si nécessaire, la création d'un objet EncryptionInfo qui spécifie ces valeurs constitue la deuxième étape du workflow de modification:

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

Générer une requête de mise à jour

La dernière étape de ce processus consiste à modifier les conversions à l'aide d'un appel à batchupdate. Cette méthode accepte un objet ConversionsBatchUpdateRequest, qui combine l'ensemble des conversions à modifier avec les informations de chiffrement associées (le cas échéant):

C#

// Insert the conversion.
ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchUpdateResponse response =
    service.Conversions.Batchupdate(request, profileId).Execute();

Java

ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchUpdateResponse response = reporting.conversions()
    .batchupdate(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchUpdateRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchupdate(
    $values['user_profile_id'],
    $batch
);

Python

# Update the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchupdate(
    profileId=profile_id, body=request_body)
response = request.execute()

Ruby

# Construct the batch update request.
batch_update_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchUpdateRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Update the conversion.
result = service.batchupdate_conversion(profile_id, batch_update_request)

Sachez que Campaign Manager 360 tente de modifier chaque conversion de votre requête dans la mesure du possible, plutôt que de mettre à jour l'ensemble du lot en tant que transaction tout ou rien. Si la mise à jour de certaines conversions d'un lot échoue, il est possible que d'autres soient bien mises à jour. Par conséquent, nous vous recommandons d'inspecter l'ConversionsBatchUpdateResponse renvoyée pour déterminer l'état de chaque conversion:

C#

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully updated conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) updating 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 updated conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) updating 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 updated conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) updating 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 updated conversion for encrypted user ID %s.' %
        encrypted_user_id)
else:
  print('Error(s) updating 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) updating conversion for encrypted user ID %s.',
    existing_conversion[: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 updated conversion for encrypted user ID %s.',
    existing_conversion[: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 la mise à jour a échoué, le champ hasFailures vous permet de déterminer rapidement si une conversion du lot fourni a échoué.