Carica le conversioni

Questa guida fornisce istruzioni dettagliate per caricare le conversioni offline utilizzando il servizio API Campaign Manager 360 Conversions. Prima di continuare, ti consigliamo di leggere 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.

Configura le risorse di conversione

Il primo passaggio della procedura di caricamento delle conversioni consiste nel creare uno o più oggetti risorsa Conversion. 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 di 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 decriptabile in formato IDFA o ID pubblicità oppure un identificatore per la pubblicità (IFA) delle TV connesse a internet da una piattaforma di dispositivi TV connessi a internet supportata (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Tieni presente che Google non supporta gli IFA delle TV connesse a internet di YouTube.

Infine, ogni conversione ha due metriche:

Campo	Descrizione
quantity	Obbligatorio. Il numero di elementi associati alla conversione. Deve essere almeno 1 affinché la conversione venga conteggiata in 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=profile_id, id=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
)

Specifica le informazioni di crittografia

Nota: questa sezione si applica solo quando carichi conversioni che contengono un encryptedUserId o un encryptedUserIdCandidates[].

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

1. L'origine della crittografia, che descrive la provenienza di 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 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ì. In caso di dubbi, contatta il rappresentante dell'account Campaign Manager 360 o l'assistenza Campaign Manager 360 per ulteriori informazioni.

Se necessario, la creazione di un oggetto EncryptionInfo che specifica questi valori è il secondo passaggio del processo 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 un solo oggetto EncryptionInfo. 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 passaggio di questa procedura consiste nel caricare le conversioni con una chiamata a batchinsert. Questo metodo accetta un oggetto ConversionsBatchInsertRequest, 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=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 tua 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 va a buon fine, altre potrebbero comunque essere inserite correttamente. Pertanto, ti consigliamo di esaminare il ConversionsBatchInsertResponse restituito 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 oggetto ConversionStatus per ogni conversione inclusa nella richiesta originale. Se ti interessano solo le conversioni che non sono state inserite, il campo hasFailures può essere utilizzato per determinare rapidamente se una conversione nel batch fornito non è riuscita.

Verificare che le conversioni siano state elaborate

Le conversioni caricate verranno generalmente elaborate e saranno disponibili per i report entro 24 ore. Per verificare se le conversioni che hai caricato sono state elaborate, ti consigliamo di generare un report sulle impressioni Floodlight. A differenza di altri report sull'attribuzione, questi restituiranno per impostazione predefinita sia le conversioni attribuite (associate a un annuncio) sia quelle non attribuite. Ciò lo rende ideale per verificare rapidamente se le conversioni che hai inviato sono state registrate 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.