メインコンテンツへスキップ

​
ユーザーアカウントと広告アカウントの違い

X Ads API を利用するには、広告アカウントと X ユーザーアカウントという 2 種類のアカウントが関与します。Ads API のドキュメントでは、通常「アカウント」は広告アカウントを指します。
  • 広告アカウントは business.x.com で登録され、API では account_id によって識別されます。広告アカウントは資金源に直接紐づき、1 つ以上の X ユーザーアカウントのコンテンツを「プロモート可能なユーザー」として活用します。各広告アカウントは、1 つ以上の X ユーザーアカウントに権限を付与できます。広告アカウント、すなわち「現在のアカウント」は、実行されるほぼすべての URL でインラインの :account_id パラメータとして表されます。
  • X ユーザーアカウント（例：@AdsAPI）は、Ads API では user_id によって識別されます。これらのアカウントは 1 つ以上を広告アカウントに関連付けることができます。API にリクエストを送信する認証済みの X ユーザーアカウントは「現在のユーザー」と呼ばれます。現在のユーザーがアクセス可能な広告アカウントの一覧は GET accounts で取得できます。「プロモート可能なユーザー」とは、特定の広告アカウントがプロモーションできる X のハンドルを指します。詳細は Obtaining Ads Account Access を参照してください。

​
広告アカウントへのアクセス方法

広告主のアカウントに対して X Ads API リクエストを行う方法は 2 通りあります。
  1. 広告主に代わってリクエストを行う（推奨）
  2. Agency など、広告主のアカウントへのアクセス権が付与された自分のアカウントを使用してリクエストを行う
本ドキュメントは、これらの選択肢の違いを簡潔にまとめた概要であり、multi-user login FAQ などの他のリソースと併せて参照してください。 Authorizing a request で説明しているとおり、すべての Ads API リクエストには、OAuth 1.0a の 3-leggedOAuth フローで取得した access token を用いた Authorization ヘッダーが必要です。アプリケーションは、access tokens を取得するための Web ベースの OAuth フローを実装する必要があります。Ads API の開発者は、X の広告主にログイン認証情報の共有を決して求めないでください。 デフォルトでは、各 X developer application には、アプリケーションの所有アカウントに対して Ads API リクエストを行うために使用できる静的な access token が含まれています。これらの認証情報は、3-legged や PIN-based OAuth フローを必要としない単一アカウントのユースケースに最適です。別の X Ads アカウントにアクセスしない場合は、以下の手順ではなく、これらの single-user 認証情報を使用してください。

​
アクセスレベル

​
App レベルの権限

各ユーザーのアクセスレベルは、X Ads API の申請時に要求した内容に基づいて決定されます。 Note: 2023年7月以前にアクセスをリクエストした Ads API 開発者は、アクセスレベルや権限が異なる場合があり、OAuth トークンが5個に制限されている可能性があります。既存のアプリケーションで追加の endpoint へのアクセスを拡張する、またはトークン上限を解除する方法については、アクセスの拡張 ガイドを参照してください。

​
広告アカウントレベルの権限

Ads アカウントにアクセスできる各ユーザーには、特定のアカウントレベルの権限が付与されます：Account administrator、Ad manager、Campaign analyst、Organic analyst、Creative Manager。アカウントレベルの権限に関する最新のドキュメントは business.x.com を参照してください。アプリケーションは、現在認証されているユーザーの権限を Authenticated User Access API endpoint を通じて取得し、アクセス可能な API endpoint と Ads 機能を判断する必要があります。 注: Conversion API で使用するユーザートークンは、Account administrator または Ad manager のアカウントレベル権限を持つユーザーのものである必要があります。                                                                                                                                              

​
access token の取得方法

​
1. 広告主（ユーザー）の access token を取得する

広告主のaccess tokenを取得する方法は2つあります。最も一般的なのは、Web UI から直接3-legged OAuth フローを利用する方法です。広告主向けの公開 UI を持たないアプリケーションは、PIN-basedな OAuth プロセスを実装できます。ユーザーが 3-legged フローを完了すると、アプリケーションは API を通じてそのユーザーの Ads アカウントにリクエストを行うための認証情報を取得できます。 ユーザー認証情報を OAuth フローで取得する方法は、広告主アカウントへのアクセスを得るうえで、Ads API 開発者の大多数に対して強く推奨します。これにより、ユーザーに代わって API を呼び出し、そのユーザーとして操作を実行できます。これらのトークンに有効期限はありませんが、ユーザーが任意のタイミングで取り消すことができます。

​
2. （開発者向け）access token を取得する

このオプションでは、広告主が business.x.com の X UI を通じて、あなたの @username への権限付与（または複数の @username）を行い、自身の X Ads アカウントへのアクセスを許可する必要があります。あなたのアカウントに対して 3-legged OAuth フローで取得されたAccess Tokensは、広告主の X Ads アカウントにアクセスできます。 これにより、広告主の OAuth トークンではなく、あなた自身の @username の OAuth トークンを使用して API を呼び出せます。このオプションの重要なポイントは、あなたの @username に Post の委任/コンポーザー権限が付与されている場合にのみ、Promoted-Only Posts を作成できることです。 アカウント上の FULL プロモータブルユーザーの代理で Promoted-Only Posts を作成するには、このフローで Posts を作成する権限も付与されている必要があります。これにより、GET accounts/:account_id/authenticated_user_access endpoint の TWEET_COMPOSER 権限を通じてアクセスできるようになります。

​
これらの方法の違い

広告主（ユーザー）OAuth トークン（開発者）OAuth トークン
 （@username を追加して別アカウントとして分離）
広告アカウントにアクセス✔✔
ユーザーに代わって Posts を作成✔✔*
キャンペーンを管理✔✔
アナリティクスにアクセス✔✔
ユーザーに代わって Card を作成✔✔
開発者による X Ads UI
経由でのアクセス		✔
レートリミット広告主ごとに個別広告主アカウントごとに個別
注: 詳細は上記の （開発者）access token の取得 セクションを参照してください。

​
サンプルのユースケース

​
広告主の access token（OAuth 3-legged Web フロー）

標準フローは Web ベースで、3-legged authorization の OAuth フローを使用します。ここで示すスクリーンショットはサンプルの一部で、ソースコードは https://github.com/xdevplatform/twauth-web で確認できます。 アプリケーションの処理のある段階で、アプリの認可を行うために X へリダイレクトします。
image0
リクエストトークンを付与して X にリダイレクトすると、ユーザーにアプリの認可が求められます。
image1
ユーザーがアプリを認可すると、リクエストトークンの生成時に指定した callback URL にリダイレクトされます。これを用いて当該ユーザーの永続的な access token を取得し、ローカルに保存します。
image
⌘I