概要

広告APIのv4でリリースされたオーディエンスAPIにより、従来のオーディエンスエンドポイントがいくつか改善されました。新しいオーディエンス処理バックエンドがベースになっているこの新しいエンドポイントでは、安定性、堅牢性、信頼性の面でいくつかの改善が行われました。このガイドの目的は、オーディエンスAPIと従来のオーディエンスのアップロードおよび管理プロセスの違いをはっきりと示すことです。 

リファレンスドキュメントは、オーディエンスAPIのリファレンスドキュメントページにあります。 

注: すべてのオーディエンスユーザーデータは、SHA-256でハッシュ化してからアップロードする必要があります。受け入れられているユーザーIDのタイプとデータの正規化に関する詳細については、「ユーザーデータ」ページを参照してください。

オーディエンス機能への変更点

v4ではカスタムオーディエンスに次のような変更が加えられました。また、v3の広告APIが利用できなくなった時点で、廃止予定のエンドポイントが使用できなくなります。

• 廃止予定TONアップロード:
  • GET accounts/:account_id/custom_audience_changes
  • GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
  • POST accounts/:account_id/custom_audience_changes
  • PUT accounts/:account_id/custom_audiences/global_opt_out
• 廃止予定リアルタイムオーディエンス:
  • POST custom_audience_memberships
• カスタムオーディエンス:
  • list_typeパラメーターは、すべてのカスタムオーディエンスエンドポイントのリクエストと応答から削除されます。このパラメーターは、以前はオーディエンスのユーザーIDタイプ（メール、TwitterのユーザーIDなど）を識別するために使用されていましたが、オーディエンスでは同じオーディエンスに対して複数のユーザーIDを受け入れることができるようになったため、この値が意味のないものとなりました。
• 一般:
  • オーディエンスのルックバック期間が更新され、過去90日間にアクティブとなったユーザーをマッチングできるようになりました（これまでは30日間）
  • オーディエンスをターゲティングするために必要なマッチングユーザーの最小数が100ユーザーに減りました（これまでは500ユーザー）

前提条件

• 広告APIアクセス
• オーディエンスエンドポイントへのアクセスには、許可リストに登録される必要があります。初回の同意が2018年8月1日より前の場合は、このフォームに記入して新しいTwitter広告商品およびサービス契約に同意してください
  

オーディエンスのアップロードプロセス

次の表は、新旧のオーディエンス作成フローの主な違いをまとめたものです。詳細については後述します。

注: TONアップロードパスで更新またはオプトアウトするオーディエンスの場合は、対応するリストをTONアップロードエンドポイント経由でアップロードし、custom_audience_changesエンドポイントを使用してオーディエンスに関連付ける必要があります。

レート制限

オーディエンスAPIエンドポイントには、アカウントごとに1分あたり1,500のレート制限があります。1つのペイロードで送信できるユーザー数に制限はありません。ペイロードには次の制約のみがあります。

1.操作の合計数: 2,500操作

2.最大ペイロードサイズ: 5,000,000バイト

オーディエンスユーザー管理

新しいオーディエンスを作成するには、次の手順に従う必要があります

カスタムオーディエンスの新規作成

POST custom_audienceエンドポイントを使用して新しいカスタムオーディエンスの「シェル」を作成し、対応するカスタムオーディエンスidを取得します。この手順は、オーディエンスを最初から作成する場合に必要です。既存のオーディエンスを更新する場合は、次のセクションに進んでください

オーディエンスにユーザーを追加する

POST accounts/:account_id/custom_audiences/:custom_audience_id/usersとカスタムオーディエンスidを使用します。サンプルのペイロードは次のようになります。

POST https://ads-api.x.com/6/accounts/18ce54d4x5t/custom_audiences/1nmth/users

# All values must be hashed, unhashed values are used in this example for illustrative purposes
[
  {
    "operation_type": "Update",
    "params": {
      "effective_at": "2018-05-15T00:00:00Z",
      "expires_at": "2019-01-01T07:00:00Z",
      "users": [
        {
          "email": [
            "abc@twitter.com"
          ],
          "handle": [
            "twitter",
            "adsapi"
          ]
        },
        {
          "email": [
            "edf@twitter.com"
          ],
          "twitter_id": [
            "121291606",
            "17874544"
          ]
        }
      ]
    }
  }
]

ユーザーをオーディエンスに追加するには、operation_type Updateを使用します。新しいオーディエンスインターフェイスを使用すると、1人のユーザーに複数のユーザーキーを渡すことができます。JSONオブジェクトの配列内の各オブジェクトは1人のユーザーに対応します。上述のペイロードの例を使用すると、リクエストにより、emailとhandleを持つユーザーと、emailとtwitter_idを持つユーザーの2人がオーディエンスに追加されます。 

オーディエンスからユーザーを削除する

ユーザーを追加するプロセスと同様に、次のようなペイロードを使用すると、ユーザーをオーディエンスから削除できます。

POST https://ads-api.x.com/6/accounts/18ce54d4x5t/custom_audiences/1nmth/users

# All values must be hashed, unhashed values are used in this example for illustrative purposes
[
  {
    "operation_type": "Delete",
    "params": {
      "effective_at": "2018-05-15T00:00:00Z",
      "expires_at": "2019-01-01T07:00:00Z",
      "users": [
        {
          "email": [
            "abc@twitter.com"
          ],
          "twitter_id": [
            "783214",
            "1225933934"
          ]
        },
        {
          "email": [
            "edf@twitter.com"
          ],
          "twitter_id": [
            "121291606",
            "17874544"
          ]
        }
      ]
    }
  }
]

operation_typeはDeleteに設定する必要があります。ユーザーはユーザーをオーディエンスに追加したときのキーでマッチングされます。たとえば、emailとtwitter_idを使用してユーザーをオーディエンスに追加した場合、これらのキー（emailまたはtwitter_idのいずれか、または両方）を使用してこのユーザーを削除できます。

さらに、同じリクエストでオーディエンスにユーザーを追加および削除できます。エンドポイントはリクエストごとに複数のoperation_typeをサポートします。

ユーザーをオプトアウトする

グローバルオプトアウトエンドポイントが廃止予定になったため、パートナーは、オーディエンスをオプトアウトしたすべてのユーザーをDeleteする必要があります。これを実行するには次のような方法があります。

1. どのユーザーがどのオーディエンスに属しているかを追跡し、それらのユーザーを各オーディエンスから個別に削除します。
2. 広告アカウントに関連付けられているすべてのオーディエンスからユーザーを削除します。

一般的なベストプラクティス

• 処理に時間がかかり、一般的にシステムへの不要な負荷の原因となるキューのスパイクを避けるために、ほぼリアルタイムのバッチでこのエンドポイントを呼び出すことを強くお勧めします。さらに、これにより、より短時間にキャンペーンのターゲティングにユーザーを利用できるようになります。
• APIの呼び出しに成功すると、リクエストで受信されたuserオブジェクトの数に対応するsuccess_countとtotal_countが返されます。
• このエンドポイントはアトミックな性質を持ちます。つまり、リクエスト全体が成功するか、エラーが発生した場合はリクエスト全体が失敗することになります。エラー応答になった場合は、APIの利用者がエラーを修正し、ペイロード全体でリクエストを再試行することをお勧めします。 
• 失敗した場合、パートナーは指数関数的後退のアプローチを使用して再試行することをお勧めします。たとえば、最初の失敗時にはすぐに再試行し、2回目の失敗は1分後に再試行し、3回連続で失敗する場合は5分後に再試行するようにします