Questa pagina è stata tradotta dall'API Cloud Translation.

Modifica conversioni

Questa guida fornisce istruzioni dettagliate per la modifica delle conversioni utilizzando il servizio Conversions 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 quantity e value delle conversioni online e offline esistenti. A tal fine, dovrai 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 nel ConversionsBatchInsertResponse delle richieste batchinsert andate a buon fine.

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

Configura le risorse di conversione

Il primo passaggio del flusso di lavoro di modifica prevede la creazione di uno o più oggetti di 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 deduplica associato alla conversione.
`timestampMicros`	Il timestamp della conversione, in microsecondi dall'epoca Unix.

I campi che possono essere modificati sono elencati di seguito.

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

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 rimarrà invariato.

Campo	Descrizione
`customVariables`	Le variabili Floodlight personalizzate della conversione. Aggiorna o inserisce 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 comporterà un errore. Se la conversione in fase di modifica contiene valori preesistenti per i campi non supportati, questi valori verranno conservati automaticamente.

L'esempio seguente illustra la creazione di un semplice oggetto risorsa 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 sulla crittografia

Se le conversioni da modificare sono associate a ID utente criptati, dovrai fornire dettagli su come vengono criptati nell'ambito della richiesta di modifica. Per maggiori dettagli, consulta la guida Caricare le conversioni.

Se necessario, crea un oggetto EncryptionInfo che specifichi questi valori nel 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]
)

Genera 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 relative informazioni sulla 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 secondo il criterio del "best effort", anziché aggiornare l'intero batch come transazione all-or-nothing. Se l'aggiornamento di alcune conversioni in un batch non va a buon fine, è possibile che altre vengano aggiornate correttamente. Pertanto, ti consigliamo di esaminare il valore 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 di cui non è stato possibile aggiornare i dati, puoi utilizzare il campo hasFailures per determinare rapidamente se qualsiasi conversione nel batch fornito non è andata a buon fine.