このページは Cloud Translation API によって翻訳されました。

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

このガイドでは、キャンペーンマネージャー 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 をサポートしていないので注意してください。

最後に、コンバージョンには 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=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
}

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 にオフラインコンバージョンを関連付ける場合は、挿入リクエストの一部として暗号化方法の詳細を指定する必要があります。特に、次の情報が必要です。

暗号化ソース: 暗号化された一連の ID がどこから取得されたものかを示します。可能な値は、AD_SERVING（%m 一致マクロをソースとする ID の場合）または DATA_TRANSFER（Data Transfer ファイルをソースとする ID の場合）です。
暗号化エンティティ: ユーザー ID の暗号化に使用する値の固有のセットです。通常、キャンペーンマネージャー 360 アカウント（Data Transfer がソースの場合）またはキャンペーンマネージャー 360 広告主（%m マクロがソースの場合）に関連する値ですが、そうでない場合もあります。ご不明な点があれば、詳細についてキャンペーンマネージャー 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=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 オブジェクトが 1 つずつ含まれます。挿入できなかったコンバージョンのみを確認したい場合は、hasFailures フィールドを使用すれば、指定したバッチ内に失敗したコンバージョンがあるかどうかをすぐに確認できます。

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

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

コンバージョンのアップロード コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

C#

Java

PHP

Python

Ruby

暗号化情報を指定する

C#

Java

PHP

Python

Ruby

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

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

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

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

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