Digital Platform API - Instant Audience サービス

Instant Audience Service は、ストリーミング アーキテクチャを使用して、Digital Platform API を介して個々のユーザーまたは少数のユーザー グループをセグメントに追加するサーバー側の方式です。 これは、バッチ セグメント サービス API に代わるものです。バッチ セグメント サービス API は、大量のユーザーを対象ユーザーにアップロードします。 バッチ セグメント サービス API と同様に、アップロードはリアルタイムで処理されず、完了するまでに最大 24 時間かかる場合があります。

サービスを構成する

新しいクライアントで、インスタント オーディエンス サービスの使用を開始する場合は、次の情報でチケットをオープンし、提供する必要があります。

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

認証

Xandr API を呼び出す方法の一般的な概要については、「 認証サービス 」を参照してください。 他のサービスと同様に、 https://api.appnexus.com に対して認証を行います。 ただし、それ以降の呼び出しは https://streaming-data.appnexus.com 時に Instant Audience Service に対して行われます。

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

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

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

承認ヘッダー

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 ファイルを使用して、セグメントにユーザーを追加または削除する準備ができました。

次の例は、ユーザーを 2 つのセグメントに割り当てる方法を示しています。 この例では、メンバーはユーザー ID 12345678900987654321 (これは Xandr ユーザー ID) をセグメント 10001 と 10002 に追加し、値 = 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

seg_block array

Response

その他の 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 分のアクティベーション時間を遵守するために、Instant Audience Service には現在次の制限があります。

エラー シナリオの例

1 回の要求で 1,000 人を超えるユーザーを追加/削除する

要求で 1,000 人を超えるユーザーを追加または削除するための 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)
]
}

要求内の 1,000 ユーザーに対する応答

{
"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
}
]
}
]
}
}
]
}

関連トピック

• ストリーミング Server-Side セグメンテーション
• 使用状況統計を確認する