Conversions hochladen

In dieser Anleitung finden Sie eine detaillierte Anleitung zum Hochladen von Offline-Conversions mit dem Campaign Manager 360 API-Dienst Conversions. Bevor Sie fortfahren, sollten Sie sich die Übersicht ansehen. Dort erhalten Sie eine Einführung in Offline-Conversions und werden mit den in diesem Leitfaden erläuterten Konzepten vertraut gemacht.

Hinweis :Die API unterstützt Offline-Conversions für Campaign Manager 360 und Display & Video 360. Warenkorbdaten sind jedoch für keines dieser Produkte verfügbar. Weitere Informationen zu Warenkorbdaten

Conversion-Ressourcen konfigurieren

Der erste Schritt beim Konvertierungsupload besteht darin, ein oder mehrere Conversion-Ressourcenobjekte zu erstellen. Jedes dieser Objekte stellt ein einzelnes Conversion-Ereignis dar und enthält einige Pflichtfelder:

Feld	Beschreibung
floodlightActivityId	Die Floodlight-Aktivität, mit der diese Conversion verknüpft wird.
floodlightConfigurationId	Die Floodlight-Konfiguration, die von der angegebenen Aktivität verwendet wird.
ordinal	Mit diesem Wert wird gesteuert, wie Conversions vom selben Gerät oder Nutzer am selben Tag dedupliziert werden. Weitere Informationen finden Sie in den häufig gestellten Fragen.
timestampMicros	Der Zeitstempel der Conversion in Mikrosekunden seit der Unix-Epoche.

Außerdem muss jedes Objekt eines der folgenden Felder enthalten:

Feld	Beschreibung
encryptedUserId	Eine einzelne verschlüsselte Nutzer-ID, die über das Abgleichsmakro%m oder die Datenübertragung erfasst wurde.
encryptedUserIdCandidates[]	Eine Liste verschlüsselter Nutzer-IDs, die über das Abgleichsmakro „%m“ oder die Datenübertragung erfasst wurden. Die erste dieser IDs mit einer erfassten Floodlight-Auslieferung vor dem angegebenen timestampMicros wird verwendet. Wenn keine der IDs mit einer vorhandenen Auslieferung übereinstimmt, wird ein Fehler ausgegeben.
dclid	Eine Displayklick-ID, die in Campaign Manager 360 oder Display & Video 360 generiert wurde.
gclid	Eine Google-Klick-ID, die von Google Ads oder Search Ads 360 generiert wurde.
matchId	Eine eindeutige vom Werbetreibenden erstellte Kennung, die über ein Floodlight-Tag an Campaign Manager 360 übergeben wird.
mobileDeviceId	Eine unverschlüsselte mobile ID im IDFA- oder AdID-Format oder eine Identifier for Advertising (IFA) für internetfähige Fernseher von einer unterstützten CTV-Geräteplattform (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Google unterstützt keine IFAs für internetfähige Fernseher von YouTube.

Optionale Felder sind in der Referenzdokumentation dokumentiert. Das Feld „Menge“ ist zwar optional, muss aber mindestens den Wert „1“ haben, damit die Conversion bei der Erstellung von Berichten für bestimmte Messwerte (z. B. „Conversions insgesamt“) berücksichtigt wird.

Im folgenden Beispiel wird die Erstellung eines einfachen Conversion-Ressourcenobjekts veranschaulicht:

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
)

Verschlüsselungsinformationen angeben

Hinweis: Dieser Abschnitt gilt nur für den Upload von Conversions, die eine encryptedUserId oder encryptedUserIdCandidates[] enthalten.

Wenn Sie wie im vorherigen Beispiel Offline-Conversions verschlüsselten Nutzer-IDs zuordnen möchten, müssen Sie im Rahmen Ihrer Anfrage zum Einfügen einige Details dazu angeben, wie sie verschlüsselt sind. Insbesondere sollten Sie Folgendes wissen:

1. Die Verschlüsselungsquelle, die angibt, woher eine Gruppe verschlüsselter IDs stammt. Zulässige Werte sind AD_SERVING für IDs aus dem Abgleichs-Makro %m oder DATA_TRANSFER für IDs aus Berichtsdateien.

2. Die Verschlüsselungsentität, eine eindeutige Reihe von Werten, die zum Verschlüsseln von Nutzer-IDs verwendet wird. Diese Werte beziehen sich normalerweise auf ein Campaign Manager 360-Konto, wenn die Quelle „Datenübertragung“ ist, oder auf einen Campaign Manager 360-Werbetreibenden, wenn die Quelle das Makro „%m“ ist. Das ist aber nicht immer der Fall. Wenn Sie sich nicht sicher sind, wenden Sie sich an Ihren Campaign Manager 360-Account Manager oder den Campaign Manager 360-Support.

Im zweiten Schritt des Conversion-Uploads erstellen Sie bei Bedarf ein EncryptionInfo-Objekt, in dem diese Werte angegeben sind:

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

Jede Anfrage zum Einfügen darf nur ein EncryptionInfo-Objekt enthalten. Das bedeutet, dass alle Conversions in einer bestimmten Anfrage aus derselben Quelle stammen und dieselbe Verschlüsselungsentität verwenden müssen.

Anfrage für Anzeigenbereitstellung generieren

Im letzten Schritt laden Sie Ihre Conversions mit einem Aufruf von batchinsert hoch. Diese Methode akzeptiert ein ConversionsBatchInsertRequest-Objekt, das die hochzuladenden Conversions mit den zugehörigen Verschlüsselungsinformationen kombiniert (falls erforderlich):

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)

In Campaign Manager 360 wird versucht, jede Conversion in Ihrem Antrag bestmöglich einzufügen, anstatt den gesamten Batch als Transaktion vom Typ „Alles oder nichts“ einzufügen. Wenn einige Conversions in einem Batch nicht eingefügt werden können, können andere möglicherweise trotzdem erfolgreich eingefügt werden. Daher wird empfohlen, die zurückgegebene ConversionsBatchInsertResponse zu prüfen, um den Status der einzelnen Conversions zu ermitteln:

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

Das status-Feld der Antwort enthält, wie oben zu sehen, für jede in der ursprünglichen Anfrage enthaltene Conversion ein ConversionStatus-Objekt. Wenn Sie nur an Conversions interessiert sind, die nicht eingefügt werden konnten, können Sie mit dem Feld hasFailures schnell feststellen, ob eine Conversion im angegebenen Batch fehlgeschlagen ist.

Prüfen, ob Conversions verarbeitet wurden

Hochgeladene Conversions werden in der Regel innerhalb von 24 Stunden verarbeitet und können dann in Berichten verwendet werden. Wenn Sie prüfen möchten, ob die von Ihnen hochgeladenen Conversions verarbeitet wurden, sollten Sie einen Floodlight-Impressionsbericht erstellen. Im Gegensatz zu anderen Attributionsberichten werden hier standardmäßig sowohl zugeordnete (einer Anzeige zugeordnete) als auch nicht zugeordnete Conversions zurückgegeben. So können Sie schnell prüfen, ob die von Ihnen gesendeten Conversions in Campaign Manager 360 angekommen sind.

Hinweis :Für die Bestätigungstests sollten aktuelle Conversions verwendet werden. In Berichten zu Floodlight-Impressionen werden keine Conversions berücksichtigt, die mehr als 28 Tage nach dem Zeitstempel gesendet wurden.