В этом руководстве приведены подробные инструкции по загрузке офлайн-конверсий с помощью службы API- Conversions
Менеджера кампаний 360. Прежде чем продолжить, рекомендуется просмотреть обзор , чтобы получить представление об офлайн-конверсиях и ознакомиться с понятиями, обсуждаемыми в этом руководстве.
Настроить ресурсы конверсии
Первым шагом в процессе загрузки конверсии является создание одного или нескольких объектов ресурсов Conversion
. Каждый из этих объектов представляет одно событие конверсии и содержит несколько обязательных полей:
Поле | Описание |
---|---|
floodlightActivityId | Действие Floodlight, с которым будет связана эта конверсия. |
floodlightConfigurationId | Конфигурация Floodlight, используемая указанным действием. |
ordinal | Значение, используемое для управления дедупликацией конверсий с одного и того же устройства или пользователя в один и тот же день. Дополнительную информацию см. в разделе часто задаваемых вопросов . |
timestampMicros | Временная метка преобразования в микросекундах с эпохи Unix. |
Кроме того, каждый объект должен содержать одно из следующих полей:
Поле | Описание |
---|---|
encryptedUserId | Один зашифрованный идентификатор пользователя, полученный из макроса соответствия %m или передачи данных . |
encryptedUserIdCandidates[] | Список зашифрованных идентификаторов пользователей, полученный из макроса соответствия %m или передачи данных . Будет использоваться первый из этих идентификаторов с зарегистрированным показом Floodlight до указанной timestampMicros . Если ни один из идентификаторов не соответствует существующей экспозиции, будет выдано сообщение об ошибке. |
dclid | Идентификатор клика в контекстно-медийной сети , созданный Менеджером кампаний 360 или Дисплеем и Видео 360. |
gclid | Идентификатор клика Google , созданный Google Ads или Search Ads 360. |
matchId | Созданный рекламодателем уникальный идентификатор передается в Менеджер кампаний 360 через тег Floodlight. |
mobileDeviceId | Незашифрованный мобильный идентификатор в формате IDFA или AdID или идентификатор подключенного телевидения для рекламы (IFA) с поддерживаемой платформы устройства CTV (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Обратите внимание, что Google не поддерживает IFA YouTube Connected TV. |
Необязательные поля описаны в справочной документации . Обратите внимание, что поле количества, хотя и необязательное, должно иметь значение не менее 1, чтобы конверсия учитывалась при подсчете определенных показателей (например, общего количества конверсий) при создании отчетов.
Пример ниже иллюстрирует создание простого объекта ресурса преобразования:
С#
// 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;
Джава
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);
Питон
# 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 }
Рубин
# 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 )
Укажите информацию о шифровании
Если вы планируете связывать офлайн-конверсии с зашифрованными идентификаторами пользователей, как в предыдущем примере, вам потребуется предоставить некоторые сведения о том, как они зашифрованы, как часть вашего запроса на вставку. В частности, вам необходимо знать:
Источник шифрования , описывающий источник пакета зашифрованных идентификаторов. Допустимые значения:
AD_SERVING
для идентификаторов, полученных из макроса соответствия %m, илиDATA_TRANSFER
для идентификаторов, полученных из файлов передачи данных.Сущность шифрования , представляющая собой уникальный набор значений, используемых для шифрования идентификаторов пользователей. Эти значения обычно относятся к учетной записи Менеджера кампаний 360, если источником является передача данных, или рекламодателем Менеджера кампаний 360, если источником является макрос %m, но это не всегда так. Если вы не уверены, обратитесь к представителю аккаунта Менеджера кампаний 360 или в службу поддержки Менеджера кампаний 360 для получения дополнительной информации.
При необходимости создание объекта EncryptionInfo
, в котором указаны эти значения, является вторым шагом в процессе загрузки конверсии:
С#
// Create the encryption info. EncryptionInfo encryptionInfo = new EncryptionInfo(); encryptionInfo.EncryptionEntityId = encryptionEntityId; encryptionInfo.EncryptionEntityType = encryptionEntityType; encryptionInfo.EncryptionSource = encryptionSource;
Джава
// 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']);
питон
# 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
, который объединяет набор конверсий для загрузки с соответствующей информацией о шифровании (при необходимости):
С#
// Insert the conversion. ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest(); request.Conversions = new List<Conversion>() { conversion }; request.EncryptionInfo = encryptionInfo; ConversionsBatchInsertResponse response = service.Conversions.Batchinsert(request, profileId).Execute();
Джава
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 );
Питон
# Insert the conversion. request_body = { 'conversions': [conversion], 'encryptionInfo': encryption_info } request = service.conversions().batchinsert(profileId=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)
Имейте в виду, что Менеджер кампаний 360 пытается вставить каждую конверсию в ваш запрос с максимальной эффективностью, а не вставлять весь пакет как транзакцию по принципу «все или ничего». Если некоторые преобразования в пакете не вставляются, другие могут быть вставлены успешно. Поэтому рекомендуется проверять возвращенный ConversionsBatchInsertResponse
, чтобы определить статус каждой конверсии:
С#
// 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); } }
Джава
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()); } }
питон
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 . В отличие от других отчетов атрибуции, они по умолчанию возвращают конверсии как с атрибуцией (связанные с рекламой), так и без атрибуции. Благодаря этому он идеально подходит для быстрой проверки того, были ли отправленные вами конверсии реализованы в Менеджере кампаний 360.