次の方法で共有

Digital Platform API - インスタント オーディエンス サービス

  • [アーティクル]

注:

アルファベータに関する通知

このフィールドまたは機能は、現在アルファフェーズまたはベータフェーズの機能の一部です。 そのため、変更される可能性があります。

インスタント オーディエンス サービスは、ストリーミング アーキテクチャを使用して、デジタル プラットフォーム API を介して個々のユーザーまたは小規模のユーザー グループをセグメントに追加するサーバー側のメソッドです。 インスタント オーディエンス サービスは、Batch Segment Service を使用して大量のデータを集計して定期的に送信するのではなく、リアルタイムに近いセグメントにユーザーを関連付けます。 このサービスを使用してセグメントにユーザーを追加するためのターゲット SLA は 2 分です。 これは、リアルタイムの対象ユーザーの改造要件がある場合に便利です。

サービスを構成する

既に Batch Segment Service を使用している場合は、この部分をスキップして 認証に進むことができます。 新しいクライアントでインスタント オーディエンス サービスの使用を開始する場合は、チケットを開き、次の情報を提供する必要があります。

  1. 外部ユーザー ID を使用していますか (つまり、mapUID を使用して Xandr を使用してマッピングを格納しますか? 別のメンバーの外部ユーザー ID を使用する場合は、その member_id も含めます。
  2. 他のメンバーに属するセグメントを設定する必要がありますか? その場合は、関連付けられている member_idsを指定します。
  3. セグメントを既定で期限切れにしたい場合 (たとえば、有効期限が切れない、60 日後に有効期限が切れるなど)? SEG ブロックに EXPIRATION を含める場合、既定の有効期限は使用されないことに注意してください。
  4. 次の質問は、社内のキャパシティ プランニングに関する質問です。
    • 投稿あたりの一意のユーザー ID の数はいくつですか?
    • 1 日あたりの予想投稿数はいくつですか?
    • 投稿あたりの一意のセグメントの数はいくつですか?

認証

Xandr API を呼び出す方法の一般的な概要については、 認証サービス を参照してください。 他のサービスと同様に、 https://api.appnexus.comに対して認証を行います。 ただし、その後の呼び出しは、 https://streaming-data.appnexus.comのインスタント オーディエンス サービスに対して行われます。

注:

認証応答で、インスタント オーディエンス サービスへの後続の呼び出しに必要となるトークンを書き留めます。

認証サービスからの応答の例:

{
    "response": {
        "status": "OK",
        "token": "hbapi:123456:9876abcd54321:nym2",
        "dbg_info": {
            ...
        }
    }
}

応答で返されるトークンは、次の例に示すように、承認ヘッダーまたは access_token クエリ文字列パラメーターとして、Instant Audience Service への後続の呼び出しに含める必要があります。

承認ヘッダー

curl -X POST -H "Authorization: hbapi:123456:9876abcd54321:nym2" https://streaming-data.appnexus.com/rt-segment

クエリ文字列

curl -X POST https://streaming-data.appnexus.com/rt-segment?access_token=hbapi:123456:9876abcd54321:nym2

セグメントからユーザーを追加/削除する

認証後、JSON ファイルを使用して、セグメントに対してユーザーを追加または削除する準備ができました。

注:

新しく作成されたセグメントにユーザーを追加する前に、約 20 分待ってください (これらのセグメントをすべてのサーバーに伝達できるようにします)。 ベスト プラクティスとして、新しいセグメントの作成を最小限に抑え、可能な限り既存のセグメントを再利用するか、セグメント valuesを使用して、既存のセグメント内のユーザーをさらにサブ分割します。 これらのプラクティスにより、ユーザーがセグメント間で追加/削除を成功させます。 セグメント valuesの作成の詳細については、UI ドキュメントの 「セグメント ピクセル: 高度な ターゲット」と 「セグメント ターゲット 」を参照してください。

次の例では、ユーザーを 2 つのセグメントに割り当てる方法を示します。 この例では、メンバーはセグメント 10001 と 10002 にユーザー ID 12345678900987654321 (これは Xandr ユーザー ID) を追加し、値 = 1 の関連付けと 1440 分以内の有効期限の両方を設定します。

ユーザーを 2 つのセグメントに割り当てる方法の例

API 呼び出し

curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/segment.json "https://streaming-data.appnexus.com/rt-segment"

JSON ペイロード

{
"rt_segment":
[
{
"user_id":"12345678900987654321",
"seg_block":[
{
"seg_id":10001,
"seg_code":null,"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":10002,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
}
],
"domain":null
}
]
}

応答

{
"response":{
"status":"OK",
"message":{
"users_in_request":1,
"segments_in_request":2
},
"warnings":[
]
}
}

JSON フィールド

rt_segment array

フィールド 種類 説明
user_id string これは、Xandr user_id か、デバイス識別子の例として、 "AEBE52E7-03EE-455A-B3C4-E57283966239"などのドメインに基づく ID です。
必須： 少なくとも 1 つ。
seg_block 配列 ユーザーと関連付けるセグメントのセグメント ブロックの配列 (以下のセグメント ブロック構造を参照)。
必須： 少なくとも 1 つ。
domain string Xandr ユーザー ID ( nullで表される) やデバイス識別子 (idfa、 sha1udid、 md5udid、 openudid、 aaid) など、要求で使用される識別子の種類。

注:
2019 年に非推奨となったsha1macは使用しないでください。

seg_block array

フィールド 種類 説明
seg_id int Xandr セグメント ID。
必須： セグメントを識別するために seg_code と member_id を使用していない場合。
seg_code string セグメントのユーザー定義名。

手記：SEG_CODEとmember_idまたはSEG_IDを含めることができますが、両方を含めないようにしてください。

必須： セグメントを識別するために seg_ID を使用しない場合。
value int セグメントに割り当てる数値。
expiration int ユーザー セグメントの関連付けの有効期間 (分単位)。 0の値は、セグメントが期限切れになることはないことを意味します。-1は、ユーザーがこのセグメントから削除されることを意味します。
member_id int seg_blockのセグメント所有者のメンバー ID。
必須：seg_codeを使用している場合。

Response

フィールド 種類 説明
status string 追加/削除が発生したか、エラーが発生したかを示します。
users_in_request int 要求で読み取ったユーザーの数。

手記： これにより、有効かどうかに関係なく、要求で最初に検出されたユーザーの数が表示されます。
segments_in_request int 要求で読み取られたセグメントの数。

注:
これにより、システムで有効かどうかに関係なく、呼び出しで関連付けられているユーザーに関係なく、要求で最初に検出されたセグメントの数が表示されます。

その他の POST シナリオ

デバイス ID (IDFA) の使用

REST API 呼び出し (IDFA)
curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/segment.json "https://streaming-data.appnexus.com/rt-segment"
JSON ペイロード (IDFA)
{
"rt_segment":[
{
"user_id":"1ba98a6c-d1a5-49ef-ad1c-2d9230ebcd13",
"seg_block":[
{
"seg_id":12,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":23784,
"seg_code":null,
"value":1,
"expiration":0,
"member_id":null
}
],
"domain":"idfa"
}
]
}
応答 (IDFA)
{
"response":{
"status":"OK",
"message":{
"users_in_request":1,
"segments_in_request":2
},
"warnings":
[
]
}

他のメンバーのコードの使用

REST API 呼び出し
curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/segment.json "https://streaming-data.appnexus.com/rt-segment"
他のメンバーの JSON ペイロード コード
{
"rt_segment":[
{
"user_id":"12345678900987654321",
"seg_block":[{"seg_code":"abcd",
"value":1,
"expiration":1440,
"member_id":1661
},
{
"seg_code":"zywx",
"value":1,
"expiration":1440,
"member_id":1262
}
],
- "domain":null
}
]
}
他のメンバーの応答コード
{
"response":{
"status":"OK",
“users_in_request”:1,
"segments_in_request":2
}
}

サービスの制限

注:

サービスの制限は、このサービスのアルファテストとベータテスト中に変更される可能性があります。

最大 2 分間のアクティブ化時間に従うために、インスタント オーディエンス サービスには現在、次の制限があります。

制限の種類 説明
通話率 1 秒あたり最大 100 POST 呼び出し (メンバーあたり) と 1 秒あたり最大 1000 GET 呼び出し (メンバーあたり)。 このレート制限を超えると、"レート制限を超えました" というメッセージが返されます。1 秒あたり 1000 回の読み取りの要求制限を超えて rt-segment-processed、待機してもう一度やり直すか、Xandr に問い合わせて上限を超えました。
オブジェクト - 1 秒あたり最大 1,000 ユーザー。
- 呼び出しごとにユーザーごとに最大 100 セグメント。
ペイロード サイズ JSON ペイロードは 1 MB を超えないようにしてください。

エラー シナリオの例

要求で 1,000 人以上のユーザーを追加/削除する

要求で 1000 人以上のユーザーを追加または削除するための API 呼び出し

curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/1002_users.json "https://streaming-data.appnexus.com/rt-segment"

要求内の 1000 人のユーザーに対する JSON ペイロード

{
"rt_segment":[
{
"user_id":"12345678900987654321",
"seg_block":[
{
"seg_id":10001,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":10002,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
}
],"domain":"domain"
},
#... assume there are additional 1000 users inthisarray(1002in total)
]
}

要求内の 1000 人のユーザーに対する応答

{
"response":{
"status":"OK",
"message":{
"users_in_request":1000,
"segments_in_request":2000
},
"warnings":[
{
"message":"Too many user_ids in request.",
"entity":{
"user_id":"23456789009876543211",
"seg_block":[
{
"seg_id":10001,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":10002,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
}
]
}
},
#... similar error will be sent for each user over 1000
]
}
}

seg_id または seg_code と member_id は提供されていません

JSON ペイロード (seg_id/seg_code とエラーシナリオ member_id )

{
"rt_segment": [
{
"user_id":"1",
"seg_block":
[
{
"seg_id":null,
"seg_code":"abc",
"value":1,
"expiration":1,
"member_id":null
}
]
}
]
}

応答 (seg_id/seg_code と member_id エラー シナリオ)

{
"status":"OK",
"message":{
"users_in_request":0,
"segments_in_request":0},
"warnings":[
{
"message":"'seg_id' or 'seg_code' and 'member_id' are required",
"entity":{
"seg_code":"abc",
"value":1,
"expiration":1
}
},
{
"message":"No valid segments for user_id: 1.",
"entity":{
"user_id":"1",
"seg_block":[
{
"seg_code":"abc",
"value":1,
"expiration":1
}
]
}
},
{
"message":"No valid rt_segment in request.",
"entity":{
"rt_segment":[
{
"user_id":"1",
"seg_block":[
{
"seg_code":"abc",
"value":1,"expiration":1
}
]
}
]
}
}
]
}

seg_block 指定されていません

JSON ペイロード (seg_block エラー シナリオ)

{
"rt_segment":[
{
"user_id":"asdf"
}
],
"domain":"domain"
}

応答 (seg_block エラー シナリオ)

{
"status":"OK",
"message":{
"users_in_request":0,
"segments_in_request":0
},
"warnings":[
{
"message":"'seg_block' is required",
"entity":{
"user_id":"asdf"
}
},
{
"message":"No valid rt_segment in request.",
"entity":{
"rt_segment":[
{
"user_id":"asdf"
}
]
}
}
]
}

user_id が空です

JSON ペイロード (user_id エラー シナリオ)

{
"rt_segment":[
{
"seg_block":[
{
"seg_id":1,
"seg_code":null,
"value":1,
"expiration":1,
"member_id":null
}
]
}
],
"domain":"domain"
}

応答 (user_id エラー シナリオ)

{
"status":"OK",
"message":{
"users_in_request":0,
"segments_in_request":0
},
"warnings":[
{
"message":"'user_id' is required and cannot be empty",
"entity":{
"seg_block":[
{
"seg_id":1,
"seg_code":null,
"value":1,
"expiration":1
}
]
}
},
{
"message":"No valid rt_segment in request.",
"entity":{
"rt_segment":[
{
"seg_block":[
{
"seg_id":1,
"seg_code":null,
"value":1,
"expiration":1
}
]
}
]
}
}
]
}