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

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

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

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

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

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

フィールド 説明
encryptedUserId %m マッチ マクロまたは Data Transfer から取得した、暗号化された単一のユーザー ID。
encryptedUserIdCandidates[] %m マッチ マクロまたは Data Transfer から取得した、暗号化されたユーザー 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)。

最後に、各コンバージョンには次の 2 つの指標があります。

フィールド 説明
quantity 必須。コンバージョンに関連付けられたアイテムの数。コンバージョンが特定の指標(合計コンバージョン数など)にカウントされるには、1 以上にする必要があります。
value コンバージョンに関連付けられた金額。Floodlight 設定を所有する広告主の通貨で解釈されます。

オプション フィールドについては、リファレンス ドキュメントをご覧ください。

次の例は、シンプルなコンバージョン リソース オブジェクトの作成を示しています。

C#

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

Java

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

PHP

$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);

Python

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = (
    service.floodlightActivities()
    .get(profileId=str(profile_id), id=str(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
}

Ruby

# 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 のバッチの取得元を示します。有効な値は、%m 一致マクロから取得された ID の場合は AD_SERVING、Data Transfer ファイルから取得された ID の場合は DATA_TRANSFER です。

  2. 暗号化エンティティ。ユーザー ID の暗号化に使用される一意の値のセットです。通常、これらの値は、ソースが Data Transfer の場合はキャンペーン マネージャー 360 アカウントに関連付けられ、ソースが %m マクロの場合はキャンペーン マネージャー 360 広告主に関連付けられますが、必ずしもそうとは限りません。不明な点がある場合は、キャンペーン マネージャー 360 のアカウント担当者またはキャンペーン マネージャー 360 のサポートにお問い合わせください。

必要に応じて、これらの値を指定する 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]
)

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

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

このプロセスの最後のステップは、batchinsert を呼び出してコンバージョンをアップロードすることです。このメソッドは、アップロードするコンバージョンのセットと、関連する暗号化情報(必要な場合)を組み合わせた ConversionsBatchInsertRequest オブジェクトを受け入れます。

C#

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

ConversionsBatchInsertResponse response =
    service.Conversions.Batchinsert(request, profileId).Execute();

Java

ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchInsertResponse response = reporting.conversions()
    .batchinsert(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchInsertRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchinsert(
    $values['user_profile_id'],
    $batch
);

Python

# Insert the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchinsert(
    profileId=str(profile_id), body=request_body
)
response = request.execute()

Ruby

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

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

Java

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

PHP

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

Python

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']))

Ruby

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 オブジェクトが含まれます。挿入に失敗したコンバージョンのみに関心がある場合は、hasFailures フィールドを使用して、指定されたバッチ内のコンバージョンが失敗したかどうかをすばやく判断できます。各エラーコードの処理方法と、失敗したコンバージョンの再試行方法(INTERNAL と NOT_FOUND)については、よくある質問をご覧ください。

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

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