このガイドでは、キャンペーン マネージャー 360 API Conversions
サービスを使用してオフライン コンバージョンをアップロードする手順について詳しく説明します。先に進む前に、概要でオフライン コンバージョンの概要を確認し、このガイドで説明するコンセプトを理解しておくことをおすすめします。
コンバージョン リソースを設定する
コンバージョン アップロード プロセスの最初のステップは、1 つ以上の Conversion
リソース オブジェクトの作成です。各オブジェクトは 1 つのコンバージョン イベントを表し、いくつかの必須フィールドが含まれています。
Field | 説明 |
---|---|
floodlightActivityId |
このコンバージョンが関連付けられている Floodlight アクティビティ。 |
floodlightConfigurationId |
指定したアクティビティによって使用される Floodlight 設定。 |
ordinal |
同じデバイスまたは同じユーザーからのコンバージョンを、同じ日に重複除去する方法を管理するために使用される値。詳しくは、よくある質問をご覧ください。 |
timestampMicros |
コンバージョンのタイムスタンプ(UNIX エポックからのマイクロ秒単位)。 |
また、各オブジェクトには次のいずれかのフィールドが含まれている必要があります。
Field | 説明 |
---|---|
encryptedUserId |
%m 一致マクロまたは Data Transfer から取得した、暗号化された単一のユーザー ID。 |
encryptedUserIdCandidates[] |
%m 一致マクロまたは Data Transfer から取得した、暗号化されたユーザー ID のリストです。指定された ID のうち、記録されている Floodlight 露出がある最初の ID が使用されます。timestampMicros 既存の露出に一致する 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#
// 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 のバッチのソースです。%m 一致マクロをソースとする ID の場合は
AD_SERVING
、Data Transfer ファイルから取得した ID の場合はDATA_TRANSFER
を使用できます。暗号化エンティティ。ユーザー 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=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
コンバージョンが処理されたことを確認する
アップロードされたコンバージョンは通常処理され、24 時間以内にレポートが有効になります。アップロードしたコンバージョンが処理されたかどうかを確認するには、Floodlight インプレッション レポートを実行することをおすすめします。他のアトリビューション レポートとは異なり、デフォルトでは、広告に関連付けられたコンバージョンと、アトリビューションのないコンバージョンの両方を返します。そのため、送信したコンバージョンがキャンペーン マネージャー 360 に届いたかどうかを簡単に確認できます。