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

В этом руководстве представлены подробные инструкции по загрузке данных о конверсиях в офлайн-режиме с помощью сервиса 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). Обратите внимание, что Google не поддерживает идентификаторы YouTube Connected TV IFA.

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

Поле	Описание
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 дней после их отметки времени.