Edytuj konwersje

Ten przewodnik zawiera szczegółowe instrukcje edytowania konwersji za pomocą usługi Campaign Manager 360 API Conversions. Zanim przejdziesz dalej, zapoznaj się z omówieniem, aby dowiedzieć się więcej o konwersjach offline i poznać pojęcia omówione w tym przewodniku.

Zanim zaczniesz

Ten proces edycji umożliwia modyfikowanie quantity i value dotychczasowych konwersji online i offline. Aby to zrobić, musisz podać wartości, które jednoznacznie identyfikują konwersje do edycji. W zależności od rodzaju edytowanych konwersji te wartości można uzyskać na różne sposoby:

Po pomyślnym edytowaniu konwersji dowolnego typu w pliku ConversionsBatchUpdateResponse znajdą się wartości niezbędne do przeprowadzenia kolejnych edycji.

Konfigurowanie zasobów konwersji

Pierwszym krokiem w procesie edycji jest utworzenie co najmniej 1 obiektu zasobu Conversion.

Te pola służą do identyfikowania konwersji, którą chcesz edytować. Te pola są wymagane i muszą dokładnie odpowiadać istniejącej konwersji.

Pole Opis

encryptedUserId, gclid, dclid, matchid lub mobileDeviceId

 Zaszyfrowany identyfikator użytkownika, identyfikator kliknięcia Google, identyfikator kliknięcia reklamy displayowej, identyfikator MatchID lub identyfikator urządzenia mobilnego, który wygenerował konwersję.
floodlightActivityId Aktywność Floodlight, do której przypisana jest konwersja.
floodlightConfigurationId Konfiguracja Floodlight używana przez określoną aktywność.
ordinal Identyfikator deduplikacji powiązany z konwersją.
timestampMicros Sygnatura czasowa konwersji w mikrosekundach od początku epoki uniksowej.

Poniżej znajdziesz listę pól, które można edytować.

Te pola są wymagane, a podane w nich wartości zastąpią wszystkie dotychczasowe wartości w edytowanej konwersji.

Pole Opis
quantity Liczba produktów powiązanych z konwersją.
value Kwota przychodów wygenerowanych przez konwersję.

Te pola są opcjonalne. Jeśli nie zostanie ustawiona, wartość pozostanie bez zmian.

Pole Opis
customVariables Niestandardowe zmienne Floodlight konwersji. Jeśli zmienna jest ustawiona, wartość zostanie zaktualizowana lub wstawiona. Jeśli zmienna nie zostanie ustawiona, jej wartość pozostanie bez zmian.

Wszystkie pozostałe pola wymienione w dokumentacji nie są obsługiwane i nie można ich modyfikować. Uwzględnienie w żądaniu edycji nieobsługiwanych pól spowoduje błąd. Jeśli edytowana konwersja zawiera wcześniej ustawione wartości w przypadku nieobsługiwanych pól, zostaną one automatycznie zachowane.

Przykład poniżej pokazuje tworzenie prostego obiektu zasobu konwersji do edycji:

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

Podaj informacje o szyfrowaniu

Jeśli edytowane konwersje są powiązane z zaszyfrowanymi identyfikatorami użytkowników, w ramach prośby o edytowanie musisz podać szczegóły dotyczące sposobu ich szyfrowania. Szczegółowe informacje znajdziesz w przewodniku Przesyłanie konwersji.

W razie potrzeby utworzenie obiektu EncryptionInfo, który określa te wartości, jest drugim krokiem w procesie edycji:

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

Generowanie żądania aktualizacji

Ostatnim krokiem tego procesu jest edytowanie konwersji za pomocą wywołania batchupdate. Ta metoda akceptuje obiekt ConversionsBatchUpdateRequest, który łączy zestaw konwersji do edycji z powiązanymi informacjami o szyfrowaniu (w razie potrzeby):

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)

Pamiętaj, że Campaign Manager 360 próbuje edytować każdą konwersję w Twojej prośbie w miarę możliwości, a nie aktualizować całej partii jako transakcji typu „wszystko albo nic”. Jeśli nie uda się zaktualizować niektórych konwersji w partii, inne mogą zostać zaktualizowane. Dlatego zalecamy sprawdzenie zwróconego parametru ConversionsBatchUpdateResponse, aby określić stan każdej konwersji:

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

Pole status w odpowiedzi, jak widać powyżej, będzie zawierać obiekt ConversionStatus dla każdej konwersji uwzględnionej w pierwotnym żądaniu. Jeśli interesują Cię tylko konwersje, których nie udało się zaktualizować, możesz użyć pola hasFailures, aby szybko sprawdzić, czy jakakolwiek konwersja w podanej partii nie powiodła się.