L'API Campaign Manager 360 v4 a atteint la date de fin de vie prévue. Migrez immédiatement vers la version 5.

Modifier les conversions

Ce guide fournit des instructions détaillées pour modifier 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. En fonction du 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 à partir du 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, le 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 de ressource Conversion.

Les champs suivants sont utilisés pour identifier une conversion à modifier. Ces champs sont obligatoires et doivent exactement correspondre à une conversion existante.

Champ	Description
`encryptedUserId` ou `gclid` ou `dclid` ou `matchid` ou `mobileDeviceId`	ID utilisateur chiffré, ID de clic Google, ID de clic sur un display, ID de correspondance ou ID d'appareil mobile qui a 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`	L'identifiant de déduplication associé à la conversion.
`timestampMicros`	Code temporel de la conversion, en microsecondes depuis l'epoch Unix.

Les champs qui peuvent être modifiés sont listés ci-dessous.

Ces champs sont obligatoires et les valeurs que vous fournissez écraseront 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 aucune valeur n'est définie, la valeur reste inchangée.

Champ	Description
`customVariables`	Variables Floodlight personnalisées de la conversion. Met à jour ou insère la valeur si la variable est définie. Si aucune valeur n'est définie, la valeur de la variable reste inchangée.

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 se produira. 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 en cours de modification sont associées à des ID utilisateur chiffrés, vous devez 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 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 en appelant batchupdate. Cette méthode accepte un objet ConversionsBatchUpdateRequest, qui combine l'ensemble des conversions à modifier avec leurs 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)

Sachez que Campaign Manager 360 tente de modifier chaque conversion de votre demande au mieux de ses capacités, plutôt que de mettre à jour l'ensemble du lot comme une transaction tout ou rien. Si certaines conversions d'un lot ne sont pas mises à jour, d'autres peuvent 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

Le champ status de la réponse, comme indiqué ci-dessus, 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 mises à jour, vous pouvez utiliser le champ hasFailures pour déterminer rapidement si une conversion du lot fourni a échoué.

Modifier les conversions Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Configurer les ressources de conversion

C#

Java

PHP

Python

Ruby

Spécifier les informations de chiffrement

C#

Java

PHP

Python

Ruby

Générer une demande de mise à jour

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

Modifier les conversions