オーディエンスAPI

DMPユーザーは、オーディエンスWebサービスを実装して、オーディエンスを作成および管理できます。オーディエンスには、ターゲッティング、モデリングまたは最適化のためにOracle Data Cloudパートナに配信するユーザーが含まれます。オーディエンスを分析して拡張したり、傾向を特定したり、そのカテゴリのパフォーマンスを分析することもできます。

たとえば、オーディエンスAPIを使用して、1つのセグメント(スマートフォンの購入に関心があるユーザーなど)を含む単純なオーディエンスを作成したり、複数のセグメント(スマートフォンの購入に関心があるユーザーとラップトップの購入に関心があるユーザーなど)を含むと同時に、その他のセグメント(特定の範囲の年齢や世帯収入のユーザーなど)を除外する複雑なオーディエンスを作成できます。オーディエンスの作成方法の詳細は、オーディエンス作成のリファレンスを参照してください。

ノート: ユーザーがOracle Data CloudプラットフォームUIでキャンペーンを作成することはなくなりました。キャンペーン・ワークフローは、オーディエンス・ワークフローの一部になりました。ただし、プラットフォームでは引き続きキャンペーンを使用して、オーディエンス・データ配信を管理できます。キャンペーンは、UIユーザーがオーディエンスを配信する際に自動的に作成されます。APIでは、以前と同様にキャンペーンを作成して使用します。

このトピックの内容  

APIについて知る

次の埋込みI/Oドキュメントを参照して、APIについての理解を深めることができます。I/Oドキュメントでは、各メソッドのパラメータについて説明し、コールのテンプレートを提供しています。ただし、ツールからライブAPIコールを実行することはできません。

次のリンクを新しいタブで開くと、I/Oドキュメントが3つのペインの形式で表示されます。

https://audiences2.docs.apiary.io

このAPIの詳細は、My Oracle Support (MOS)にお問い合せください。

サービスURI

オーディエンスAPIのURIは、次のとおりです。

services.bluekai.com/Services/WS/audiences

オーディエンスAPIのユースケース

オーディエンスAPIでどのような種類のオーディエンスを取得できますか。

  • 作成済オーディエンス: Oracle Data Cloudプラットフォームのオーディエンス・ビルダーまたはオーディエンスAPIを使用して作成したオーディエンス。
  • 受信済オーディエンス: DMPユーザーと共有したオーディエンス。受信済オーディエンスを使用してキャンペーンを作成したり、それを分析できます。

    オーディエンス共有は、一般的には、DMPユーザーでオーディエンスをエージェンシに送信するために使用され、その後エージェンシによってキャンペーンが実行されます。

    オーディエンスは、オーディエンス権限APIまたはOracle Data Cloudプラットフォームのオーディエンス管理ツールを使用して共有できます。

オーディエンスAPIはいつ使用しますか。

  • オーディエンスの作成およびインベントリの取得
    • ファーストパーティ・カテゴリを含むオーディエンス: DMPユーザーまたはオーディエンス受信者は、オーディエンスAPIを使用して、新しいオーディエンスを作成したり、既存のオーディエンスを取得できます。次に、セグメント・リーチAPIを使用して、オーディエンス内の一意のユーザーの数を取得できます。
    • サードパーティ・カテゴリを含むオーディエンス: データ購入者は、オーディエンスAPIを使用して、新しいオーディエンスを作成したり、サードパーティ・カテゴリを含む既存のオーディエンスを取得できます。次に、セグメント・リーチAPIを使用して、オーディエンス内の一意のユーザーの数を取得できます。
  • オーディエンス検出: DMPユーザーまたはオーディエンスを作成したデータ購入者は、オーディエンスAPIを使用して、オーディエンスの構成と設定を取得できます。これにより、同様のカテゴリと設定を持つ新しいオーディエンスを作成できます。
  • オーディエンス・アナリティクス: オーディエンス・アナリティクスをプログラマティックに実行するデータ・アプリ・パートナは、GETメソッドをコールし、返されたオーディエンス内のカテゴリを、Audience Discoveryレポートを作成するための入力として使用できます。
  • データ配信構成: オーディエンスAPIを使用して、パートナに配信するカテゴリのグループを作成できます。既存のオーディエンスを配信する場合は、オーディエンスAPIのGET関数を使用して、送信するオーディエンスを取得します。
  • データ・マッピング: データ・マッピングは、キャンペーンレベルで実行されます。これは、優先されるデータ配信方法であるサーバー・データ・トランスファーを介して配信されるユーザー・データとともにcampaignIDパラメータが含まれるためです。

関連するAPIコール

通常、オーディエンスAPIを使用する前後に実行するAPIコールは、次のとおりです。

関連するAPIコール ユースケース
オーディエンス権限API オーディエンスを他のDMPパートナと共有します。
キャンペーンAPI DMPパートナにターゲット・オーディエンスを配信するための指示を作成します。
ピクセルURL API 宛先をキャンペーンに関連付けます。
セグメント・リーチAPI オーディエンスを作成して配信する前に、オーディエンス内の一意のユーザーの推定数を取得します。
カテゴリAPI ターゲット・オーディエンスの作成に使用できるファーストパーティ・カテゴリとサードパーティ・カテゴリを表示します。
ユーザー・データAPI ユーザーが適格となったキャンペーンとカテゴリをプログラマティックに配信します。

GETレスポンスのサマリー

オーディエンスAPIのGETリクエストは、オーディエンスまたはオーディエンスのリストを返します。

プロパティ タイプ 説明
archived ブール オーディエンスがアーカイブされているかどうかを示します。アーカイブされたオーディエンスには、データは配信されません。
audienceGrants オブジェクト

別のDMPパートナから受信したオーディエンスに関連するプロパティが含まれているオブジェクト。共有する各オーディエンスには、次のプロパティが含まれています。

  • sharedDate: オーディエンスを最初に共有した日付(YYYY-MM-DD形式)
  • withdrawByDate: 共有オーディエンスが取り下げられる日付(YYYY-MM-DD形式)
  • emailNotes: オーディエンスの電子メール送信に関連付けられているユーザー指定のノート
audienceID 整数 オーディエンスに割り当てられている一意の識別子
campaigns オブジェクト

オーディエンスが追加されているキャンペーンのリストを含むオブジェクト。各キャンペーンには、次のプロパティが含まれています。

  • campaignID: キャンペーンに割り当てられている一意の識別子。このプロパティは、キャンペーンを所有している場合にのみ返されます。
  • partnerID: このキャンペーンを共有していたDMPパートナの一意の識別子。このプロパティは、キャンペーンを所有していない場合にのみ返されます。
  • name: キャンペーンのユーザー指定の名前。
createDate 日付 オーディエンスが作成された日付(YYYY-MM-DD形式)。
countryCodes 整数

オーディエンスがターゲットする国の2文字のISO 3166-1 alpha-2国コード。
deviceTypeId 整数

オーディエンスがターゲットするユーザーのデバイスを示します。これは、次の値のいずれかになります。

  • 0: すべてのデバイス(デスクトップとモバイル)
  • 1: デスクトップ・デバイス
  • 2: モバイル・デバイス
name 文字列 オーディエンスのユーザー指定の名前。
partnerID 整数 Oracle Data Cloudプラットフォーム・シートに割り当てられている一意の識別子。
prospecting ブール レガシー・フィールド。
recency 整数 ユーザーをオーディエンスに含めるようにカテゴリ属性でタグ付けしておく必要がある最大日数。デフォルトのリーセンシは0で、90日間を意味します。
retargeting ブール レガシー・フィールド。
segment オブジェクト

次の構造でオーディエンスを表すオブジェクト:

  • オーディエンスを表す1つのANDオブジェクト。
  • ANDオブジェクト内の、オーディエンスの個々のセグメントを表す1つ以上のORオブジェクト。
  • 各ORオブジェクト内の、セグメント内のカテゴリを表す1つ以上のカテゴリID (cat)のリスト。

このオブジェクトは、GET (読取り)レスポンスでのみ移入されます。GET (リスト)レスポンスでは空です。
status 文字列

オーディエンスが共有されているかどうかを示します。このプロパティは、次の値のいずれかになります。

  • Saved: オーディエンスはアクティブですが、共有されていません。
  • Shared: オーディエンスを別のDMPパートナと所有していました。
  • Received: 共有するオーディエンスをDMPパートナが受信しました。
  • Withdrawn: オーディエンスは共有されなくなりました。
totalCount 整数 GET (リスト)リクエストによって返されたオーディエンスの合計数

オーディエンス作成のリファレンス(POSTおよびPUTリクエスト)

Oracle Data Cloud APIでは、オーディエンスは、一連のセグメントをAND論理で組み合せて表現されます

{ "AND": [<Segment1>, <Segment2>, ...] }

各セグメントに含まれる1つ以上のカテゴリは、OR論理で組み合されます。

{"OR": [{"cat1", <categoryID>}, {"cat2", <categoryID>), ...] }

オーディエンスに複数のセグメントが含まれている場合、ユーザーはターゲット・オーディエンスに含まれるすべてのセグメントの基準を満たす必要があります(AND条件)。

セグメントに複数のカテゴリが含まれている場合、ユーザーは、セグメントに含めるカテゴリのいずれかでタグ付けされていることのみが必要です(OR条件)。

1つのセグメントへのカテゴリの追加

1つのカテゴリを持つ1つのセグメントが含まれる単純なオーディエンスを作成できます。

たとえば、In-Market > Autos (categoryID = 17)をセグメントに追加する場合、ユーザーは、オーディエンスに含めるそのカテゴリでタグ付けされている必要があります。

次のコード・スニペットは、1つのカテゴリを持つ1つのセグメントが含まれるオーディエンスAPIのPOSTリクエストのJSON本文を示しています。

"segment": {"and": [{"or": [{"cat": 17}]}]}

セグメントへの複数のカテゴリの追加

セグメントに複数のカテゴリを追加でき、その場合、OR条件が形成されます。つまり、ユーザーは、ターゲット・オーディエンスに含めるセグメントのカテゴリのいずれかでタグ付けされていることのみが必要です。

たとえば、In-Market > Retail > Video Games > Systems > Sony > Playstation (categoryID = 7628)およびIn-Market > Retail > Video Games > Systems > Microsoft > XBOX (categoryID = 7624)をセグメントに追加する場合、ユーザーは、含めるビデオ・ゲーム・システムのいずれかでタグ付けされていることのみが必要です。

次のコード・スニペットは、1つのセグメントに複数のカテゴリが含まれるオーディエンスAPIのPOSTリクエストのJSON本文を示しています。

segment": {"AND": [{"OR": [{"cat": 7624},{"cat": 7628,"freq": [1, null]}]}]}

オーディエンスへの複数のセグメントの追加

ターゲット・オーディエンスには複数のセグメントが含まれることもあり、その場合、AND条件が形成されます。つまり、ユーザーは、ターゲット・オーディエンスに含まれるすべてのセグメントの基準を満たす必要があります。

たとえば、あるセグメントにIn-Market > Travel > Air Travel (categoryID = 139)を追加し、別のセグメントにIn-Market > Travel > Cruises (categoryID = 6089)を追加する場合、ユーザーは、含める両方のカテゴリでタグ付けされている必要があります。

次のコード・スニペットは、複数のセグメントが含まれるオーディエンスAPIのPOSTリクエストのJSON本文を示しています。

"segment": {"AND": [{"OR": [{"cat": 139}]},{"OR": [{"cat": 6089}]}]}

セグメントの除外

ターゲット・オーディエンスでは、セグメント内の1つ以上のカテゴリを除外でき、その場合、NOT条件が形成されます。つまり、除外されたセグメント内のユーザーは、ターゲット・オーディエンスに含まれなくなります。

たとえば、In-Market > Travel > Cruisesカテゴリ(categoryID = 6089)のユーザーを含めても、Demographic > Premium Demographic > Income > $0-$14,999 (categoryID = 5814)とDemographic > Premium Demographic > Income > $15,000-$19,999 (categoryID = 71)のカテゴリのユーザーを除外する場合、クルーズの購買意向が強いものの、指定された低所得層に属するユーザーは、ターゲット・オーディエンスには含められません。

次のコードは、様々なセグメントを含めたり除外するオーディエンスAPIのPOSTリクエストのJSON本文を示しています。

"segment": {"AND": [{"OR": [{"cat": 18}]},{"NOT": {"OR": [{"cat": 71},{"cat": 5814}]}}]}

頻度およびターゲット・デバイスの設定

(オプション)オーディエンスAPIのPOSTおよびPUTリクエストで頻度とターゲット・デバイスを指定できます。

  • Frequency: 頻度は、あるカテゴリでユーザーが初めてタグ付けされて以来、そのカテゴリに何回適格となった場合に、問合せに含めるかを表します。

    たとえば、前述の例を使用して最小頻度を10に設定するには、次の構文を使用して、freqパラメータをJSON本文に含めます。

    {"AND": [{"OR": [{"cat": 17,"freq":[10]}]}]}

    頻度の範囲(たとえば、10から20まで)を設定するには、次の構文を使用します。

    {"AND": [{"OR": [{"cat": 17,"freq":[10,20]}]}]}

  • Device: device_typeパラメータを使用して、特定のデバイス・タイプ(デスクトップまたはモバイル)に基づいてオーディエンスのリーチを取得できます。たとえば、モバイル・デバイスのみのオーディエンスのリーチを取得するには、次の構文を使用します。

    {"AND": [{"OR": [{"cat": 17}]}],"device_type": "mobile"}

    デフォルトのデバイス・タイプはAll (デスクトップとモバイル)です。APIでは、all (デスクトップとモバイル)、desktop、mobileのデバイス・タイプがサポートされています。

さらに学ぶ

Oracle Data Cloud APIの概要