オーディエンス収集のパートナになる

オーディエンス収集は、Oracle Data Cloudプラットフォームと実行プラットフォームの間でオーディエンス・オブジェクトを自動的に作成およびマッピングする方法です。オーディエンス収集では、Oracle Data Cloudプラットフォームによってシステムが認証され、APIを使用してオーディエンス・オブジェクトが作成されます。APIによって、インジェクトされたオーディエンスの外部オーディエンスIDが返され、オーディエンス・オブジェクトにユーザーを追加できるように、プラットフォームによってこの外部オーディエンスIDが後続データに含められます。

オーディエンス収集によって、プラットフォーム間のオーディエンスの配信とアクティブ化が、共通のクライアントにとって迅速かつシームレスなセルフサービスのプロセスになることで、チームでセグメント・オブジェクトを手動でマッピングする必要がなくなります。

オーディエンス収集のワークフロー

前提条件

オーディエンス収集パートナになるには、次の要件を満たす必要があります。

• オーディエンスAPI: システムでオーディエンスを作成、検証および更新するPOST、GETおよびPUTメソッドをサポートし、一連のcURLコマンドに適切に応答できるRESTfulオーディエンスAPIが必要です。
• データ配信: サーバー・データ・トランスファー(SDT)またはJSONリターンを介してOracle Data Cloudプラットフォーム・データを受信できる必要があります。
• 認証: プラットフォームで、次のいずれかの方法を使用してシステムを認証できる必要があります。
  • OAuth 2.0認可コード付与タイプ
  • 存続時間(TTL)が延長されたアクセス・トークン
認証エンドポイントは次の構文に準拠する必要があります。
• https://your_authorization_provider_url.com/oauth2/authorize
• https://your_authorization_provider_url.com/oauth2/token

オーディエンス収集アプリを開発するには:

1. 認証およびオーディエンスのAPIドキュメントをOracle Data Cloudプラットフォーム・パートナ・マネージャに送信し、インテグレーションをレビューするための会議を設定します。
2. 提供されたcURLコマンドでオーディエンスAPIを検証し、結果をOracle Data Cloudプラットフォーム・パートナ・マネージャに送信します。
3. 認可サービス、オーディエンス・サービスおよびデータ配信方法を含むオーディエンス収集アプリを作成して、テストに備えて保存します。アプリを公開するには、Oracle Data CloudプラットフォームによってAPIが検証される必要があります。このことは、エンジニアリング・サポートがアプリのデバッグとトラブルシューティングを支援するための要件となります。
4. アプリをテストして、次のことを検証します。
   • オーディエンスがシステム内に作成されていること。
   • プラットフォームで外部オーディエンスIDが受信され、保存されていること。
   • データ配信によって、ユーザーが外部オーディエンスに追加されていること。
5. (推奨)インテグレーションをテストして検証し、かつ、クライアントがオーディエンスを見つけて使用する方法の文書化に役立てるために、システム内でOracle Data Cloudにテスト・シートを提供します。
6. Oracle Data Cloudを使用して、アプリの使用説明書を作成します。システム内でテスト・シートを提供しない場合は、使用説明書とスクリーンショットを提供して、クライアントにシステムでOracle Data Cloudオーディエンスを見つける方法を示す必要があります。
7. 2から4週間、1から3クライアントとのインテグレーションのベータ版テストを実施します。
8. アプリをOracle Data Cloudアプリ・カタログに公開します。これにより、すべてのクライアントでインテグレーションを使用できるようになります。
9. クライアントがアプリをそのDMPに追加すると、システムの資格証明を入力するプロバイダURLにリダイレクトされ、シートでオーディエンスを作成および構成するためのOracle Data Cloudへのアクセスを付与されます。
10. クライアントがオーディエンスを作成し、Oracle Data Cloudプラットフォームで配信します。プラットフォームでは、オーディエンス配信に対応するキャンペーンが作成されます。
    
11. プラットフォームによってオーディエンス作成APIがコールされ、クライアントのオーディエンスがシステム内のシートにインジェクトされます。
12. プラットフォームによって、クライアントのユーザー・データ(一意のユーザーID、外部オーディエンスID、カテゴリまたはキャンペーンID)がSDTまたはJSONリターンを経由してシステムに配信されます。

アプリの作成

アプリの作成プロセス中に、オーディエンス収集インテグレーションに必要なすべての情報(名前、説明、ロゴ、価格設定モデル、データ配信方法など)を提供します。このプロセスと要件の詳細は、アプリの開発を参照してください。

オーディエンス収集アプリに関して、次の情報を提供する必要があります。

• 収集方法(直接または間接)
• 認証サービス
• オーディエンス・オブジェクトのJSONスキーマ
• オーディエンスAPI

収集方法

Oracle Data Cloudのオーディエンスがシステム内のクライアント・シートに渡される方法を選択します。

• 直接収集: Oracle Data Cloudプラットフォームによって、アプリ・パートナのプラットフォーム内のクライアントのシートに直接オーディエンス・オブジェクトが作成されます。
• 間接収集: Oracle Data Cloudプラットフォームによって、アプリ・パートナのプラットフォームでオーディエンス・オブジェクトが作成され、クライアントがアプリをインストールしたときに指定したシステムのアカウント識別子に基づいてオーディエンス・オブジェクトがプロビジョニングされます。間接収集を使用する場合は、テスト広告主ID、アカウントID、クライアントIDまたは間接オーディエンス収集インテグレーションの検証に使用できるその他のIDを提供する必要があります。

認証サービス

Oracle Data Cloudプラットフォームがシステム内のクライアントのシートでクライアントのオーディエンス・オブジェクトを作成および編集し、ユーザーをリストに追加できるようにするには、OAuth 2.0プロトコルの認可コード付与タイプを使用する必要があります。

ノート: Oracle Data Cloudプラットフォームでは、現在、クライアント資格証明タイプまたはその他のOAuth 2.0メソッドはサポートされていません。

OAuth 2.0を使用するかわりに、すべてのクライアント・シートまたは特定のシートにオーディエンスをインジェクトするために使用できる拡張TTLを持つアクセス・トークンを指定できます。アクセス・トークンを使用するには、システムでHTTP認証がサポートされている必要があります。

次の情報を提供します。

オーディエンス・オブジェクトのJSONスキーマ

システムに送信されるオーディエンス・オブジェクトのJSONスキーマおよびインジェクトされたオーディエンスのプライマリIDをプラットフォームに渡すために使用されるフィールドの名前を指定する必要があります。POSTメソッドとPUTメソッドの両方で、このスキーマがサポートされている必要があります。

デフォルトのオーディエンス・オブジェクトのスキーマ:

{ "name": "$AUDIENCE_NAME_$CAMPAIGN_NAME_$TIMESTAMP", "price": $PRICE "advertiserId": $ADVERTISER_ID }

プラットフォームから受信する標準のJSON形式のオーディエンス・オブジェクトのフィールド:

オーディエンス・オブジェクトの入力スキーマに、次のマクロを含めることができます。

次の例は、システムに送信されるオーディエンス・オブジェクトのJSONスキーマを構成する方法を示しています。

ベンダーに送信されるサンプル・オーディエンス・オブジェクト(JSON):

{
	"name": "Oracle Data Cloud platform Audience: $AUDIENCE_NAME",
	"price": $PRICE,
	"advertiserId": $ADVERTISER_ID
}

次の例は、オーディエンス・オブジェクトの入力スキーマを構成する方法を示しています。

サンプル・オーディエンス・オブジェクト(JSON)の出力:

{
	"external_audience_id":"123-abc-456",
	"name": "Vendor Campaign_BlueKai Audience_1432131627"
}

オーディエンス・オブジェクトのフィールド:

オーディエンス・オブジェクトID名

システムで作成されたオーディエンス・オブジェクトに対して生成されたユニークIDにリンクされているキーの名前を提供する必要があります(external_audience_id、id、segment_idなど)。プラットフォームによって(オーディエンスAPIに対するPOSTリクエスト経由で)システムにオーディエンス・オブジェクトが作成されると、APIによって、システムでオーディエンスに対して作成されたIDを持つJSONオブジェクトが返されます("external_audience_id": "123"など)。

オーディエンスAPI

システムでオーディエンス/セグメント・オブジェクトを作成、検証および更新するPOST、GETおよびPUTメソッドをサポートする、それぞれのオーディエンスAPIをOracle Data Cloudに提供する必要があります。

オーディエンスの作成(POST)

指定したオーディエンス・オブジェクトのJSONスキーマを使用して、Oracle Data Cloudプラットフォームからオーディエンス・オブジェクトをJSON形式で受信するには、POSTメソッドが必要です。システムがサードパーティ・データを受け入れる場合、オーディエンスAPIがJSON本文のpriceフィールドを受け入れることができる必要があります。POSTリクエストを受信した場合、システムで作成された外部オーディエンスをJSON形式でプラットフォームに返します。

リクエスト

example.com/rest/audiences

サンプル本文

{
	"name": "Vendor Campaign_BlueKai Audience_1432131627",
	"price": 1.35,
	"advertiserId": 12345
}

サンプル落札レスポンス: HTTP 200成功コードおよび次のJSON本文

{
	"external_audience_id":"123-abc-456",
	"name": "Vendor Campaign_BlueKai Audience_1432131627"
}

エラー・レスポンス: HTTP 4xxエラー・コード。エラーが認可、認証または期限切れのアクセス・トークンに関連している場合は、401エラーまたは403エラーを返す必要があります。Oracle Data Cloudプラットフォームでは、現在、エラー・コードが解析または表示されません。エラー・コードは、内部的なデバッグで重要になります。

オーディエンスの検証(GET)

GETメソッドは、Oracle Data Cloudが、インジェクトされたオーディエンスのオーディエンス/セグメント・オブジェクトがシステムに作成されていることを検証するために必要です。

リクエスト:

example.com/rest/audiences/externalAudienceID

サンプル落札レスポンス: HTTP 200成功コードおよび次のJSON本文:

{
	"external_audience_id":"123-abc-456",
	"name": "Vendor Campaign_BlueKai Audience_1432131627"
}

エラー・レスポンス: HTTP 4xxエラー・コード

オーディエンスの更新(PUT)

サードパーティ・データを受信する場合、オーディエンスのCPMの更新をサポートするためにPUTメソッドが必要となります。このことは、カテゴリ価格が変更されたり、クライアントがオーディエンスのカテゴリを変更した場合に発生することがあります。PUTリクエストは、URLパスで外部オーディエンスIDをサポートする必要があります。

リクエスト:

example.com/rest/audiences/externalAudienceID

サンプル本文:

{
	"price": 1.00
}

サンプル・レスポンス: HTTP 200落札コードおよび次のJSON本文:

{
	"external_audience_id":"123-abc-456",
	"price": "1.00"
}

エラー・レスポンス: HTTP 4xxエラー・コード

PUTメソッドは、POSTと同じオーディエンス・スキームをサポートする必要があります。サンプル本文は、価格のみを更新するPUTの一般的なユースケースを示しています。ただし、PUTメソッドはPOSTと同じパラメータをすべて受け入れることができる必要があります。

オーディエンスAPIのテスト

オーディエンス収集アプリを作成する前に、次のcURLコマンドを使用して、オーディエンスAPIをテストできます。ベアラーのアクセス・トークンを提供し、Authorizationヘッダーに配置する必要があります。また、オーディエンス・エンドポイントを含める必要があります。

POST構文:

curl -X POST -d'{"name": "audienceName","price": D.CC,"audience_id": "audienceID"}' -H'Content-Type:application/json' -H'Authorization: Bearer yourAccessToken' 'yourAudienceEndpoint'

POST例:

curl -X POST -d'{"name": "BK_AI JS test audience1","price": 1.75,"audience_id": "abc123"}' -H'Content-Type:application/json' -H'Authorization: Bearer atesttoken' 'http://www.mocky.io/v2/570d68b8120000c60412e589'

GET構文

curl -X GET -H'Content-Type:application/json' -H'Authorization: Bearer yourAccessToken' 'yourAudienceEndpoint/audienceID'

GET例

curl -X GET -H'Content-Type:application/json' -H'Authorization: Bearer atesttoken' 'http://www.mocky.io/v2/570d68b8120000c60412e589/abc123'

PUT構文

curl -X PUT -d'{"price": D.CC}' -H'Content-Type:application/json' -H'Authorization: Bearer yourAccessToken' 'yourAudienceEndpoint/audienceID'

PUT例

curl -X PUT -d'{"price": 1.50}' -H'Content-Type:application/json' -H'Authorization: Bearer atesttoken' 'http://www.mocky.io/v2/570d68b8120000c60412e589/abc123'

オーディエンスの作成および配信

Oracle Data Cloudプラットフォームで、クライアントはファーストパーティ・データ、他のクライアントと共有するプライベート・セカンドパーティ・データおよびOracle Data Marketplaceで購入したサードパーティ・データを含むオーディエンスを作成します。次に、クライアントは、オーディエンスを配信し、オーディエンスをインジェクトする場所を指定します。

オーディエンス収集

クライアントのオーディエンス配信がアクティブになると、プラットフォームがアプリの作成ステップで取得したアクセス・トークンを使用してオーディエンス作成APIをコールして、システム内のクライアントのシートにオーディエンスをインジェクトします。オーディエンス作成APIによって、外部オーディエンスIDがプラットフォームに返されます。

Oracle Data Cloudにオーディエンス作成APIを提供する必要があります。キャンペーンがアクティブ化されると、プラットフォームによって、アクセス・トークンを使用してシステムのオーディエンス作成APIがコールされ、システム内のクライアントのシートにオーディエンスが作成されます。オーディエンスはすぐにクライアントによるターゲッティングに使用できます。

各アプリ・パートナ・プラットフォームで、わずかに異なる階層を使用してオーディエンス・オブジェクトが保存されます。オーディエンス・オブジェクトがベンダー・プラットフォームの階層内(広告主レベルやキャンペーンレベルなど)に保存される場合、Oracle Data Cloudがオーディエンス・オブジェクトをベンダー・プラットフォームの適切なレベルに関連付ける方法を認識することが必要になることがあります。

データ配信

標準の配信方法(SDTまたはJSONリターン)を介してデータを配信する場合は、プラットフォームによって、ユーザーまたはキャンペーンをセグメント・オブジェクトおよびカテゴリにマッピングするリストIDと、ユーザーが適格であるプラットフォームが渡されます。

SDT

SDTの方法では、Oracle Data Cloudプラットフォームからのユーザー・データをサーバーサイドのプロファイル・ストアに標準配信形式で転送します。スワップ済のIDがキャンペーンによって獲得されると、一意のユーザーID (UUID)および外部オーディエンスIDを含むリアルタイム・データが、JSON形式のPOSTリクエストを介してシステムに配信されます。external_audience_idは、個別のキーと値のペアとしてJSONオブジェクトに含まれます(また、PixelURL属性にも追加されます)。あるいは、プラットフォームでユーザー・データを毎時バッチ・ファイルまたは日次バッチ・ファイルに保管でき、そのファイルは、Oracle Data Cloud SFTPサーバーまたはAmazon S3バケットからダウンロードできます。SDTデータに基づいて、ユーザーを特定のリストに追加します。次の例は、システムに配信されるデータを示しています。

SDT JSONオブジェクトの例:

{ 
   "DeliveryTime":"Thu Dec 22 02:22:33 PST 2016",
   "DestinationId":1,
   "PixelCount":1,
   "Pixels":[ 
      { 
         "BkUuid":"6tRenM19999/4qBn",
         "CampaignId":45671,
         "CategoryId":"17 ",
         "PartnerUuid":"YOUR_PARTNER_UUID",
         "PixelId":9151,
         "PixelUrl":"http://www.site.com/15415/pixel.gif?external_audience_id=123-abc-456",
         "Rank":4,
         "Timestamp":"Thu Dec 22 02:22:33 PST 2016",
         "UtcSeconds":1482445313,
         "external_audience_id":"123-abc-456"
      }
   ]
}  

JSONリターン

JSONリターンの配信方法では、Oracle Data Cloudプラットフォームのユーザー・データがJavaSciptタグをホストするWebページに転送されます。適格なユーザーがこのページにアクセスすると、プラットフォームによって、external_audience_idなどのJSON形式のデータと、ユーザーが適格であるカテゴリを含むbk_resultsオブジェクトが返されます。JSONリターン方法は、通常、サイト最適化およびダイナミック・クリエイティブ最適化のパートナによって使用されます。次の例は、システムに配信されるデータを示しています。

JSONリターン・タグの例

var bk_results = {
    "campaigns": [
    {
        "campaign": 45671,
        "external_audience_id": "123-abc-456",
        "timestamp":1482445313,
        "categories": [
            {
                "categoryID":17,
                "timestamp":1482445842
            }
        ]
    }]
};

FAQ

オーディエンス収集にはどのようなメリットがありますか。

オーディエンス収集でオーディエンス・マッピング・プロセスを自動化し、迅速に処理することによって、次のメリットがもたらされます。

• クライアントはシステムにオーディエンスをセルフサービスで配信できます。プラットフォーム間でデータを迅速かつシームレスにアクティブ化できます。マッピングが即時に行われるため、通常、オーディエンスは24時間以内にシステムで完全に収集され、アクティブ化する準備が整います。手動マッピング・プロセスを使用すると、通常、クライアントのオーディエンスの収集に48-72時間かかります。
• Oracle Data Cloudプラットフォームでは、システムにおけるクライアントのオーディエンスのマッピングに必要な情報を提供するためにリソースを費やす必要がありません。オーディエンス収集によって節約される時間を活用して、アナリティクス、インサイトおよびその他のメディア・キャンペーンの最適化とのインテグレーションをさらに強化できます。
• クライアントのオーディエンスのマッピングに必要となる情報を取得するためにOracle Data Cloudやクライアントとの通信に時間を費やす必要がなく、実際のマッピング自体にリソースを費やす必要がありません。迅速で簡単なインテグレーションによって、クライアントがシステムにデータを配信する可能性が高まります。

オーディエンス収集インテグレーションでは何をする必要がありますか。

Oracle Data Cloudがシステム内のクライアントのシートにアクセスするために使用できる認証方法およびPOST、GETおよびPUTメソッドをサポートするオーディエンスAPIを提供する必要があります。また、Oracle Data CloudプラットフォームからSDTまたはJSONリターン・タグを介してユーザー・データを受信できる必要があります。

認証方法とオーディエンスAPIの準備が整いました。次に何を行いますか。

partner.bluekai.comにログインし、「Apps」→「Develop Apps」を選択して、新しいアプリを作成します。アプリ開発ツールを使用すると、インテグレーションに必要なすべての情報をすばやく入力できます。詳細は、アプリの開発を参照してください。

SDT経由でデータを受信します。新しいサーバー・エンドポイントが必要ですか。また、現在のサーバー・エンドポイントを変更する必要がありますか。

オーディエンス収集インテグレーションに既存のサーバー・エンドポイントを使用することはできますが、外部オーディエンスIDを含む追加フィールドを処理できる必要があります。たとえば、SDTリアルタイム経由でデータを受信する場合、JSON POSTに"external_audience_id":"123-abc-456"などのフィールドが含まれます。SDTバッチ経由でデータを受信している場合、https://stags.bluekai.com/site/15415?limit=0&external_audience_id=123-abc-456などのピクセルURLフィールドの問合せ文字列からの外部オーディエンスIDを解析する必要があります。

アプリを保存しようとすると、エラー・メッセージが表示されます。何が問題ですか。

Oracle Data Cloudパートナ・マネージャがエンジニアリング・チームとの会議をスケジューリングするか、電子メールの送付先をお知らせします。DMP Engineeringのサポートを受けるには、提供されたcURLコマンドを使用してオーディエンスAPIを検証している必要があります。