Conversions hochladen

In dieser Anleitung finden Sie eine detaillierte Beschreibung zum Hochladen von Offline-Conversions mit dem Conversions-Dienst der Campaign Manager 360 API. Bevor Sie fortfahren, sollten Sie sich die Übersicht ansehen, um sich mit Offline-Conversions vertraut zu machen und die in diesem Leitfaden behandelten Konzepte kennenzulernen.

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

Conversion-Ressourcen konfigurieren

Der erste Schritt beim Hochladen von Conversions ist das Erstellen von einem oder mehreren Conversion-Ressourcenobjekten. Jedes dieser Objekte stellt ein einzelnes Conversion-Ereignis dar und enthält einige Pflichtfelder:

Feld	Beschreibung
floodlightActivityId	Die Floodlight-Aktivität, der diese Conversion zugeordnet wird.
floodlightConfigurationId	Die von der angegebenen Aktivität verwendete Floodlight-Konfiguration.
ordinal	Ein Wert, mit dem gesteuert wird, wie Conversions, die vom selben Gerät oder Nutzer und vom selben Tag stammen, dedupliziert werden. Weitere Informationen finden Sie in den FAQ.
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 %m-Abgleichmakro oder die Datenübertragung abgerufen wurde.
encryptedUserIdCandidates[]	Eine Liste mit verschlüsselten Nutzer-IDs, die über das %m-Abgleichsmakro oder die Datenübertragung abgerufen wurden. Die erste dieser IDs mit einer aufgezeichneten Floodlight-Impression vor dem angegebenen timestampMicros wird verwendet. Wenn keine der IDs mit einer vorhandenen Testgruppe übereinstimmt, wird ein Fehler ausgegeben.
dclid	Eine von Campaign Manager 360 oder Display & Video 360 generierte Kennung für Klicks im Displaynetzwerk.
gclid	Ein von Google Ads oder Search Ads 360 generierter Google Click Identifier.
matchId	Eine eindeutige vom Werbetreibenden erstellte ID, die über ein Floodlight-Tag an Campaign Manager 360 gesendet wird.
mobileDeviceId	Eine nicht verschlüsselte mobile ID im IDFA- oder AdID-Format oder eine IFA (Identifier for Advertising) 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.

Jede Conversion hat zwei Messwerte:

Feld	Beschreibung
quantity	Erforderlich. Die Anzahl der Elemente, die mit der Conversion verknüpft sind. Muss mindestens 1 sein, damit die Conversion für bestimmte Messwerte (z. B. „Conversions insgesamt“) berücksichtigt wird.
value	Der mit der Conversion verbundene Dollarbetrag. Wird entsprechend der Währung des Werbetreibenden interpretiert, dem die Floodlight-Konfiguration gehört.

Optionale Felder sind in der Referenzdokumentation dokumentiert.

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

Verschlüsselungsinformationen angeben

Hinweis: Dieser Abschnitt gilt nur, wenn Sie Conversions hochladen, die eine encryptedUserId oder encryptedUserIdCandidates[] enthalten.

Wenn Sie Offline-Conversions verschlüsselten Nutzer-IDs zuordnen möchten, wie im vorherigen Beispiel, müssen Sie in Ihrer Einfügeanfrage einige Details zur Verschlüsselung angeben. Insbesondere müssen Sie Folgendes wissen:

1. Die Verschlüsselungsquelle, die beschreibt, woher eine Gruppe verschlüsselter IDs stammt. Zulässige Werte sind AD_SERVING für IDs aus dem Makro „%m“ oder DATA_TRANSFER für IDs aus Dateien zur Datenübertragung.

2. Die Verschlüsselungseinheit, eine eindeutige Gruppe 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 „Data Transfer“ ist, oder auf einen Campaign Manager 360-Werbetreibenden, wenn die Quelle das Makro „%m“ ist. Das ist jedoch 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.

Bei Bedarf ist das Erstellen eines EncryptionInfo-Objekts, in dem diese Werte angegeben werden, der zweite Schritt beim Hochladen von Conversions:

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 Einfügeanfrage darf nur ein EncryptionInfo-Objekt enthalten. Das bedeutet, dass alle Conversions in einer bestimmten Anfrage aus derselben Quelle stammen und dieselbe Verschlüsselungseinheit verwenden müssen.

Einfüge-Anfrage generieren

Der letzte Schritt in diesem Prozess besteht darin, Ihre Conversions mit einem Aufruf von batchinsert hochzuladen. Diese Methode akzeptiert ein ConversionsBatchInsertRequest-Objekt, das die hochzuladenden Conversions mit den zugehörigen Verschlüsselungsinformationen (falls erforderlich) kombiniert:

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)

Campaign Manager 360 versucht, jede Conversion in Ihre Anfrage einzufügen. Es wird also nicht der gesamte Batch als Alles-oder-Nichts-Transaktion eingefügt. Wenn einige Conversions in einem Batch nicht eingefügt werden können, werden andere möglicherweise trotzdem eingefügt. Daher wird empfohlen, das zurückgegebene ConversionsBatchInsertResponse zu prüfen, um den Status jeder Conversion 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 Feld status der Antwort, wie oben zu sehen, enthält ein ConversionStatus-Objekt für jede Conversion, die in der ursprünglichen Anfrage enthalten ist. Wenn Sie sich nur für Conversions interessieren, die nicht eingefügt werden konnten, können Sie mit dem Feld hasFailures schnell feststellen, ob irgendeine Conversion im bereitgestellten Batch fehlgeschlagen ist.

Prüfen, ob Conversions verarbeitet wurden

Hochgeladene Conversions werden in der Regel innerhalb von 24 Stunden verarbeitet und sind dann für Berichte verfügbar. Wenn Sie prüfen möchten, ob hochgeladene Conversions verarbeitet wurden, empfehlen wir, einen Floodlight-Impressionsbericht zu erstellen. Im Gegensatz zu anderen Attributionsberichten werden hier standardmäßig sowohl zugeordnete (mit einer Anzeige verknüpfte) als auch nicht zugeordnete Conversions zurückgegeben. So lässt sich schnell prüfen, ob die von Ihnen gesendeten Conversions in Campaign Manager 360 angekommen sind.

Hinweis :Für die Überprüfungstests sollten aktuelle Conversions verwendet werden. In Berichten zu Floodlight-Impressionen werden keine Conversions berücksichtigt, die mehr als 28 Tage nach dem Zeitstempel eingereicht wurden.