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

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

Прежде чем начать

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

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

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

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

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

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

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

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

encryptedUserId или gclid или dclid или matchid или mobileDeviceId

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

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

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

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

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

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

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

Приведенный ниже пример иллюстрирует создание простого объекта ресурса преобразования для редактирования:

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

Руби 

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

Руби 

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

Руби 

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

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

Руби 

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