コンバージョンのアップロード

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

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

コンバージョンをアップロードするプロセスの最初のステップは、1 つ以上の Conversion リソース オブジェクトの作成です。このオブジェクトはそれぞれ、単一のコンバージョン イベントを表し、以下の必須フィールドが含まれています。

フィールド 説明
floodlightActivityId このコンバージョンを関連付ける Floodlight アクティビティ。
floodlightConfigurationId 指定したアクティビティで使用される Floodlight 設定。
ordinal 同じデバイスまたはユーザーによる同日のコンバージョンの重複除去の方法を制御するために使用する値。詳しくは、よくある質問をご覧ください。
timestampMicros コンバージョンのタイムスタンプ（Unix エポックからのマイクロ秒数）。

また、各オブジェクトには次のフィールドのいずれか 1 つが含まれている必要があります。

フィールド 説明
encryptedUserId %m 一致マクロまたは Data Transfer から取得した、単一の暗号化ユーザー ID。
encryptedUserIdCandidates[] %m 一致マクロまたは Data Transfer から取得した複数の暗号化ユーザー ID のリスト。リスト内の ID のうち、指定の timestampMicros の前に Floodlight 露出が記録された最初の ID が使用されます。既存の露出と一致する ID が存在しない場合は、エラーが発生します。
dclid キャンペーン マネージャー 360 またはディスプレイ＆ビデオ 360 で生成されたディスプレイ広告のクリック ID。
gclid Google 広告または検索広告 360 で生成された Google クリック ID。
matchId Floodlight タグを通じてキャンペーン マネージャー 360 に渡された、広告主が作成した固有の ID。
mobileDeviceId IDFA または AdID 形式の暗号化されていないモバイル ID、またはサポートされているコネクテッド テレビ デバイス プラットフォーム（Roku、Fire TV、Android TV、Apple TV、Xbox、Samsung、Vizio）のコネクテッド テレビ広告識別子（IFA）。Google では YouTube コネクテッド テレビの IFA をサポートしていないので注意してください。

オプション フィールドについては、リファレンス ドキュメントをご覧ください。数量フィールドは省略できますが、レポート実行時にコンバージョンが特定の指標（合計コンバージョン数など）でカウントされるようにするには、1 以上を指定する必要があります。

下記の例では、シンプルなコンバージョン リソース オブジェクトの作成方法を示します。

C#JavaPHPPythonRuby
// Generate a timestamp in milliseconds since Unix epoch.
TimeSpan timeSpan = DateTime.UtcNow - new DateTime(1970, 1, 1);
long currentTimeInMilliseconds = (long) timeSpan.TotalMilliseconds;

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

// Create the conversion.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = currentTimeInMilliseconds.ToString();
conversion.TimestampMicros = currentTimeInMilliseconds * 1000;
long currentTimeInMilliseconds = System.currentTimeMillis();

// Find Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity = reporting.floodlightActivities()
    .get(profileId, floodlightActivityId).execute();
long floodlightConfigurationId = floodlightActivity.getFloodlightConfigurationId();

Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(String.valueOf(currentTimeInMilliseconds));
conversion.setTimestampMicros(currentTimeInMilliseconds * 1000);
$currentTimeInMicros = time() * 1000 * 1000;

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

$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($currentTimeInMicros);
$conversion->setTimestampMicros($currentTimeInMicros);
# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.floodlightActivities().get(
    profileId=profile_id, id=floodlight_activity_id).execute()
floodlight_config_id = floodlight_activity['floodlightConfigurationId']

current_time_in_micros = int(time.time() * 1000000)

# Construct the conversion.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': current_time_in_micros,
    'timestampMicros': current_time_in_micros
}
# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  floodlight_activity_id)
floodlight_config_id = floodlight_activity.floodlight_configuration_id

current_time_in_micros = DateTime.now.strftime('%Q').to_i * 1000

# Construct the conversion.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: encrypted_user_id,
  floodlight_activity_id: floodlight_activity_id,
  floodlight_configuration_id: floodlight_config_id,
  ordinal: current_time_in_micros,
  timestamp_micros: current_time_in_micros
)

暗号化情報を指定する

上記の例のように、暗号化されたユーザー ID にオフライン コンバージョンを関連付ける場合は、挿入リクエストの一部として暗号化方法の詳細を指定する必要があります。特に、次の情報が必要です。

  1. 暗号化ソース: 暗号化された一連の ID がどこから取得されたものかを示します。可能な値は、AD_SERVING（%m 一致マクロをソースとする ID の場合）または DATA_TRANSFER（Data Transfer ファイルをソースとする ID の場合）です。

  2. 暗号化エンティティ: ユーザー ID の暗号化に使用する値の固有のセットです。通常、キャンペーン マネージャー 360 アカウント（Data Transfer がソースの場合）またはキャンペーン マネージャー 360 広告主（%m マクロがソースの場合）に関連する値ですが、そうでない場合もあります。ご不明な点があれば、詳細についてキャンペーン マネージャー 360 アカウント担当者またはキャンペーン マネージャー 360 サポートにお問い合わせください。

必要であれば、これらの値を指定する 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]
)

個々の挿入リクエストに含めることができる EncryptionInfo オブジェクトは 1 つだけです。つまり、あるリクエストに含まれるコンバージョンはすべて、同じソースから取得されたもので、同じ暗号化エンティティを使用している必要があります。

挿入リクエストを生成する

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

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

ConversionsBatchInsertResponse response =
    service.Conversions.Batchinsert(request, profileId).Execute();
ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchInsertResponse response = reporting.conversions()
    .batchinsert(profileId, request).execute();
$batch = new Google_Service_Dfareporting_ConversionsBatchInsertRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchinsert(
    $values['user_profile_id'],
    $batch
);
# Insert the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchinsert(profileId=profile_id,
                                            body=request_body)
response = request.execute()
# Construct the batch insert request.
batch_insert_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchInsertRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Insert the conversion.
result = service.batchinsert_conversion(profile_id, batch_insert_request)

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

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

上記のように、レスポンスの status フィールドには、元のリクエスト内のコンバージョンごとに ConversionStatus オブジェクトが 1 つずつ含まれます。挿入できなかったコンバージョンのみを確認したい場合は、hasFailures フィールドを使用すれば、指定したバッチ内に失敗したコンバージョンがあるかどうかをすぐに確認できます。

コンバージョンが処理されたことを確認する

アップロードしたコンバージョンは通常 24 時間以内に処理され、レポートに使用できます。アップロードしたコンバージョンが処理されたかどうかを確認するには、Floodlight インプレッション数レポートを実行することをおすすめします。他のアトリビューション レポートとは異なり、このレポートでは、アトリビューションありの（広告に関連付けられた）コンバージョンとアトリビューションなしのコンバージョンの両方がデフォルトで返されます。キャンペーン マネージャー 360 に送信したコンバージョンが処理されたかどうかを確認するには最適です。