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 di acquisire familiarità con i concetti illustrati in questa guida.

Configura le risorse di conversione

Il primo passaggio della procedura di caricamento delle conversioni consiste nel creare uno o più oggetti Conversion delle risorse. 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 la conversione.
floodlightConfigurationId	La configurazione Floodlight utilizzata dall'attività specificata.
ordinal	Un valore utilizzato per controllare in che modo vengono deduplicate le conversioni effettuate dallo stesso dispositivo o utente nello stesso giorno. Per ulteriori informazioni, consulta le Domande frequenti.
timestampMicros	Il timestamp della conversione, in microsecondi dal periodo 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 valore timestampMicros specificato. Se nessuno degli ID corrisponde a un'esposizione esistente, viene visualizzato 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 trasmesso a Campaign Manager 360 tramite un tag Floodlight.
mobileDeviceId	Un ID dispositivo mobile non criptato in formato IDFA o ID pubblicità o un identificatore di TV connessa a Internet (IFA) 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 per YouTube TV connesse a Internet.

I campi facoltativi sono documentati nella documentazione di riferimento. Tieni presente che il campo della quantità, anche se facoltativo, deve essere almeno 1 affinché la conversione venga conteggiata ai fini di determinate metriche (come le conversioni totali) durante l'esecuzione dei 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 informazioni crittografia

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

Se prevedi di attribuire le conversioni offline agli ID utente criptati, come nell'esempio precedente, devi fornire alcuni dettagli sulla crittografia come parte della richiesta di inserimento. In particolare, devi conoscere:

1. L'origine di crittografia, che descrive da dove proviene un gruppo 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 utilizzato per criptare gli ID utente. In genere, questi valori fanno riferimento 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 del tuo account Campaign Manager 360 o l'assistenza di Campaign Manager 360 per ulteriori informazioni.

Se necessario, la creazione di un oggetto EncryptionInfo 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 inserzione può contenere solo un oggetto EncryptionInfo. Ciò significa che tutte le conversioni incluse in una determinata richiesta devono derivare dalla stessa origine e utilizzare la stessa entità di crittografia.

Genera una richiesta di inserimento

Il passaggio finale di questa procedura è caricare le conversioni con una chiamata al numero batchinsert. Questo metodo accetta un oggetto ConversionsBatchInsertRequest, che combina l'insieme di conversioni da caricare con le informazioni sulla 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 cerca di inserire ogni conversione nella tua richiesta secondo il criterio del "best effort", anziché inserire l'intero batch come transazione "tutto o niente". Se l'inserimento di alcune conversioni in un batch non riesce, altre potrebbero essere ancora inserite correttamente. Pertanto, ti consigliamo di controllare la proprietà ConversionsBatchInsertResponse restituita 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 una conversione nel fornito non è andata a buon fine.

Verificare che le conversioni siano state elaborate

In genere, le conversioni caricate vengono elaborate e disponibili per la generazione di report entro 24 ore. Per verificare se le conversioni che hai caricato sono state elaborate, ti consigliamo di eseguire un report Impressioni Floodlight. A differenza degli altri report sull'attribuzione, per impostazione predefinita vengono restituite sia le conversioni attribuite (associate a un annuncio) sia quelle non attribuite. Per questo è ideale per verificare rapidamente se le conversioni inviate sono state inviate a Campaign Manager 360.

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