オーディエンスAPI統合ガイド

Rokt Audience APIは、広告主や技術パートナーがオーディエンスセグメントを直接Roktに転送し、キャンペーンのターゲティングや抑制に利用できるようにします。オーディエンスを同期させることで、キャンペーンが適切なユーザーに届き、表示すべきでないユーザーに広告を配信することを避け、無駄な支出を削減できます。これにより、キャンペーン全体のパフォーマンスが向上します。

前提条件

始める前に、以下を確認してください:

• API資格情報 – APIキーとシークレットペアを要求するには、Roktのアカウントマネージャーに連絡してください。これらの資格情報は、すべてのAPIリクエストで基本認証に使用されます。

---

認証

Rokt Audience APIは、次のいずれかの方法で基本認証を使用して認証できます:

HTTPクライアントの認証設定を使用する

HTTPクライアントが基本認証をサポートしている場合、APIキーを「ユーザー名」として、シークレットを「パスワード」として使用します。

Authorization ヘッダーを手動で設定する

HTTPクライアントが自動的に認証を処理しない場合、ヘッダーを自分で構築します:

1. キーとシークレットをコロン (:) で区切って連結します:

   example-api-key:example-api-secret

2. 結果をUTF-8でBase64エンコードします:

   ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

3. エンコードされた文字列の前に認証方法をスペースを含めて付けます:

   Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

4. 結果の文字列をHTTPリクエストの Authorization ヘッダーとして設定します:

   Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

必須ヘッダー

ヘッダー	値	説明
Content-Type	application/json	リクエストボディの形式
Charset	utf-8	文字エンコーディング
Authorization	Basic base64(api-key:api-secret)	認証資格情報

---

APIリファレンス

エンドポイント

POST https://inbound.mparticle.com/s2s/v1/UserProfile

リクエストボディ構造

リクエストボディはオブジェクトの配列であり、各オブジェクトは単一のユーザーを表し、identities と device_updates でユーザーを識別するために必要なフィールドを含み、user_attributes でプロファイルに属性を追加し、external_audience_membership_updates オブジェクトを使用して1つ以上のオーディエンスに追加または削除します。

単一のペイロードに複数のユーザーを含めるには、配列に追加のオブジェクトを追加します。各オブジェクトの request_type は常に "user_profile_modify" に設定する必要があります。

各ペイロードには最大100ユーザーを含めることができます。

[
  {
    "request_type": "user_profile_modify",
    "environment": "production",
    "data": {
      "source_request_id": "unique-request-id-here",
      "identities": {
        "customerid": "cust_123456",
        "email": "email@example.com",
        "other": "SHA256-email"
      },
      "device_updates": [
        {
          "device_info": {
            "ios_advertising_id": "00000000-0000-0000-0000-000000000000"
          }
        }
      ],
      "user_attributes": {
        "workspace": [
          {
            "attribute_name": "some_attr_1",
            "attribute_value": "some_val_1"
          },
          {
            "attribute_name": "some_attr_2",
            "attribute_value": "some_val_2"
          }
        ]
      },
      "external_audience_membership_updates": [
        {
          "external_audience_id": "audience_name_1",
          "action": "add",
          "change_timestamp_ms": 1713895200000
        },
        {
          "external_audience_id": "audience_name_2",
          "action": "remove",
          "change_timestamp_ms": 1713895200000
        }
      ]
    }
  }
]

Audience APIはリクエストごとに最大100ユーザーをサポートします。

[
  { "request_type": "user_profile_modify", ... },
  { "request_type": "user_profile_modify", ... },
  { "request_type": "user_profile_modify", ... }
]

---

フィールドリファレンス

一般的なリクエストボディフィールド

これらのフィールドは、各ユーザーオブジェクトのルートレベルで設定されます。

{
  "request_type": "user_profile_modify",
  "environment": "production",
  "data": {
    "source_request_id": "unique-request-id-here"
  }
}

フィールド	タイプ	必須	説明
request_type	string	はい	"user_profile_modify"に設定する必要があります。
environment	string	はい	"production"に設定する必要があります。
source_request_id	string	いいえ	このリクエストを一意に識別するための値。任意の有効な文字列が受け入れられます。

ユーザーアイデンティティ

ユーザーアイデンティティは、data.identitiesオブジェクトに設定されます。Roktがリクエストをユーザーにマッチさせるためには、少なくとも1つの識別子が必要です。

"identities": {
  "email": "email@example.com",
  "other": "SHA256-hashed-email",
  "customerid": "cust_123456"
}

フィールド	タイプ	必須	説明
email	string	条件付き必須	プレーンテキストのメールアドレス。小文字でトリムされている必要があります。ハッシュ化されたメールが提供されていない場合に必須です。
other	string	条件付き必須	SHA-256でハッシュ化されたメール。ハッシュ化する前に小文字でトリムされていることを確認してください。プレーンテキストのメールが提供されていない場合に必須です。
customerid	string	いいえ	内部の顧客またはユーザーID。

デバイス情報

デバイス識別子は、data.device_updates[]配列内のオブジェクトとして送信され、特にモバイルユーザーに対してマッチ率を向上させます。

"device_updates": [
  {
    "device_info": {
      "ios_advertising_id": "00000000-0000-0000-0000-000000000000"
    }
  }
]

フィールド	タイプ	必須	説明
ios_advertising_id	string	いいえ	Apple iOSデバイスの広告識別子（IDFA）。
android_advertising_id	string	いいえ	Google Android広告識別子（GAID）。
ios_idfv	string	いいえ	Apple iOSデバイス識別子（IDFV）。
android_uuid	string	いいえ	Android識別子。

ユーザー属性

各属性は、data.user_attributes.workspace[]配列内のオブジェクトとして送信されます。送信したい属性をattribute_nameに設定し、対応する値をattribute_valueに設定します。

"user_attributes": {
  "workspace": [
    {
      "attribute_name": "firstname",
      "attribute_value": "Jane"
    },
    {
      "attribute_name": "lastname",
      "attribute_value": "Smith"
    }
  ]
}

Roktは、帰属、レポート、および最適化を改善するために、可能な限り多くの以下のユーザー属性を送信することを推奨します。

属性	タイプ	必須	説明
firstname	string	いいえ	顧客の名前。
firstnamesha256	string	いいえ	名前のSHA-256ハッシュ。ハッシュ化する前に、小文字でトリムし、すべての末尾のスペースを削除します。
lastname	string	いいえ	顧客の姓。
lastnamesha256	string	いいえ	姓のSHA-256ハッシュ。ハッシュ化する前に、小文字でトリムし、すべての末尾のスペースを削除します。
mobile	string	いいえ	電話番号は1112345678または+1 (222) 345-6789のいずれかの形式でフォーマットできます。
mobilesha256	string	いいえ	携帯電話番号のSHA-256ハッシュ。ハッシュ化する前に、携帯電話番号は5551234567（ダッシュやスペースなし）としてフォーマットする必要があります。
age	string	いいえ	顧客の年齢。
dob	string	いいえ	生年月日。yyyymmddの形式でフォーマットします。
gender	string	いいえ	顧客の性別。例えば、M、Male、F、またはFemale。
city	string	いいえ	顧客の都市。
state	string	いいえ	顧客の州。
zip	string	いいえ	顧客の郵便番号。
title	string	いいえ	顧客の称号。例えば、Mr、Mrs、Ms。

ハッシュ化のためのデータ正規化

SHA-256で値をハッシュ化する前に:

• すべてのテキストを小文字にする
• 先頭と末尾の空白をトリムする
• 電話番号をフォーマット 5551234567 に正規化する（ダッシュ、スペース、括弧、国コードを削除）

オーディエンスメンバーシップの更新

各オーディエンス更新は、data.external_audience_membership_updates[] 配列内のオブジェクトとして送信されます。オーディエンスごとに1つのオブジェクトを追加します。

"external_audience_membership_updates": [
  {
    "external_audience_id": "premium_users",
    "action": "add",
    "change_timestamp_ms": 1713895200000
  },
  {
    "external_audience_id": "retargeting_list",
    "action": "remove",
    "change_timestamp_ms": 1713895200000
  }
]

フィールド	タイプ	必須	説明
external_audience_id	string	はい	オーディエンスの名前。
action	string	はい	許可される値: "add" または "remove"。ユーザーをオーディエンスに含めるには "add" を使用し、除外するには "remove" を使用します。
change_timestamp_ms	number	いいえ	オーディエンスメンバーシップ変更のUnixタイムスタンプ（ミリ秒単位）。

オーディエンス更新のバッチ処理

可能な場合、単一のユーザーに対するすべてのオーディエンス更新を1つのリクエストにまとめてください。これにより、内部処理のパフォーマンスが向上し、オーバーヘッドが削減されます。オーディエンスごとに1つのオブジェクトを external_audience_membership_updates 配列に追加します。

---

制限

• 各広告主アカウントは1,000のユニークなオーディエンスに制限されています。この制限を超えた場合は、アカウントマネージャーに連絡してください。
• 単一のリクエストで、最大100のリクエストボディを送信できます。それぞれがユニークなユーザーを表します。
• external_audience_id の値は100文字に制限されています。

---

エラーレスポンス

ステータス	コード	説明
202	Accepted	リクエストは受け付けられました。202は処理の成功を保証するものではなく、下流でエラーが発生する可能性があります。オーディエンスがRoktでライブであることを確認するには、アカウントマネージャーに連絡してください。
400	Bad Request	リクエストJSONが不正、検証後に有効なUserProfileRequestsがない、またはペイロードが大きすぎます。APIはペイロードごとに100リクエストをサポートしています。
401	Unauthorized	認証ヘッダーが欠落しています。
403	Forbidden	認証ヘッダーは存在しますが、無効です。
429	Too Many Requests	APIは秒間270リクエストから始まる加速ベースのレート制限を使用し、時間とともに自動的にスケールアップします。現在の制限を超えた場合、APIは429 Too Many Requestsレスポンスを返します。Retry-After ヘッダーが存在しない場合は、指数バックオフとランダムジッターで再試行することをお勧めします。
503	Service Unavailable	リクエストを指数バックオフパターンで再試行することをお勧めします。
5xx	Internal Server Error	サーバー側のエラーが発生しました。再度リクエストを試みてください。このエラーが続く場合は、アカウントマネージャーに連絡してください。

失敗したリクエストの例としてのレスポンスボディ

{
    "errors" :
    [
        {
            "code" : "BAD_REQUEST",
            "message" : "requests[0].data.external_audience_membership_updates[0].external_audience_id cannot be longer than 100 characters."
        }
    ]
}