Prześlij konwersje

W tym przewodniku znajdziesz szczegółowe instrukcje przesyłania konwersji offline za pomocą interfejsu Campaign Manager 360 API Conversions. Zanim przejdziesz dalej, przeczytaj omówienie, aby zapoznać się z konwersjami offline i pojęciami omówionymi w tym przewodniku.

Uwaga: interfejs API obsługuje konwersje offline w przypadku Campaign Managera 360 i Display & Video 360, ale dane koszyka nie są dostępne w żadnym 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żde 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ść służąca do określania 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 makry dopasowywania%m lub raportu Przenoszenie danych;
encryptedUserIdCandidates[]	Lista zaszyfrowanych identyfikatorów użytkowników uzyskanych z makra dopasowywania%m lub funkcji Przenoszenie danych. Użyty zostanie pierwszy z tych identyfikatorów, który ma zarejestrowaną ekspozycję 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 w kampanii 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 usługi Campaign Manager 360 za pomocą tagu Floodlight.
mobileDeviceId	niezaszyfrowany identyfikator urządzenia mobilnego w formacie IDFA lub AdID albo identyfikator wyświetlania reklam na urządzeniach CTV (IFA) z obsługiwanej platformy CTV (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Pamiętaj, że Google nie obsługuje IFA na urządzeniach CTV.

Na koniec każda konwersja ma 2 rodzaje danych:

Pole	Opis
quantity	Wymagany. Liczba elementów powiązanych z konwersją. Aby konwersja mogła być uwzględniana w przypadku niektórych danych (np. łącznej liczby konwersji), musi wynosić co najmniej 1.
value	Kwota w USD powiązana z konwersją. Interpretowana w konfiguracji Floodlight z walutą reklamodawcy.

Opcjonalne pola są opisane w dokumentacji referencyjnej.

Przykład poniżej pokazuje tworzenie prostego obiektu 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
)

Określ informacje o szyfrowaniu

Uwaga: ta sekcja ma zastosowanie tylko w przypadku przesyłania konwersji, które zawierają tagi encryptedUserId lub encryptedUserIdCandidates[].

Jeśli zamierzasz przypisywać konwersje offline do zaszyfrowanych identyfikatorów użytkowników, jak w poprzednim przykładzie, musisz podać szczegóły dotyczące sposobu ich zaszyfrowania w ramach żądania wstawiania. Musisz wiedzieć:

1. Źródło szyfrowania, które określa, skąd pochodzi grupa 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. element szyfrowania, czyli unikalny zestaw wartości służących do szyfrowania identyfikatorów użytkowników; Te wartości zwykle odnoszą się do konta Campaign Managera 360, gdy źródło to Przesyłanie danych, lub do reklamodawcy w usłudze Campaign Manager 360, gdy źródło to 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 wstawiania 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 elementu szyfrowania.

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 wstawiać każdą konwersję z Twojego żądania z największą starannością, a nie wstawiać całej partii jako transakcji typu „wszystko albo nic”. Jeśli nie uda się wstawić niektórych konwersji z partii, inne mogą zostać zaimportowane. Dlatego zalecamy sprawdzenie zwróconego parametru 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

Jak widać powyżej, pole status w odpowiedzi 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 z podanej partii nie została wstawiona.

Sprawdzanie, czy konwersje zostały przetworzone

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

Uwaga: testy weryfikacyjne należy przeprowadzać na podstawie ostatnich konwersji. Raporty o wyświetleniach Floodlight nie uwzględniają konwersji przesłanych później niż 28 dni po ich sygnaturze czasowej.