Konvertierungen bearbeiten

In diesem Leitfaden finden Sie eine detaillierte Anleitung zum Bearbeiten von Conversions mit dem Campaign Manager 360 API-Dienst Conversions. Bevor Sie fortfahren, sollten Sie sich die Übersicht ansehen, um eine Einführung in Offline-Conversions zu erhalten und sich mit den in diesem Leitfaden beschriebenen Konzepten vertraut zu machen.

Hinweis

Mit diesem Bearbeitungsworkflow können Sie den quantity und die value vorhandener Online- und Offline-Conversions ändern. Dazu müssen Sie Werte angeben, mit denen die zu bearbeitenden Conversions eindeutig identifiziert werden können. Je nach Art der Conversions, die Sie bearbeiten, erhalten Sie diese Werte auf unterschiedliche Weise:

  • Die Werte, die zur Identifizierung von Online-Conversions erforderlich sind, können über die Datenübertragung abgerufen werden.

  • Die Werte, die zur Identifizierung von Offline-Conversions erforderlich sind, werden im ConversionsBatchInsertResponse erfolgreicher batchinsert-Anfragen zurückgegeben.

Nachdem Sie eine Conversion eines der beiden Typen bearbeitet haben, enthält die ConversionsBatchUpdateResponse die Werte, die für nachfolgende Änderungen erforderlich sind.

Conversion-Ressourcen konfigurieren

Der erste Schritt im Bearbeitungsworkflow besteht darin, ein oder mehrere Conversion-Ressourcenobjekte zu erstellen.

Die folgenden Felder werden verwendet, um eine zu bearbeitende Conversion zu identifizieren. Diese Felder sind erforderlich und müssen genau mit einer vorhandenen Conversion übereinstimmen.

Feld Beschreibung

encryptedUserId oder gclid oder dclid oder matchid oder mobileDeviceId

 Die verschlüsselte Nutzer-ID, GCLID (Google Click ID), Display Click ID, ID zum Abgleich oder Mobilgeräte-ID, die die Conversion generiert hat.
floodlightActivityId Die Floodlight-Aktivität, der die Conversion zugeordnet ist.
floodlightConfigurationId Die von der angegebenen Aktivität verwendete Floodlight-Konfiguration.
ordinal Die Deduplizierungskennung, die der Conversion zugeordnet ist.
timestampMicros Der Zeitstempel der Conversion in Mikrosekunden seit der Unix-Epoche.

Die bearbeitbaren Felder sind unten aufgeführt.

Diese Felder sind erforderlich. Die von Ihnen angegebenen Werte überschreiben alle vorhandenen Werte für die bearbeitete Conversion.

Feld Beschreibung
quantity Die Anzahl der mit der Conversion verknüpften Artikel.
value Der durch die Conversion erzielte Umsatz.

Diese Felder sind optional. Der Wert bleibt unverändert, wenn er nicht festgelegt ist.

Feld Beschreibung
customVariables Die benutzerdefinierten Floodlight-Variablen der Conversion. Aktualisiert oder fügt den Wert ein, wenn die Variable festgelegt ist. Der Wert der Variablen bleibt unverändert, wenn er nicht festgelegt ist.

Alle anderen in der Referenzdokumentation erwähnten Felder werden nicht unterstützt und können nicht geändert werden. Wenn Sie nicht unterstützte Felder in Ihre Änderungsanfrage aufnehmen, wird ein Fehler ausgegeben. Wenn die bearbeitete Conversion bereits Werte für nicht unterstützte Felder enthält, werden diese Werte automatisch beibehalten.

Im folgenden Beispiel wird ein einfaches Conversion-Ressourcenobjekt erstellt, das bearbeitet werden soll:

C#

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Construct the conversion object with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = conversionOrdinal;
conversion.TimestampMicros = conversionTimestamp;

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.Quantity = newQuantity;
conversion.Value = newValue;

Java

// Create a conversion object populated with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(ordinal);
conversion.setTimestampMicros(timestampMicros);

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.setQuantity(newQuantity);
conversion.setValue(newValue);

PHP

// 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();

// Create a conversion object with values that identify the conversion to
// update.
$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($values['ordinal']);
$conversion->setTimestampMicros($values['timestamp']);

// Set the fields to be updated. These fields are required; to preserve a
// value from the existing conversion, it must be copied over manually.
$conversion->setQuantity($values['new_quantity']);
$conversion->setValue($values['new_value']);

Python

# Construct the conversion object with values that identify the conversion
# to update.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': ordinal,
    'timestampMicros': timestamp
}

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion['quantity'] = new_quantity
conversion['value'] = new_value

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  existing_conversion[:floodlight_activity_id])
floodlight_config_id = floodlight_activity.floodlight_configuration_id

# Construct the conversion with values that identify the conversion to
# update.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: existing_conversion[:encrypted_user_id],
  floodlight_activity_id: existing_conversion[:floodlight_activity_id],
  floodlight_configuration_id: floodlight_config_id,
  ordinal: existing_conversion[:ordinal],
  timestamp_micros: existing_conversion[:timestamp]
)

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion.quantity = new_quantity
conversion.value = new_value

Verschlüsselungsinformationen angeben

Wenn die zu bearbeitenden Conversions mit verschlüsselten Nutzer-IDs verknüpft sind, müssen Sie im Rahmen der Bearbeitungsanfrage Details zur Verschlüsselung angeben. Weitere Informationen finden Sie im Leitfaden Conversions hochladen.

Falls erforderlich, ist das Erstellen eines EncryptionInfo-Objekts, das diese Werte angibt, der zweite Schritt im Bearbeitungsworkflow:

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

Aktualisierungsanfrage generieren

Der letzte Schritt in diesem Prozess besteht darin, die Conversions mit einem Aufruf von batchupdate zu bearbeiten. Diese Methode akzeptiert ein ConversionsBatchUpdateRequest-Objekt, das die zu bearbeitenden Conversions mit den zugehörigen Verschlüsselungsinformationen (falls erforderlich) kombiniert:

C#

// Insert the conversion.
ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchUpdateResponse response =
    service.Conversions.Batchupdate(request, profileId).Execute();

Java

ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchUpdateResponse response = reporting.conversions()
    .batchupdate(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchUpdateRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchupdate(
    $values['user_profile_id'],
    $batch
);

Python

# Update the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchupdate(
    profileId=profile_id, body=request_body)
response = request.execute()

Ruby

# Construct the batch update request.
batch_update_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchUpdateRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Update the conversion.
result = service.batchupdate_conversion(profile_id, batch_update_request)

Beachten Sie, dass Campaign Manager 360 versucht, jede Conversion in Ihrer Anfrage nach bestem Wissen und Gewissen zu bearbeiten, anstatt den gesamten Batch als Alles-oder-Nichts-Transaktion zu aktualisieren. Wenn einige Conversions in einem Batch nicht aktualisiert werden, können andere möglicherweise trotzdem aktualisiert werden. Daher sollten Sie die zurückgegebene ConversionsBatchUpdateResponse prüfen, um den Status der einzelnen Conversions zu ermitteln:

C#

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully updated conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) updating 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 updated conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) updating 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 updated conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) updating 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 updated conversion for encrypted user ID %s.' %
        encrypted_user_id)
else:
  print('Error(s) updating 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) updating conversion for encrypted user ID %s.',
    existing_conversion[: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 updated conversion for encrypted user ID %s.',
    existing_conversion[:encrypted_user_id])
end

Das Feld status der Antwort enthält, wie bereits erwähnt, ein ConversionStatus-Objekt für jede Konvertierung, die in der ursprünglichen Anfrage enthalten war. Wenn Sie nur an Conversions interessiert sind, die nicht aktualisiert werden konnten, können Sie mit dem Feld hasFailures schnell feststellen, ob eine Conversion im angegebenen Batch fehlgeschlagen ist. Informationen zum Umgang mit den einzelnen Fehlercodes und dazu, welche fehlgeschlagenen Konvertierungen wiederholt werden sollten (INTERNAL und NOT_FOUND), finden Sie in den FAQs.