コンバージョンを編集

このガイドでは、キャンペーン マネージャー 360 API の Conversions サービスを使用してコンバージョンを編集する手順について詳しく説明します。先に進む前に、概要でオフライン コンバージョンの概要を確認し、このガイドで説明するコンセプトを理解しておくことをおすすめします。

始める前に

この編集ワークフローを使用すると、既存のオンライン コンバージョンとオフライン コンバージョンの quantity と value を変更できます。そのためには、編集するコンバージョンを一意に識別する値を指定する必要があります。編集するコンバージョンの種類に応じて、これらの値は異なる方法で取得されます。

  • オンライン コンバージョンを識別するために必要な値は、Data Transfer から取得できます。

  • オフライン コンバージョンの特定に必要な値は、成功した batchinsert リクエストの ConversionsBatchInsertResponse で返されます。

いずれかのタイプのコンバージョンの編集が完了すると、ConversionsBatchUpdateResponse には、後続の編集を実行するために必要な値が含まれます。

コンバージョン リソースを構成する

編集ワークフローの最初のステップでは、1 つ以上の Conversion リソース オブジェクトを作成します。

次のフィールドは、編集するコンバージョンを識別するために使用されます。これらのフィールドは必須であり、既存のコンバージョンと完全に一致している必要があります。

フィールド 説明

encryptedUserId、gclid、dclid、matchid、または mobileDeviceId

 コンバージョン生成時の、暗号化されたユーザー ID、Google クリック ID、ディスプレイ クリック ID、照合用のウェブ商品アイテム ID、またはモバイル デバイス ID。
floodlightActivityId コンバージョンが関連付けられている Floodlight アクティビティ。
floodlightConfigurationId 指定されたアクティビティで使用される Floodlight 設定。
ordinal コンバージョンに関連付けられている重複除去 ID。
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

暗号化情報を指定する

編集するコンバージョンが暗号化されたユーザー ID に関連付けられている場合は、編集リクエストの一部として、暗号化の方法に関する詳細を指定する必要があります。詳しくは、コンバージョンのアップロード ガイドをご覧ください。

必要に応じて、これらの値を指定する EncryptionInfo オブジェクトを作成することが、編集ワークフローの 2 番目のステップです。

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）については、よくある質問をご覧ください。