コンバージョンを編集する

このガイドでは、キャンペーンマネージャー 360 API Conversions サービスを使用してコンバージョンを編集する手順について詳しく説明します。以下をご覧になる前に、オフラインコンバージョンの基本について紹介している概要をご確認になり、このガイドで説明する概念について理解しておくことをおすすめします。

はじめに

編集ワークフローでは、既存のオンラインコンバージョンやオフラインコンバージョンの quantity と value を編集できます。編集を行うには、対象のコンバージョンを一意に識別する値を指定する必要があります。編集するコンバージョンのタイプに応じて、次のいずれかの方法で値を取得します。

オンラインコンバージョンを識別するために必要な値は、Data Transfer から取得できます。
オフラインコンバージョンを識別するために必要な値は、成功した batchinsert リクエストの ConversionsBatchInsertResponse で返されます。

いずれのタイプのコンバージョンであれ、編集が正常に完了すると、その後の編集を行う際に必要な値が ConversionsBatchUpdateResponse に格納されます。

コンバージョンリソースを設定する

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

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

フィールド	説明
`encryptedUserId`、`gclid`、`dclicd`、`matchid`、または `mobileDeviceId`	コンバージョン生成時の、暗号化されたユーザー ID、Google クリック ID、ディスプレイクリック ID、マッチ ID、またはモバイルデバイス ID。 `encryptedUserIdCandidates` フィールドは編集には使用できません。
`floodlightActivityId`	コンバージョンが関連付けられている Floodlight アクティビティ。
`floodlightConfigurationId`	指定したアクティビティで使用される Floodlight 設定。
`ordinal`	コンバージョンに関連付けられている重複除去識別子。
`timestampMicros`	コンバージョンのタイムスタンプ（Unix エポックからのマイクロ秒数）。

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

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

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

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

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

コンバージョンを編集する

はじめに

コンバージョン リソースを設定する

C#

Java

PHP

Python

Ruby

暗号化情報を指定する

C#

Java

PHP

Python

Ruby

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

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

コンバージョンリソースを設定する