Prześlij konwersje

Ten przewodnik zawiera szczegółowe instrukcje przesyłania konwersji offline za pomocą usługi Campaign Manager 360 API Conversions. Zanim przejdziesz dalej, zalecamy przeczytanie omówienia, aby zapoznać się z konwersjami offline i pojęciami opisanymi w tym przewodniku.

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ą zostanie 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 ciągu tego samego dnia. 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 za pomocą makra dopasowania%m lub Przenoszenia danych. Użyty zostanie pierwszy z tych identyfikatorów, który został zarejestrowany przez Floodlight przed określonym czasem (timestampMicros). Jeśli żaden z identyfikatorów nie pasuje do istniejącego elementu, pojawi się 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 2 rodzaje danych:

Pole Opis
quantity Wymagane. Liczba elementów powiązanych z konwersją. Musi wynosić co najmniej 1, aby konwersja była uwzględniana w niektórych rodzajach danych (np. Łączna liczba konwersji).
value Kwota w dolarach powiązana z konwersją. Interpretowane w walucie reklamodawcy, który jest właścicielem konfiguracji Floodlight.

Pola opcjonalne są opisane w dokumentacji referencyjnej.

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
)

Podaj informacje o szyfrowaniu

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

  1. Źródło szyfrowania, które opisuje, skąd pochodzi grupa 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 szyfrujący, czyli unikalny zestaw wartości używany do szyfrowania identyfikatorów użytkowników. Te wartości zwykle odnoszą się do konta Campaign Managera 360, gdy źródłem jest Przenoszenie danych, lub do reklamodawcy Campaign Managera 360, gdy źródłem jest makro %m, ale nie zawsze tak jest. Jeśli nie masz pewności, skontaktuj się z opiekunem klienta Campaign Managera 360 lub z zespołem pomocy Campaign Managera 360, aby uzyskać więcej 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 uwzględnione w danym żądaniu muszą pochodzić z tego samego źródła i używać tego samego podmiotu szyfrującego.

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 z nimi 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ę z żądania, dokładając wszelkich starań, a nie wstawia całej partii jako transakcji „wszystko albo nic”. Jeśli nie uda się wstawić niektórych konwersji z partii, inne mogą zostać wstawione prawidłowo. Dlatego zalecamy sprawdzenie zwróconego obiektu 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 odpowiedzi 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 któraś konwersja w podanej partii nie została wstawiona. Wskazówki dotyczące postępowania w przypadku poszczególnych kodów błędów i ponownego przesyłania nieudanych konwersji (INTERNAL i NOT_FOUND) znajdziesz w najczęstszych pytaniach.

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 idealnie nadaje się do szybkiego sprawdzania, czy wysłane konwersje dotarły do Campaign Managera 360.