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 trattati in questa guida.

Prima di iniziare

Questo flusso di lavoro di modifica ti consente di modificare la quantity e il 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:

• I valori necessari per identificare le conversioni online possono essere ottenuti da Data Transfer.

• I valori necessari per identificare le conversioni offline vengono restituiti in ConversionsBatchInsertResponse delle richieste batchinsert riuscite.

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

Configurare le risorse di conversione

Il primo passaggio del flusso di lavoro 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 o gclid o dclid o 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. Il campo encryptedUserIdCandidates non può essere utilizzato per le modifiche.
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 Unix.

Di seguito sono elencati i campi che possono essere modificati.

Questi campi sono obbligatori e i valori che fornisci sovrascriveranno tutti i valori preesistenti nella conversione che stai modificando.

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

Questi campi sono facoltativi. Se non è impostato, il valore rimane invariato.

Campo	Descrizione
customVariables	Le variabili Floodlight personalizzate della conversione. Aggiornerà o inserirà il valore se la variabile è impostata. Se non è impostato, il valore della variabile rimane invariato.

Tutti gli altri campi menzionati nella documentazione di riferimento non sono supportati e non possono essere modificati. L'inclusione di campi non supportati nella richiesta di modifica genererà un errore. Se la conversione che stai modificando contiene valori preesistenti per i 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

Specificare le informazioni di crittografia

Nota: questa sezione si applica solo quando modifichi le conversioni che contengono un encryptedUserId.

Se le conversioni che stai modificando sono associate a ID utente criptati, devi fornire i dettagli su come vengono criptati nell'ambito della richiesta di modifica. Per maggiori dettagli, consulta la guida Caricare le conversioni.

Se necessario, la creazione di un oggetto EncryptionInfo che specifichi questi valori è il secondo passaggio del flusso di lavoro 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]
)

Generare una richiesta di aggiornamento

L'ultimo passaggio di questa procedura 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 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 richiesta in base al principio del "best effort", anziché aggiornare l'intero batch come transazione "tutto o niente". Se l'aggiornamento di alcune conversioni in un batch non riesce, altre potrebbero comunque essere aggiornate correttamente. Pertanto, ti consigliamo di esaminare il 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 mostrato sopra, 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.