Редактировать конверсии

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

Подготовка

Этот рабочий процесс позволяет изменять quantity и value существующих онлайн- и офлайн-конверсий. Для этого вам нужно будет указать значения, которые однозначно идентифицируют конверсии, которые нужно изменить. В зависимости от типа конверсий, которые вы редактируете, вы получите эти значения разными способами:

  • Значения, необходимые для идентификации онлайн-конверсий, можно получить с помощью функции передачи данных.

  • Значения, необходимые для идентификации офлайн-конверсий, возвращаются в ConversionsBatchInsertResponse успешных запросов batchinsert.

После того как вы измените конверсию любого типа, ConversionsBatchUpdateResponse будет содержать значения, необходимые для последующих изменений.

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

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

Для идентификации конверсии, которую нужно изменить, используются следующие поля: Эти поля обязательны и должны точно соответствовать существующей конверсии.

Поле Описание

encryptedUserId, gclid, dclid, matchid или mobileDeviceId

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

Ниже перечислены поля, которые можно редактировать.

Эти поля обязательны для заполнения. Указанные в них значения заменят все существующие значения для редактируемой конверсии.

Поле Описание
quantity Количество товаров, связанных с конверсией.
value Сумма дохода, полученного от конверсии.

Эти поля необязательны. Если значение не задано, оно останется без изменений.

Поле Описание
customVariables Пользовательские переменные Floodlight для конверсии. Если переменная задана, значение будет обновлено или вставлено. Если значение не задано, оно не меняется.

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

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

C#

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Construct the conversion object with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = conversionOrdinal;
conversion.TimestampMicros = conversionTimestamp;

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.Quantity = newQuantity;
conversion.Value = newValue;

Java

// Create a conversion object populated with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(ordinal);
conversion.setTimestampMicros(timestampMicros);

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.setQuantity(newQuantity);
conversion.setValue(newValue);

PHP

// 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();

// Create a conversion object with values that identify the conversion to
// update.
$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($values['ordinal']);
$conversion->setTimestampMicros($values['timestamp']);

// Set the fields to be updated. These fields are required; to preserve a
// value from the existing conversion, it must be copied over manually.
$conversion->setQuantity($values['new_quantity']);
$conversion->setValue($values['new_value']);

Python

# Construct the conversion object with values that identify the conversion
# to update.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': ordinal,
    'timestampMicros': timestamp
}

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion['quantity'] = new_quantity
conversion['value'] = new_value

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  existing_conversion[:floodlight_activity_id])
floodlight_config_id = floodlight_activity.floodlight_configuration_id

# Construct the conversion with values that identify the conversion to
# update.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: existing_conversion[:encrypted_user_id],
  floodlight_activity_id: existing_conversion[:floodlight_activity_id],
  floodlight_configuration_id: floodlight_config_id,
  ordinal: existing_conversion[:ordinal],
  timestamp_micros: existing_conversion[:timestamp]
)

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion.quantity = new_quantity
conversion.value = new_value

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

Если редактируемые конверсии связаны с зашифрованными идентификаторами пользователей, в запросе на изменение нужно указать, как они зашифрованы. Подробную информацию вы найдете в руководстве по загрузке конверсий.

При необходимости создание объекта 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]
)

Как создать запрос на обновление

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

C#

// Insert the conversion.
ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchUpdateResponse response =
    service.Conversions.Batchupdate(request, profileId).Execute();

Java

ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchUpdateResponse response = reporting.conversions()
    .batchupdate(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchUpdateRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchupdate(
    $values['user_profile_id'],
    $batch
);

Python

# Update the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchupdate(
    profileId=profile_id, body=request_body)
response = request.execute()

Ruby

# Construct the batch update request.
batch_update_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchUpdateRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Update the conversion.
result = service.batchupdate_conversion(profile_id, batch_update_request)

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

C#

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully updated conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) updating 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 updated conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) updating 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 updated conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) updating 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 updated conversion for encrypted user ID %s.' %
        encrypted_user_id)
else:
  print('Error(s) updating 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) updating conversion for encrypted user ID %s.',
    existing_conversion[: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 updated conversion for encrypted user ID %s.',
    existing_conversion[:encrypted_user_id])
end

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