Carica le conversioni

Questa guida fornisce istruzioni dettagliate per il caricamento delle conversioni offline utilizzando il servizio API Campaign Manager 360 Conversions. Prima di procedere, ti consigliamo di consultare la sezione Panoramica per un'introduzione alle conversioni offline e per familiarizzare con i concetti trattati in questa guida.

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

Configura le risorse di conversione

Il primo passaggio della procedura di caricamento delle conversioni consiste nella creazione di uno o più oggetti di risorsa Conversion. Ciascuno 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 modalità di deduplica delle conversioni provenienti dallo stesso dispositivo o dallo stesso 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 giorno timestampMicros specificato. Se nessuno degli ID corrisponde a un'esposizione esistente, verrà generato un errore.
dclid	Un identificatore dei 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 e trasmesso a Campaign Manager 360 tramite un tag Floodlight.
mobileDeviceId	Un ID mobile non criptato nel formato IDFA o AdID o un identificatore della pubblicità (IDFA) per TV connesse a internet da una piattaforma di dispositivi CTV supportata (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Tieni presente che Google non supporta gli IFA di YouTube per TV connesse a internet.

I campi facoltativi sono documentati nella documentazione di riferimento. Tieni presente che il campo Quantità, sebbene facoltativo, deve essere almeno pari a 1 affinché la conversione venga conteggiata ai fini di determinate metriche (ad esempio Conversioni totali) quando vengono generati i report.

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 sulla crittografia

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

Se prevedi di attribuire le conversioni offline a ID utente criptati, come nell'esempio precedente, dovrai fornire alcuni dettagli sulla loro crittografia 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. In genere, questi valori si riferiscono a un account Campaign Manager 360 quando la sorgente è Trasferimento dati o a un inserzionista Campaign Manager 360 quando la sorgente è la macro %m, ma non sempre è così. In caso di dubbi, contatta il rappresentante dell'account Campaign Manager 360 o l'assistenza di Campaign Manager 360 per ulteriori informazioni.

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

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 relative informazioni sulla crittografia (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 richiesta secondo il criterio del massimo impegno, anziché inserire l'intero batch come transazione all-or-nothing. Se non riesci a inserire alcune conversioni in un batch, altre potrebbero essere inserite correttamente. Pertanto, ti consigliamo di esaminare il valore 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 è stato possibile inserire, il campo hasFailures può essere utilizzato per determinare rapidamente se qualsiasi conversione nel batch fornito non è andata a buon fine.

Verificare che le conversioni siano state elaborate

In genere, le conversioni caricate vengono elaborate ed è possibile generare report al loro riguardo entro 24 ore. Per verificare se le conversioni che hai caricato sono state elaborate o meno, ti consigliamo di eseguire 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. Questo lo rende ideale per verificare rapidamente se le conversioni che hai inviato sono arrivate a Campaign Manager 360.

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