Загрузка конверсий

В этом руководстве приведены подробные инструкции по загрузке офлайн-конверсий с помощью сервиса Conversions Campaign Manager 360 API. Прежде чем продолжить, рекомендуем ознакомиться с общими сведениями об офлайн-конверсиях и основными понятиями, которые используются в этом руководстве.

Настройка ресурсов конверсий

Первый шаг в процессе загрузки конверсий – создание одного или нескольких объектов ресурсов Conversion. Каждый из этих объектов представляет одно событие-конверсию и содержит несколько обязательных полей:

Поле Описание
floodlightActivityId Действие Floodlight, с которым будет связана эта конверсия.
floodlightConfigurationId Конфигурация Floodlight, используемая указанным действием.
ordinal Это значение определяет, будут ли дедуплицироваться конверсии, совершенные на одном устройстве или одним пользователем в течение дня. Дополнительную информацию можно найти в разделе часто задаваемых вопросов.
timestampMicros Временная метка конверсии в микросекундах с начала эпохи Unix.

Кроме того, каждый объект должен содержать одно из следующих полей:

Поле Описание
encryptedUserId Один зашифрованный идентификатор пользователя, полученный с помощью макроса сопоставления%m или передачи данных.
encryptedUserIdCandidates[] Список зашифрованных идентификаторов пользователей, полученных с помощью макроса сопоставления%m или передачи данных. Будет использован первый из этих идентификаторов, для которого зарегистрирован показ Floodlight до указанного значения timestampMicros. Если ни один из идентификаторов не соответствует существующему показу, будет возвращена ошибка.
dclid Идентификатор клика в КМС, созданный Менеджером кампаний 360 или Дисплеем и Видео 360.
gclid Идентификатор клика Google, созданный Google Рекламой или Поисковой рекламой 360.
matchId Уникальный идентификатор, созданный рекламодателем, который передается в Менеджер кампаний 360 тегом Floodlight.
mobileDeviceId Незашифрованный мобильный идентификатор в формате IDFA или AdID или рекламный идентификатор (IFA) подключенного телевизора с поддерживаемой платформой (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio).

Наконец, у каждой конверсии есть два показателя:

Поле Описание
quantity Обязательно. Количество товаров, связанных с конверсией. Чтобы конверсия учитывалась в некоторых показателях (например, "Всего конверсий"), значение должно быть не меньше 1.
value Денежная ценность конверсии. Интерпретируется в валюте рекламодателя, указанной в настройках Floodlight.

Необязательные поля описаны в справочной документации.

В примере ниже показано, как создать простой объект ресурса конверсии.

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
)

Укажите информацию о шифровании

Если вы планируете атрибутировать офлайн-конверсии зашифрованным идентификаторам пользователей, как в предыдущем примере, вам нужно будет предоставить некоторые сведения о том, как они зашифрованы, в рамках запроса на вставку. В частности, вам нужно знать:

  1. Источник шифрования, который описывает, откуда поступила партия зашифрованных идентификаторов. Допустимые значения: AD_SERVING для идентификаторов, полученных с помощью макроса %m, или DATA_TRANSFER для идентификаторов, полученных из файлов передачи данных.

  2. Объект шифрования – уникальный набор значений, используемый для шифрования идентификаторов пользователей. Обычно эти значения относятся к аккаунту Менеджера кампаний 360, если источником является передача данных, или к рекламодателю Менеджера кампаний 360, если источником является макрос %m, но так бывает не всегда. Если вы не уверены, обратитесь к специалисту по работе с аккаунтом Менеджера кампаний 360 или в службу поддержки Менеджера кампаний 360.

При необходимости создайте объект EncryptionInfo, в котором будут указаны эти значения. Это второй шаг в процессе загрузки конверсий.

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

Обратите внимание, что каждый запрос на вставку может содержать только один объект EncryptionInfo. Это означает, что все конверсии, включенные в запрос, должны поступать из одного источника и использовать один и тот же объект шифрования.

Создание запроса на вставку

Последний шаг – загрузка конверсий с помощью вызова batchinsert. Этот метод принимает объект ConversionsBatchInsertRequest, который объединяет набор конверсий, подлежащих загрузке, с соответствующей информацией о шифровании (при необходимости):

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)

Обратите внимание, что Менеджер кампаний 360 пытается вставить каждую конверсию из вашего запроса по мере возможности, а не весь пакет сразу. Если некоторые конверсии в пакете не удается вставить, другие могут быть вставлены успешно. Поэтому рекомендуется проверять возвращаемый объект ConversionsBatchInsertResponse, чтобы определить статус каждой конверсии.

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

Поле status ответа будет содержать объект ConversionStatus для каждой конверсии, включенной в исходный запрос. Если вас интересуют только конверсии, которые не удалось добавить, то с помощью поля hasFailures можно быстро определить, не была ли добавлена какая-либо конверсия из указанного пакета. Инструкции по устранению каждого кода ошибки и повторной загрузке неудачных конверсий (INTERNAL и NOT_FOUND) приведены в разделе часто задаваемых вопросов.

Как проверить, были ли обработаны конверсии

Загруженные конверсии обычно обрабатываются и становятся доступны для отчетов в течение 24 часов. Чтобы проверить, были ли обработаны загруженные вами конверсии, рекомендуется создать отчет Показы Floodlight. В отличие от других отчетов об атрибуции, в этих отчетах по умолчанию будут представлены как атрибутированные (связанные с объявлением), так и неатрибутированные конверсии. Это позволяет быстро проверить, поступили ли в Менеджер кампаний 360 отправленные вами конверсии.