Modifica conversioni

Questa guida fornisce istruzioni dettagliate per la modifica delle conversioni utilizzando il servizio Conversions dell'API Campaign Manager 360. Prima di continuare, ti consigliamo di consultare la Panoramica per un'introduzione alle conversioni offline e per acquisire familiarità con i concetti discussi in questa guida.

Prima di iniziare

Questo workflow di modifica ti consente di modificare quantity e value delle conversioni online e offline esistenti. Per farlo, devi fornire valori che identifichino in modo univoco le conversioni da modificare. A seconda del tipo di conversioni che stai modificando, otterrai questi valori in modi diversi:

Una volta modificata correttamente una conversione di uno dei due tipi, ConversionsBatchUpdateResponse conterrà i valori necessari per eseguire le modifiche successive.

Configura le risorse di conversione

Il primo passaggio del workflow di modifica prevede la creazione di uno o più oggetti risorsa Conversion.

I seguenti campi vengono utilizzati per identificare una conversione da modificare. Questi campi sono obbligatori e devono corrispondere esattamente a una conversione esistente.

Campo Descrizione

encryptedUserId, gclid, dclid, matchid o mobileDeviceId

 L'ID utente criptato, l'ID clic Google, l'ID clic Display, l'ID corrispondenza o l'ID dispositivo mobile che ha generato la conversione.
floodlightActivityId L'attività Floodlight a cui è attribuita la conversione.
floodlightConfigurationId La configurazione Floodlight utilizzata dall'attività specificata.
ordinal L'identificatore di deduplicazione associato alla conversione.
timestampMicros Il timestamp della conversione, in microsecondi dall'epoca di Unix.

I campi che possono essere modificati sono elencati di seguito.

Questi campi sono obbligatori e i valori forniti sovrascriveranno eventuali valori preesistenti nella conversione in fase di modifica.

Campo Descrizione
quantity Il numero di elementi associati alla conversione.
value L'importo delle entrate generate dalla conversione.

Questi campi sono facoltativi. Se non viene impostato, il valore rimarrà invariato.

Campo Descrizione
customVariables Le variabili Floodlight personalizzate della conversione. Aggiorna o inserisce il valore se la variabile è impostata. Il valore della variabile rimane invariato se non viene impostato.

Tutti gli altri campi menzionati nella documentazione di riferimento non sono supportati e non possono essere modificati. L'inserimento di campi non supportati nella richiesta di modifica genererà un errore. Se la conversione in fase di modifica contiene valori preesistenti per campi non supportati, questi valori verranno conservati automaticamente.

L'esempio seguente illustra la creazione di un semplice oggetto risorsa di conversione da modificare:

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

Specifica le informazioni di crittografia

Se le conversioni in fase di modifica sono associate a ID utente criptati, dovrai fornire i dettagli su come sono criptati nell'ambito della richiesta di modifica. Per maggiori dettagli, consulta la guida Caricamento delle conversioni.

Se necessario, la creazione di un oggetto EncryptionInfo che specifica questi valori è il secondo passaggio del workflow di modifica:

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

Genera una richiesta di aggiornamento

L'ultimo passaggio di questo processo consiste nel modificare le conversioni con una chiamata a batchupdate. Questo metodo accetta un oggetto ConversionsBatchUpdateRequest, che combina l'insieme di conversioni da modificare con le relative informazioni di crittografia associate (se necessario):

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)

Tieni presente che Campaign Manager 360 tenta di modificare ogni conversione nella tua richiesta nel miglior modo possibile, anziché aggiornare l'intero batch come transazione "tutto o niente". Se alcune conversioni di un batch non vengono aggiornate, altre potrebbero comunque essere aggiornate correttamente. Pertanto, ti consigliamo di esaminare l'oggetto ConversionsBatchUpdateResponse restituito per determinare lo stato di ogni conversione:

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

Il campo status della risposta, come visto in precedenza, conterrà un oggetto ConversionStatus per ogni conversione inclusa nella richiesta originale. Se ti interessano solo le conversioni che non sono state aggiornate, puoi utilizzare il campo hasFailures per determinare rapidamente se una conversione nel batch fornito non è riuscita. Per indicazioni su come gestire ogni codice di errore e su quali conversioni non riuscite riprovare (INTERNAL e NOT_FOUND), consulta le domande frequenti.