메인 콘텐츠로 건너뛰기

​
사용자 계정 vs 광고 계정

Ads API를 사용할 때는 광고 계정과 X 사용자 계정이라는 두 가지 유형의 계정이 사용됩니다. Ads API 문서 전체에서 “account”라는 용어는 보통 광고 계정을 가리킵니다.
  • 광고 계정은 business.x.com에서 등록되며 API에서는 account_id로 식별됩니다. 광고 계정은 자금 출처(funding source)와 직접 연결되고, 하나 이상의 X 사용자 계정에서 가져온 콘텐츠를 ‘프로모션 가능 사용자(promotable users)’로 활용합니다. 각 광고 계정은 하나 이상의 X 사용자 계정에 권한을 부여할 수 있습니다. 광고 계정, 즉 “현재 계정(current account)”은 거의 모든 URL에서 인라인 :account_id 매개변수로 표현됩니다.
  • X 사용자 계정(예: @AdsAPI)은 Ads API에서 user_id로 식별됩니다. 이러한 계정은 하나 이상이 하나의 광고 계정과 연결될 수 있습니다. API에 요청을 보내는 인증된 X 사용자 계정은 ‘현재 사용자(current user)’라고 합니다. 현재 사용자가 액세스할 수 있는 광고 계정 목록은 GET accounts에서 확인할 수 있습니다. ‘프로모션 가능 사용자(promotable users)’는 특정 광고 계정이 프로모션할 수 있는 X 핸들입니다. 이에 대한 자세한 내용은 Obtaining Ads Account Access를 참고하세요.

​
광고 계정에 액세스하는 방법

광고주의 계정에 대해 Ads API 요청을 수행하는 방법은 두 가지가 있습니다.
  1. 광고주를 대신하여 요청하기(권장)
  2. Agency처럼 광고주의 계정에 대한 액세스 권한이 부여된 자신의 계정을 사용해 요청하기(여러 계정을 지원하는 경우 등)
이 문서는 이러한 옵션 간 차이에 대한 간략한 개요이며, 다중 사용자 로그인 FAQ와 같은 다른 자료와 함께 사용해야 합니다.  요청 승인에서 설명한 것처럼, Ads API에 대한 모든 요청에는 3-leggedOAuth 플로를 통해 획득한 액세스 토큰을 사용하는 OAuth 1.0a 기반 Authorization 헤더가 필요합니다. 애플리케이션은 액세스 토큰을 얻기 위한 웹 기반 OAuth 플로를 구현해야 합니다. Ads API 개발자는 X 광고주에게 로그인 자격 증명을 공유해 달라고 절대 요청해서는 안 됩니다. 기본적으로 각 X 개발자 App에는 App을 소유한 계정에 대해 Ads API 요청을 수행하는 데 사용할 수 있는 정적 access token이 포함되어 있습니다. 이러한 자격 증명은 3-legged 또는 PIN 기반 OAuth 플로 없이 단일 계정 사용 사례에 이상적입니다. 다른 X 광고 계정에 액세스하지 않는 경우, 아래 단계 대신 이러한 single-user 자격 증명을 사용하십시오.

​
접근 수준

​
App 수준 권한

각 사용자는 Ads API 신청 시 요청한 대로 해당 수준의 액세스 권한을 부여받습니다: 참고: 2023년 7월 이전에 액세스를 요청한 Ads API 개발자는 서로 다른 수준의 액세스 권한을 가질 수 있으며, OAuth 토큰이 최대 5개로 제한될 수 있습니다. 기존 애플리케이션에서 추가 엔드포인트에 대한 액세스를 받거나 토큰 한도를 해제하려면 액세스 증가 가이드를 참고하세요.

​
광고 계정 수준 권한

광고 계정(Ads Account)에 대한 접근 권한이 있는 각 사용자는 Account administrator, Ad manager, Campaign analyst, Organic analyst, Creative Manager 중 하나의 특정 계정 수준 권한을 가집니다. 계정 수준 권한에 대한 최신 문서는 business.x.com을 참조하세요. 애플리케이션은 현재 인증된 사용자의 권한을 Authenticated User Access API 엔드포인트를 통해 조회하여, 해당 사용자가 어떤 API 엔드포인트와 Ads 기능에 접근할 수 있는지 결정해야 합니다. 참고: Conversion API에 사용되는 모든 사용자 토큰은 Account administrator 또는 Ad manager 계정 수준 권한을 가진 사용자에 대해서만 사용할 수 있습니다.                                                                                                                                              

​
액세스 토큰을 발급받는 방법

​
1. 광고주(사용자) 액세스 토큰 받기

광고주의 액세스 토큰을 얻는 방법은 두 가지가 있습니다. 가장 일반적인 방법은 웹 UI 내에서 직접 3-legged OAuth flow를 사용하는 것입니다. 광고주에게 공개적으로 노출된 UI가 없는 애플리케이션은 PIN-based OAuth 프로세스를 구현할 수 있습니다. 사용자가 3-legged 플로우를 완료하면, 애플리케이션은 API를 통해 해당 광고주의 Ads 계정에 요청을 보낼 수 있는 자격 증명을 얻게 됩니다. OAuth 플로우를 통해 사용자 자격 증명을 얻는 방식은 대부분의 Ads API 개발자가 광고주 계정에 대한 액세스를 얻기 위해 강력히 권장되는 방법입니다. 이를 통해 사용자를 대신하여 API를 호출하고 그 사용자로서 작업을 수행할 수 있습니다. 이러한 토큰은 만료되지 않지만, 사용자가 언제든지 토큰을 철회할 수 있습니다.

​
2. (개발자) 액세스 토큰 받기

이 옵션을 사용하려면 광고주가 business.x.com의 X UI를 통해 자신의 X Ads 계정에 귀하의 @username (또는 여러 @username)에게 액세스 권한을 부여해야 합니다. 귀하의 계정에 대해 3-legged OAuth 플로우를 통해 발급받은 액세스 토큰은 광고주의 X Ads 계정에 액세스할 수 있습니다. 이를 통해 광고주의 OAuth 토큰이 아니라 귀하 자신의 @username에 대한 OAuth 토큰을 사용하여 API를 호출할 수 있습니다. 이 옵션의 핵심 차이는, Post 위임/작성 권한이 귀하의 @username에 부여된 경우에만 프로모션 전용 포스트(Promoted-Only Posts)를 생성할 수 있다는 점입니다. 계정의 FULL 프로모션 가능 사용자(promotable user)를 대신하여 프로모션 전용 포스트(Promoted-Only Posts)를 생성할 수 있는 권한을 얻으려면, 이 플로우에서 포스트를 생성할 수 있는 액세스 권한도 부여받아야 합니다. 이렇게 되면 GET accounts/:account_id/authenticated_user_access 엔드포인트에서 TWEET_COMPOSER 권한을 통해 액세스할 수 있습니다.

​
이러한 방법 간의 차이점

광고주(사용자) OAuth 토큰(개발자) OAuth 토큰
 (@username이 별도 계정으로 추가됨)
Ads 계정에 액세스✔✔
사용자를 대신해 게시물 생성✔✔*
캠페인 관리✔✔
애널리틱스에 액세스✔✔
사용자를 대신해 카드 생성✔✔
개발자의
X Ads UI를 통한 액세스 가능 여부		✔
요청 한도광고주별로 별도 적용광고주 계정별로 별도 적용
참고: 자세한 내용은 위의 개발자 액세스 토큰 받기 섹션을 참조하세요.

​
예시 사용 사례

​
OAuth 3-legged 웹 플로우를 통한 광고주의 액세스 토큰

표준 플로우는 웹 기반이며 3-legged authorization OAuth 플로우를 사용합니다. 여기에서 설명하는 스크린샷은 https://github.com/xdevplatform/twauth-web에서 소스를 확인할 수 있는 샘플의 일부입니다. 애플리케이션 플로우 중 어느 시점에는, 애플리케이션을 승인받기 위해 X로 리디렉션해야 합니다.
image0
요청 토큰과 함께 X로 리디렉션하면, 사용자는 애플리케이션을 승인하라는 메시지를 보게 됩니다.
image1
사용자가 애플리케이션을 승인하면, 요청 토큰을 생성할 때 제공했던 콜백 URL로 리디렉션됩니다. 이를 사용해 해당 사용자의 영구 액세스 토큰을 발급받아 로컬에 저장합니다.
image