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

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

Примечание: Хотя API поддерживает офлайн-конверсии для Campaign Manager 360 и Display & Video 360, данные о корзине покупок недоступны для этих продуктов. Подробнее о данных о корзине покупок .

Настройка ресурсов преобразования

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

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

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

Поле	Описание
encryptedUserId	Единый зашифрованный идентификатор пользователя, полученный из макроса %m match или функции передачи данных .
encryptedUserIdCandidates[]	Список зашифрованных идентификаторов пользователей, полученных из макроса %m match или функции Data Transfer . Будет использован первый из этих идентификаторов, для которого была записана экспозиция Floodlight до указанной timestampMicros . Если ни один из идентификаторов не соответствует существующей экспозиции, будет выдана ошибка.
dclid	Идентификатор клика по рекламному объявлению, сгенерированный Campaign Manager 360 или Display & Video 360.
gclid	Идентификатор клика Google, генерируемый Google Ads или Search Ads 360.
matchId	Уникальный идентификатор, созданный рекламодателем, передается в Campaign Manager 360 через тег Floodlight.
mobileDeviceId	Незашифрованный мобильный идентификатор в формате IDFA или AdID, либо идентификатор Connected TV для рекламы (IFA) с поддерживаемой платформы устройства CTV (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
}

Руби

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

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

Примечание: Этот раздел применяется только при загрузке преобразований, содержащих encryptedUserId или encryptedUserIdCandidates[] .

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

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

2. Идентификатор шифрования — это уникальный набор значений, используемых для шифрования идентификаторов пользователей. Обычно эти значения относятся к учетной записи Campaign Manager 360, если источником является передача данных, или к рекламодателю Campaign Manager 360, если источником является макрос %m, но это не всегда так. Если вы не уверены, обратитесь к представителю вашей учетной записи Campaign Manager 360 или в службу поддержки Campaign Manager 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
}

Руби

# 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()

Руби

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

Обратите внимание, что Campaign Manager 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']))

Руби

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 можно использовать для быстрого определения того, была ли какая-либо конверсия в предоставленной партии неудачной.

Проверка обработки конверсий.

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

Примечание: Проверка достоверности данных должна проводиться с использованием недавних конверсий. Отчеты Floodlight Impressions не будут отражать конверсии, отправленные более чем через 28 дней после их отметки времени.