Prześlij konwersje

Ważne: zaktualizuj procesy związane z konwersjami offline do interfejsu Data Manager API, aby zwiększyć komfort pracy i uzyskać dostęp do dodatkowych funkcji. Nie zalecamy wdrażania nowych procesów związanych z konwersjami offline za pomocą interfejsu Campaign Manager 360 API.

W tym przewodniku znajdziesz szczegółowe instrukcje przesyłania konwersji offline za pomocą usługi Conversions interfejsu Campaign Manager 360 API. 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.

Uwaga: interfejs API obsługuje konwersje offline w Campaign Managerze 360 i Display & Video 360, ale dane koszyka nie są dostępne w żadnej z tych usług. Więcej informacji o danych koszyka.

Konfigurowanie zasobów konwersji

Pierwszym krokiem w procesie przesyłania konwersji jest utworzenie co najmniej 1 Conversion obiektów zasobów. Każdy z tych obiektów reprezentuje pojedyncze zdarzenie konwersji i zawiera kilka wymaganych pól:

Pole	Opis
floodlightActivityId	Aktywność Floodlight, z którą będzie powiązana ta konwersja.
floodlightConfigurationId	Konfiguracja Floodlight używana przez określoną aktywność.
ordinal	Wartość używana do kontrolowania sposobu deduplikacji konwersji z tego samego urządzenia lub użytkownika w tym samym dniu. Więcej informacji znajdziesz w najczęstszych pytaniach.
timestampMicros	Sygnatura czasowa konwersji w mikrosekundach od początku epoki uniksowej.

Każdy obiekt musi też zawierać jedno z tych pól:

Pole	Opis
encryptedUserId	Pojedynczy zaszyfrowany identyfikator użytkownika uzyskany z makra dopasowania%m lub Przenoszenia danych.
encryptedUserIdCandidates[]	Lista zaszyfrowanych identyfikatorów użytkowników uzyskanych z makra dopasowania%m lub Przenoszenia danych. Zostanie użyty pierwszy z tych identyfikatorów, który ma zarejestrowane wyświetlenie Floodlight przed określoną wartością timestampMicros. Jeśli żaden z identyfikatorów nie pasuje do istniejącego wyświetlenia, zostanie zgłoszony błąd.
dclid	Identyfikator kliknięcia reklamy displayowej wygenerowany przez Campaign Managera 360 lub Display & Video 360.
gclid	Identyfikator kliknięcia Google wygenerowany przez Google Ads lub Search Ads 360.
matchId	Unikalny identyfikator utworzony przez reklamodawcę, przekazywany do Campaign Managera 360 za pomocą tagu Floodlight.
mobileDeviceId	Niezaszyfrowany Identyfikator urządzenia mobilnego w formacie IDFA lub AdID albo identyfikator urządzenia CTV na potrzeby wyświetlania reklam (IFA) z obsługiwanej platformy urządzeń CTV (Android TV, Apple TV, Fire TV, Roku, Samsung, Vizio lub Xbox).

Każda konwersja ma też 2 dane:

Pole	Opis
quantity	Wymagane. Liczba elementów powiązanych z konwersją. Aby konwersja była uwzględniana w niektórych danych (np. w łącznej liczbie konwersji), musi wynosić co najmniej 1.
value	Kwota w dolarach powiązana z konwersją. Interpretowana w walucie reklamodawcy, który jest właścicielem konfiguracji Floodlight.

Pola opcjonalne są opisane w dokumentacji.

Poniższy przykład pokazuje, jak utworzyć prosty obiekt zasobu konwersji:

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
)

Określanie informacji o szyfrowaniu

Uwaga: ta sekcja dotyczy tylko przesyłania konwersji, które zawierają encryptedUserId lub encryptedUserIdCandidates[].

Jeśli planujesz przypisywać konwersje offline do zaszyfrowanych identyfikatorów użytkowników, tak jak w poprzednim przykładzie, musisz podać w żądaniu wstawienia pewne informacje o sposobie ich szyfrowania. W szczególności musisz znać:

1. The źródło szyfrowania, które opisuje, skąd pochodzi partia zaszyfrowanych identyfikatorów. Dopuszczalne wartości to AD_SERVING w przypadku identyfikatorów pochodzących z makra dopasowania %m lub DATA_TRANSFER w przypadku identyfikatorów pochodzących z plików Przenoszenia danych.

2. Podmiot szyfrowania, czyli unikalny zestaw wartości używanych do szyfrowania identyfikatorów użytkowników. Wartości te zwykle odnoszą się do konta Campaign Managera 360, gdy źródłem jest Przenoszenie danych, lub do reklamodawcy w Campaign Managerze 360, gdy źródłem jest makro %m, ale nie zawsze tak jest. Jeśli nie masz pewności, skontaktuj się z przedstawicielem konta Campaign Managera 360 lub zespołem pomocy Campaign Managera 360 w celu uzyskania dodatkowych informacji.

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

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

Pamiętaj, że każde żądanie wstawienia może zawierać tylko 1 obiekt EncryptionInfo. Oznacza to, że wszystkie konwersje zawarte w danym żądaniu muszą pochodzić z tego samego źródła i używać tego samego podmiotu szyfrowania.

Generowanie żądania wstawienia

Ostatnim krokiem w tym procesie jest przesłanie konwersji za pomocą wywołania batchinsert. Ta metoda akceptuje obiekt ConversionsBatchInsertRequest, który łączy zestaw konwersji do przesłania z powiązanymi informacjami o szyfrowaniu (w razie potrzeby):

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)

Pamiętaj, że Campaign Manager 360 próbuje wstawić każdą konwersję w żądaniu w najlepszy możliwy sposób, a nie wstawiać całej partii jako transakcji typu „wszystko albo nic”. Jeśli wstawienie niektórych konwersji w partii się nie powiedzie, inne mogą zostać wstawione. Dlatego zalecamy sprawdzenie zwróconej wartości ConversionsBatchInsertResponse, aby określić stan każdej konwersji:

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

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ę wstawić, możesz użyć pola hasFailures, aby szybko sprawdzić, czy jakakolwiek konwersja w podanej partii nie została wstawiona.

Sprawdzanie, czy konwersje zostały przetworzone

Przesłane konwersje są zwykle przetwarzane i dostępne w raportach w ciągu 24 godzin. Aby sprawdzić, czy przesłane konwersje zostały przetworzone , zalecamy uruchomienie raportu wyświetleń Floodlight. W przeciwieństwie do innych raportów o atrybucji te raporty domyślnie zwracają zarówno konwersje przypisane (powiązane z reklamą), jak i nieprzypisane. Dzięki temu możesz szybko sprawdzić, czy wysłane konwersje dotarły do Campaign Managera 360.

Uwaga: testy weryfikacyjne należy przeprowadzać na podstawie ostatnich konwersji. Raporty wyświetleń Floodlight nie będą uwzględniać konwersji przesłanych ponad 28 dni po ich sygnaturze czasowej.