セグメント・リーチAPI

DMPユーザーは、セグメント・リーチ(SegmentInventory) Webサービスを実装して、オーディエンスの個々のカテゴリとセグメントおよびオーディエンス自体の一意のユーザーの推定数を取得できます。リーチは、現在のオーディエンスの構成に基づいて、カテゴリ、セグメントまたはオーディエンスで検出されたユーザーの数に基づきます。メディア実行プラットフォームにオーディエンスを配信する前に、そのオーディエンスの大きさが、必要な数のインプレッションを生成するのに十分であるかどうかをオーディエンス・リーチで確認できます。

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

このトピックの内容  

APIについて知る

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

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

segmentreach.docs.apiary.io

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

サービスURI

セグメント・リーチAPIのURIは、次のとおりです。

services.bluekai.com/Services/WS/SegmentInventory

関連するAPIコール

次に、通常、セグメント・リーチAPIを使用する前後に実行するAPIコールを示します。

関連するAPI ユースケース
オーディエンスAPI オーディエンスを、そのリーチの検証後に作成します。オーディエンスAPIの前後で、セグメント・リーチAPIをコールできます。最初にセグメント・リーチAPIをコールして、オーディエンスを作成する前に、オーディエンスのリーチを取得し、必要なスケールを満たすことを検証することも、最初にオーディエンスAPIをコールして、オーディエンスを作成してから、セグメント・リーチAPIを使用してそのリーチを検証することもできます。
キャンペーンAPI DMPパートナにターゲット・オーディエンスを配信するための指示を作成します。
カテゴリAPI セグメント・リーチAPIを使用する前に、オーディエンスを作成するために使用できるファーストパーティ・カテゴリおよびサードパーティ・カテゴリを表示します。

オーディエンス作成のリファレンス

Oracle Data Cloud APIでは、オーディエンスは、AND論理で結合された一連のセグメントで表されます

{"AND":[{"AND":[segment1,segment2,...]}]}

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

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

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

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

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

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

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

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

{"AND":[{"AND":[{"OR":[{"cat":17}]}]}]}

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

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

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

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

{"AND":[{"AND":[{"OR":[{"cat":7624},{"cat":7628}]}]}]}

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

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

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

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

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

複数のカテゴリを持つ複数のセグメントを含める

ターゲット・オーディエンスに複数のセグメントが含まれている場合、1つ以上のセグメントに複数のカテゴリを含めることができます。

たとえば、あるセグメントに複数の自動車のモデルのカテゴリを含めて、別のセグメントに地理とデモグラフィックのカテゴリを含めることができます。

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

{"AND":[{"AND":[{"OR":[{"cat":2150},{"cat":355}]},{"OR":[{"cat":2095},{"cat":2098}]}]}]}

セグメントの除外

ターゲット・オーディエンスでは、セグメント内の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本文を示しています。

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

頻度の設定

(オプション)セグメント・リーチAPIのPOSTリクエストで頻度を指定できます。

あるカテゴリでユーザーが初めてタグ付けされて以来、そのカテゴリに何回適格となった場合に、問合せに含めるかを示します。たとえば、前述の例を使用して、最小頻度を10に設定するには、次の構文を使用して、JSON本文にfreqパラメータを含めます。

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

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

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

国の設定

国: 1つ以上の国のオーディエンスのリーチを取得するには、各国の問合せ文字列にcountriesパラメータを含めます。たとえば、米国と英国のオーディエンスのリーチを取得するには、それぞれの国の2文字のISO 3166-1 alpha-2の国コードを含めた、countries=US,UKの構文を使用します

重要: デフォルトでは、セグメント・リーチでは、米国のみのデータを検索しているかのようにデータを返します。すべての国を含める場合は、countries=ALLを指定する必要があります。

IDソースの設定

IDソースを指定するには、device_typeパラメータを使用して、次のいずれかのコードを指定します。

  • 1: Oracle Data Cloudサードパーティ・デスクトップCookie ID
  • 3: Oracle Data Cloud MobileのCookie ID
  • 6: Google Advertising ID (AdID)
  • 9: Apple IDFA

デフォルトは、オーディエンスでサポートされるすべてのIDソースです。

IDソースに従ってインベントリの数値をレスポンスに含めるには、doPerIdTypeReachパラメータをtrueに設定します。デフォルト値はfalseです。

パートナIDの指定

ユーザー・アカウントが複数のシートに関連付けられている場合、ターゲットするシートを決定するために、問合せ文字列にパートナIDを含めることができます。(自分のパートナIDは、プラットフォームのUIの右上隅に表示されます。)パートナIDを指定するには、pidパラメータを使用します。次に例を示します。

services.bluekai.com/Services/WS/SegmentInventory?pid=999999

デバイスの設定(非推奨)

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

services.bluekai.com/Services/WS/SegmentInventory?deviceTypeID=2

デフォルトのデバイス・タイプはすべて(デスクトップとモバイル)です。Oracle Data Cloud APIでは、次のデバイス・タイプのコードがサポートされています。

  • 0: すべて(デスクトップとモバイル)
  • 1: デスクトップ
  • 2: モバイル

警告: deviceTypeIDパラメータは非推奨です。かわりにdevice_typeを使用してください。

セグメント・リーチPOSTレスポンスのサマリー

セグメント・リーチAPIのPOSTリクエストでは、指定されたオーディエンス、セグメントおよびカテゴリのリーチが返されます。

次のオーディエンスのプロパティが返される可能性があります。

プロパティ 説明
_cpuTime (Oracleの内部使用のみ) POSTのレスポンス時間(ミリ秒)
multiplier Oracleの内部使用のみ
namespaces Oracleの内部使用のみ
nvars Oracleの内部使用のみ
priceFloor Oracleの内部使用のみ
reach 現在の構成に基づく、カテゴリ、セグメントまたはオーディエンスで検出された一意のユーザーの合計数
status セグメント・リーチAPIに対するコールが成功した場合、この値はQUERY_SUCCESSになります。

次のセグメントのプロパティが返される可能性があります。

プロパティ 説明
nvars Oracleの内部使用のみ
priceFloor Oracleの内部使用のみ
reach 現在の構成に基づく、カテゴリ、セグメントまたはオーディエンスで検出された一意のユーザーの合計数

次のカテゴリのプロパティが返される可能性があります。

プロパティ 説明
cat カテゴリに割り当てられているユニークID
freq カテゴリの問合せで使用される頻度(指定されている場合)。頻度は、あるカテゴリでユーザーが初めてタグ付けされて以来、そのカテゴリに何回以上適格となった場合に、問合せに含めるかを表します。
nvars Oracleの内部使用のみ
reach 現在の構成に基づく、カテゴリ、セグメントまたはオーディエンスで検出された一意のユーザーの合計数

さらに学ぶ

Oracle Data Cloud APIの概要