Prześlij konwersje

Ten przewodnik zawiera szczegółowe instrukcje przesyłania konwersji offline za pomocą usługi interfejsu Campaign Manager 360 API Conversions. Zanim przejdziesz dalej, zapoznaj się z omówieniem, aby poznać konwersje offline i zapoznać się z koncepcjami omówionymi w tym przewodniku.

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

Konfigurowanie zasobów konwersji

Pierwszym krokiem w procesie przesyłania konwersji jest utworzenie co najmniej 1 obiektu zasobu Conversion. 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 usuwania duplikatów konwersji z tego samego urządzenia lub od tego samego 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.

Dodatkowo każdy obiekt musi 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, w przypadku którego odnotowano wyświetlenie Floodlight przed podaną datą timestampMicros. Jeśli żaden z identyfikatorów nie pasuje do istniejącej ekspozycji, wystąpi 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). Pamiętaj, że Google nie obsługuje identyfikatorów IFA w przypadku YouTube na urządzeniach CTV.

Każda konwersja ma 2 rodzaje danych:

Pole	Opis
quantity	Wymagane. Liczba produktów powiązanych z konwersją. Musi wynosić co najmniej 1, aby konwersja była uwzględniana w przypadku niektórych rodzajów danych (np. Łączna liczba konwersji).
value	Kwota w dolarach powiązana z konwersją. Interpretowana w walucie reklamodawcy będącego właścicielem konfiguracji Floodlight.

Pola opcjonalne są opisane w dokumentacji referencyjnej.

Przykład poniżej 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=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
)

Podaj informacje o szyfrowaniu

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

Jeśli planujesz przypisywać konwersje offline do zaszyfrowanych identyfikatorów użytkowników, tak jak w poprzednim przykładzie, w ramach żądania wstawienia musisz podać pewne szczegóły dotyczące sposobu szyfrowania tych identyfikatorów. W szczególności musisz wiedzieć:

1. Źródło szyfrowania, które określa, skąd pochodzi partia zaszyfrowanych identyfikatorów. Akceptowane wartości to AD_SERVING w przypadku identyfikatorów pochodzących z makra %m match lub DATA_TRANSFER w przypadku identyfikatorów pochodzących z plików Przenoszenia danych.

2. Podmiot szyfrujący, czyli unikalny zestaw wartości używanych do szyfrowania identyfikatorów użytkowników. Te wartości są zwykle powiązane z kontem Campaign Managera 360, gdy źródłem jest Przesyłanie danych, lub z reklamodawcą Campaign Managera 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 z zespołem pomocy Campaign Managera 360, aby uzyskać więcej informacji.

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

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 jeden obiekt.EncryptionInfo Oznacza to, że wszystkie konwersje uwzględnione w danym żądaniu muszą pochodzić z tego samego źródła i korzystać z tego samego podmiotu szyfrującego.

Generowanie prośby o wstawienie

Ostatnim krokiem w tym procesie jest przesłanie konwersji za pomocą wywołania funkcji batchinsert. Ta metoda przyjmuje 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=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 Twoim żądaniu z najwyższą starannością, a nie wstawić całą partię jako transakcję typu „wszystko albo nic”. Jeśli nie uda się wstawić niektórych konwersji w partii, inne mogą zostać wstawione. Dlatego zalecamy sprawdzenie zwróconego 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 powiodła się.

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 wygenerowanie raportu Wyświetlenia Floodlight. W przeciwieństwie do innych raportów 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 o wyświetleniach Floodlight nie będą odzwierciedlać konwersji przesłanych ponad 28 dni po sygnaturze czasowej.