Carica le conversioni

Questa guida fornisce istruzioni dettagliate per il caricamento delle conversioni offline 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.

Nota: anche se l'API supporta le conversioni offline per Campaign Manager 360 e Display & Video 360, i dati del carrello non sono disponibili per nessuno dei due prodotti. Scopri di più sui dati del carrello.

Configurare le risorse di conversione

Il primo passo della procedura di caricamento delle conversioni consiste nella creazione di uno o più Conversion oggetti risorsa. Ognuno di questi oggetti rappresenta un singolo evento di conversione e contiene alcuni campi obbligatori:

Campo	Descrizione
floodlightActivityId	L'attività Floodlight a cui verrà associata questa conversione.
floodlightConfigurationId	La configurazione Floodlight utilizzata dall'attività specificata.
ordinal	Un valore utilizzato per controllare la deduplicazione delle conversioni dallo stesso dispositivo o utente nello stesso giorno. Per ulteriori informazioni, consulta le Domande frequenti.
timestampMicros	Il timestamp della conversione, in microsecondi dall'epoca Unix.

Inoltre, ogni oggetto deve contenere uno dei seguenti campi:

Campo	Descrizione
encryptedUserId	Un singolo ID utente criptato ottenuto dalla macro di corrispondenza%m o da Data Transfer.
encryptedUserIdCandidates[]	Un elenco di ID utente criptati ottenuti dalla macro di corrispondenza%m o da Data Transfer. Verrà utilizzato il primo di questi ID con un'esposizione Floodlight registrata prima del timestampMicros specificato. Se nessuno degli ID corrisponde a un'esposizione esistente, verrà generato un errore.
dclid	Un identificatore di clic display generato da Campaign Manager 360 o Display & Video 360.
gclid	Un identificatore di clic di Google generato da Google Ads o Search Ads 360.
matchId	Un identificatore univoco creato dall'inserzionista passato a Campaign Manager 360 tramite un tag Floodlight.
mobileDeviceId	Un ID mobile non criptato in formato IDFA o ID pubblicità oppure un identificatore per la pubblicità (IFA) da un dispositivo TV connesso a internet supportato (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio).

Infine, ogni conversione ha due metriche:

Campo	Descrizione
quantity	Obbligatorio. Il numero di articoli associati alla conversione. Deve essere almeno 1 affinché la conversione venga conteggiata per determinate metriche (ad esempio Conversioni totali).
value	L'importo in dollari associato alla conversione. Interpretato nella valuta dell'inserzionista proprietario della configurazione Floodlight.

I campi facoltativi sono documentati nella documentazione di riferimento.

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

C#

// Generate a timestamp in milliseconds since Unix epoch.
TimeSpan timeSpan = DateTime.UtcNow - new DateTime(1970, 1, 1);
long currentTimeInMilliseconds = (long) timeSpan.TotalMilliseconds;

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Create the conversion.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = currentTimeInMilliseconds.ToString();
conversion.TimestampMicros = currentTimeInMilliseconds * 1000;

Java

long currentTimeInMilliseconds = System.currentTimeMillis();

// Find Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity = reporting.floodlightActivities()
    .get(profileId, floodlightActivityId).execute();
long floodlightConfigurationId = floodlightActivity.getFloodlightConfigurationId();

Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(String.valueOf(currentTimeInMilliseconds));
conversion.setTimestampMicros(currentTimeInMilliseconds * 1000);

PHP

$currentTimeInMicros = time() * 1000 * 1000;

// 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();

$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($currentTimeInMicros);
$conversion->setTimestampMicros($currentTimeInMicros);

Python

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = (
    service.floodlightActivities()
    .get(profileId=str(profile_id), id=str(floodlight_activity_id))
    .execute()
)
floodlight_config_id = floodlight_activity['floodlightConfigurationId']

current_time_in_micros = int(time.time() * 1000000)

# Construct the conversion.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': current_time_in_micros,
    'timestampMicros': current_time_in_micros
}

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  floodlight_activity_id)
floodlight_config_id = floodlight_activity.floodlight_configuration_id

current_time_in_micros = DateTime.now.strftime('%Q').to_i * 1000

# Construct the conversion.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: encrypted_user_id,
  floodlight_activity_id: floodlight_activity_id,
  floodlight_configuration_id: floodlight_config_id,
  ordinal: current_time_in_micros,
  timestamp_micros: current_time_in_micros
)

Specificare le informazioni di crittografia

Nota: questa sezione si applica solo al caricamento delle conversioni che contengono un encryptedUserId o encryptedUserIdCandidates[].

Se prevedi di attribuire le conversioni offline agli ID utente criptati, come nell'esempio precedente, dovrai fornire alcuni dettagli su come vengono criptati nell'ambito della richiesta di inserimento. In particolare, dovrai sapere:

1. L'origine della crittografia, che descrive da dove proviene un batch di ID criptati. I valori accettabili sono AD_SERVING per gli ID provenienti dalla macro di corrispondenza %m o DATA_TRANSFER per gli ID provenienti dai file di Data Transfer.

2. L'entità di crittografia, ovvero un insieme univoco di valori utilizzati per criptare gli ID utente. Questi valori in genere si riferiscono a un account Campaign Manager 360 quando l'origine è Data Transfer o a un inserzionista Campaign Manager 360 quando l'origine è la macro %m, ma non è sempre così. Se non sei sicuro, contatta il rappresentante dell'account Campaign Manager 360 o l'assistenza di Campaign Manager 360 per ulteriori informazioni.

Se necessario, la creazione di un EncryptionInfo oggetto che specifichi questi valori è il secondo passaggio della procedura di caricamento delle conversioni:

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

Tieni presente che ogni richiesta di inserimento può contenere solo un EncryptionInfo oggetto. Ciò significa che tutte le conversioni incluse in una determinata richiesta devono provenire dalla stessa origine e utilizzare la stessa entità di crittografia.

Generare una richiesta di inserimento

L'ultimo passo di questa procedura consiste nel caricare le conversioni con una chiamata a batchinsert. Questo metodo accetta un ConversionsBatchInsertRequest oggetto, che combina l'insieme di conversioni da caricare con le informazioni di crittografia associate (se necessario):

C#

// Insert the conversion.
ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchInsertResponse response =
    service.Conversions.Batchinsert(request, profileId).Execute();

Java

ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchInsertResponse response = reporting.conversions()
    .batchinsert(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchInsertRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchinsert(
    $values['user_profile_id'],
    $batch
);

Python

# Insert the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchinsert(
    profileId=str(profile_id), body=request_body
)
response = request.execute()

Ruby

# Construct the batch insert request.
batch_insert_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchInsertRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Insert the conversion.
result = service.batchinsert_conversion(profile_id, batch_insert_request)

Tieni presente che Campaign Manager 360 tenta di inserire ogni conversione nella richiesta nel miglior modo possibile, anziché inserire l'intero batch come transazione tutto o niente. Se l'inserimento di alcune conversioni in un batch non riesce, altre potrebbero comunque essere inserite correttamente. Pertanto, ti consigliamo di esaminare la restituita ConversionsBatchInsertResponse per determinare lo stato di ogni conversione:

C#

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully inserted conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) inserting 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 inserted conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) inserting 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 inserted conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) inserting 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 inserted conversion for encrypted user ID %s.'
      % encrypted_user_id
  )
else:
  print(
      'Error(s) inserting 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) inserting conversion for encrypted user ID %s.',
    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 inserted conversion for encrypted user ID %s.',
    encrypted_user_id)
end

Il campo status della risposta, come mostrato sopra, conterrà un ConversionStatus oggetto per ogni conversione inclusa nella richiesta originale. Se ti interessano solo le conversioni di cui non è stato eseguito l'inserimento, puoi utilizzare il campo hasFailures per determinare rapidamente se una qualsiasi conversione nel batch fornito non è stata inserita.

Verificare che le conversioni siano state elaborate

In genere, le conversioni caricate vengono elaborate e sono disponibili per i report entro 24 ore. Per verificare se le conversioni che hai caricato sono state elaborate, ti consigliamo di eseguire un report sulle impressioni Floodlight. A differenza di altri report sull'attribuzione, questi report restituiscono per impostazione predefinita sia le conversioni attribuite (associate a un annuncio) sia quelle non attribuite. Questo li rende ideali per verificare rapidamente se le conversioni che hai inviato sono state inserite in Campaign Manager 360.

Nota: i test di verifica devono essere eseguiti utilizzando le conversioni recenti. I report sulle impressioni Floodlight non rifletteranno le conversioni inviate più di 28 giorni dopo il timestamp.