コンバージョンを編集

このガイドでは、キャンペーン マネージャー 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 コンバージョンに関連付けられている重複除去識別子。
timestampMicros コンバージョンのタイムスタンプ（Unix エポックからのマイクロ秒数）。

編集可能なフィールドは次のとおりです。

これらのフィールドは必須で、指定した値によって編集中のコンバージョンの値が上書きされます。

フィールド 説明
quantity コンバージョンに関連付けられたアイテムの数。
value コンバージョンによって得られた収益額。

このフィールドは省略可能です。設定しない場合、値は変更されません。

フィールド 説明
customVariables コンバージョンのカスタム Floodlight 変数。変数が設定されている場合は、値を更新または挿入します。設定されていない場合、変数の値は変更されません。

リファレンス ドキュメントに記載されているその他すべてのフィールドは、サポートされていないため変更できません。サポートされていないフィールドを編集リクエストに含めるとエラーになります。編集中のコンバージョンにサポートされていないフィールドの値が含まれている場合、それらの値は自動的に保持されます。

次の例では、後ほど編集する単純なコンバージョン リソース オブジェクトを作成しています。

C#JavaPHPPythonRuby
// 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;
// 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);
// 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']);
# 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

暗号化情報を指定する

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

必要であれば、暗号化方法の値を指定する EncryptionInfo オブジェクトを作成します。これが編集ワークフローの 2 つ目のステップになります。

C#JavaPHPPythonRuby
// 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);
$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]
)

更新リクエストを生成する

編集ワークフローの最後のステップとして、batchupdate を呼び出してコンバージョンを編集します。このメソッドに渡す ConversionsBatchUpdateRequest オブジェクトには、編集するコンバージョンのセットを指定します。必要であれば、各コンバージョンに関連付けられた暗号化情報も含めます。

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

ConversionsBatchUpdateResponse response =
    service.Conversions.Batchupdate(request, profileId).Execute();
ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchUpdateResponse response = reporting.conversions()
    .batchupdate(profileId, request).execute();
$batch = new Google_Service_Dfareporting_ConversionsBatchUpdateRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchupdate(
    $values['user_profile_id'],
    $batch
);
# 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)

キャンペーン マネージャー 360 は、バッチ全体をオール オア ナッシング トランザクションとして編集するのではなく、ベスト エフォートを基本として各コンバージョンの編集を試みます。バッチ内のコンバージョンの一部を編集できなくても、それ以外のコンバージョンは正常に編集できる場合があります。したがって、返された ConversionsBatchUpdateResponse を調べて、各コンバージョンのステータスを確認することをおすすめします。

C#JavaPHPPythonRuby
// 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);
  }
}
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());
  }
}
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());
    }
}
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 オブジェクトが 1 つずつ含まれます。更新できなかったコンバージョンのみを確認したい場合は、hasFailures フィールドを使用すれば、指定したバッチ内に失敗したコンバージョンがあるかどうかをすぐに確認できます。