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

Modifier les conversions

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

Avant de commencer

Ce workflow vous permet de modifier la quantity et la value des conversions en ligne et hors connexion existantes. Pour ce faire, vous devez fournir des valeurs identifiant de façon unique les conversions à modifier. Selon le type de conversion 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 grâce au transfert de données.
Les valeurs nécessaires pour identifier les conversions hors connexion sont renvoyées dans le ConversionsBatchInsertResponse des requêtes batchinsert ayant abouti.

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

Configurer les ressources de conversion

La première étape du workflow de modification consiste à créer un ou plusieurs objets 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`, `dclicd`, `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 apporter des 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`	Horodatage de la conversion en microsecondes depuis l'epoch Unix.

Les champs modifiables sont indiqués ci-dessous. Ces champs sont obligatoires, et les valeurs fournies remplaceront les valeurs préexistantes pour la conversion en cours de modification.

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

Tous les autres champs mentionnés dans la documentation de référence ne sont pas acceptés et ne peuvent pas être modifiés. Si vous ajoutez des champs non compatibles dans votre demande de modification, vous obtiendrez une erreur. Si la conversion en cours de modification contient des valeurs préexistantes pour des champs non compatibles, ces valeurs sont 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 en cours de modification sont associées à des ID utilisateur chiffrés, vous devrez fournir des informations sur le chiffrement de ces conversions dans la demande de modification. Pour en savoir plus, consultez le guide Importer des conversions.

Si nécessaire, la deuxième étape du workflow de modification 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]
)

Générer une demande de mise à jour

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

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)

Notez que Campaign Manager 360 tente de modifier chaque conversion de votre demande de la façon la plus optimale possible, au lieu de mettre à jour l'intégralité du lot comme une transaction "tout ou rien". Si certaines conversions d'un lot ne sont pas mises à jour, d'autres peuvent tout de même l'être. Par conséquent, nous vous recommandons d'inspecter le ConversionsBatchUpdateResponse renvoyé 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 seules les conversions dont la mise à jour a échoué ne vous intéressent, vous pouvez utiliser le champ hasFailures pour déterminer rapidement si une conversion du lot fourni a échoué.