ユーザーアカウント vs 広告アカウント
Ads API の利用には 2 種類のアカウントが関係します: 広告アカウントと X ユーザーアカウントです。Ads API のドキュメントを通じて「アカウント」という用語は通常、広告アカウントを指します。- 広告アカウントは business.x.com に登録され、API では account_id で識別されます。広告アカウントは資金源に直接紐づき、1 つ以上の X ユーザーアカウントを「promotable users」としてコンテンツを活用します。各広告アカウントは 1 つ以上の X ユーザーアカウントに権限を付与できます。広告アカウント、つまり「current account」は、実行されるほぼすべての URL 内でインラインの :account_id パラメーターとして表現されます。
- X ユーザーアカウント(たとえば @AdsAPI)は、Ads API では user_id で識別されます。これらのアカウントの 1 つ以上を、広告アカウントに関連付けることができます。API にリクエストを行う、認証された X ユーザーアカウントは「current user」と呼ばれます。current user がアクセスできる広告アカウントの一覧は、GET accounts で取得できます。「Promotable users」は、特定の広告アカウントによってプロモートできる X ハンドルです。詳細については、Ads アカウントアクセスの取得を参照してください。
広告アカウントへのアクセス方法
広告主のアカウントに対して Ads API リクエストを行うには、2 つの方法があります。- 広告主に代わってリクエストを行う(推奨)
- 広告主のアカウントへのアクセスが付与された自分のアカウントを使用してリクエストを行う。例: 複数アカウントをサポートする代理店。
アクセスレベル
アプリレベルの権限
各ユーザーは、Ads API への申請時にリクエストされたアクセスレベルを持ちます。- Conversion Only: ユーザーはMobile および Web Conversion エンドポイントにread & write アクセスできます。
- Standard Access: ユーザーはAnalytics、Campaign Management、Creatives、Custom Audiences、Conversion エンドポイントにread & write アクセスできます。
広告アカウントレベルの権限
Ads アカウントへアクセスできる各ユーザーは、特定のアカウントレベル権限を持ちます: Account administrator、Ad manager、Campaign analyst、Organic analyst、Creative Manager。アカウントレベル権限に関する最新のドキュメントは business.x.com でご確認ください。アプリケーションは、Authenticated User Access API エンドポイントを介して現在認証されたユーザーの権限を取得し、どの API エンドポイントおよび広告機能にアクセスできるかを判定する必要があります。 注: Conversion API で使用するユーザートークンは、Account administrator または Ad manager のアカウントレベル権限を持つユーザーのものである必要があります。アクセストークンの取得方法
1. 広告主(User)のアクセストークンを取得する
広告主の access token を取得する方法は 2 つあります。最も一般的な方法は、Web UI から直接3-legged OAuth フローを使用する方法です。広告主に公開可能な UI がないアプリケーションは、PIN ベースの OAuth プロセスを実装できます。ユーザーが 3-legged フローを完了すると、アプリケーションは API を通じてその Ads アカウントに対するリクエストを行うための資格情報を得ます。 OAuth フローによるユーザー資格情報の取得は、大多数の Ads API 開発者が広告主アカウントへのアクセスを得るために強く推奨する方法です。これによりユーザーに代わって API を呼び出し、そのユーザーとして操作を行えるようになります。これらのトークンは有効期限はありませんが、ユーザーがいつでも取り消すことができます。2. 自分(Developer)のアクセストークンを取得する
このオプションは、広告主が business.x.com の X UI 経由で@username に権限を付与する必要があります(あるいは @usernames)。自分のアカウントの 3-legged OAuth フローで取得した アクセストークン で、広告主の X Ads アカウントにアクセスできるようになります。 これにより、広告主の OAuth トークンではなく、自分の @username の OAuth トークンで API を呼び出すことができます。このオプションの重要な違いは、Post の delegation/composer 権限が @username に付与されている場合にのみ Promoted-Only Post を作成できる、という点です。 アカウントのFULL promotable user に代わって Promoted-Only Post を作成する権限を得るには、このフローで Post 作成のアクセスも付与される必要があります。これにより、GET accounts/:account_id/authenticated_user_access エンドポイントで TWEET_COMPOSER 権限としてアクセスが有効になります。
これら方法の違い
注: 詳細は上の 自分(Developer)のアクセストークンを取得する セクションを参照してください。
サンプルユースケース
OAuth 3-legged Web フロー経由の広告主のアクセストークン
標準的なフローは Web ベースで、3-legged authorization の OAuth フローを使用します。ここに示すスクリーンショットは、https://github.com/xdevplatform/twauth-web でソースを閲覧できるサンプルの一部です。 アプリケーションのある時点で、X にリダイレクトしてアプリケーションを認可することになります。
