[Twitter/Ads API] 트위터 광고 API로 광고 데이터 가져오기

📈 Twitter Ads API

기업에서는 자신들의 서비스의 활용 가치를 더욱 올리기 위해 API를 제공합니다. 트위터 역시 API를 제공합니다. API를 통해 소셜 로그인 기능을 제공하는 등 트위터 서비스를 활용할 수 있습니다. 다른 기업도 같지만, 트위터의 경우 광고와 관련된 업무를 할 수 있도록 Twitter Ads API를 제공합니다. 광고 API를 통해 광고 자동화 혹은 광고와 관련된 리포트를 받아오는 등의 서비스를 이용할 수 있습니다. 이번 포스트에서는 트위터 광고 API 활용 절차를 가볍게 다뤄보고자 합니다.

 

(시작하기에 앞서 Twitter Ads API 개발자 문서를 살펴보시길 추천합니다.)

https://developer.twitter.com/en/docs/twitter-ads-api/getting-started

Getting Started

 

📉 Twitter Ads API 사용신청

API를 사용하기 위해선 승인 절차는 필수적입니다. 특히 광고처럼 프라이빗한 API의 경우 승인 절차가 더욱 복잡합니다. 개인적으로는 특히 트위터가 다른 매체에 비해 더욱 까다로웠던 기억이 있습니다. 트위터 광고 API를 사용하기 위해선 크게 3가지 절차 타이틀이 있습니다. 첫 번째로 개발자 계정에 가입을 해야 합니다. 두 번째는 프로젝트와 앱 생성 및 앱의 키와 토큰을 보관해야 합니다. 마지막으로 Ads API 액세스 요청을 거쳐 서비스에 접근할 수 있도록 합니다. 그럼 단계별로 하나씩 설명해 보겠습니다.

 

📂 개발자 계정 가입

아래 이미지는 개발자 계정 가입 절차입니다. 먼저 국가 선택 및 API를 사용하려는 목적을 선택합니다.

개발자 계정 가입 절차 - 국가 및 목적 입력

다음 단계로 넘어가면 API와 관련한 정책 안내 및 약관 동의 절차로 이어집니다.

개발자 계정 가입 절차 - 정책 안내 및 동의

 

🔐 프로젝트와 앱 생성 및 앱의 키와 토큰을 보관

가입을 완료했다면 두 번째 단계를 진행하면 됩니다. 개발자 센터에서 프로젝트 생성을 진행합니다. 먼저 프로젝트 이름을 지어줍니다.

프로젝트 생성 및 앱 키 토큰 보관 - 프로젝트 이름 지정

그다음 API의 주 사용 목적을 선택합니다.

프로젝트 생성 및 앱 키 토큰 보관 - 사용 목적 입력

프로젝트에 대한 요약을 기재하는 절차입니다. 크게 중요하진 않지만, 관련 중요한 내용을 적어두어 인수인계하는 등 프로젝트를 공유할 때 유용합니다.

프로젝트 생성 및 앱 키 토큰 보관 - 프로젝트 요약

바로 이어서 신규 앱을 해당 프로젝트 하위로 생성합니다.

프로젝트 생성 및 앱 키 토큰 보관 - 신규 앱 생성

배포할 환경을 선택합니다.

프로젝트 생성 및 앱 키 토큰 보관 - 앱 환경 선택

프로젝트와 마찬가지로 앱 이름을 지어줍니다.

프로젝트 생성 및 앱 키 토큰 보관 - 앱 이름 지정

다음으로 넘어가면 앱 생성이 완료됩니다. 앱 생성이 완료되면서, API Key, API Key Secret, Token이 생성되며 노출됩니다.

프로젝트 생성 및 앱 키 토큰 보관 - 앱 생성 완료 및 키, 시크릿, 토큰 제공

키들과 토큰은 앱을 생성할 때 처음이자 마지막으로 보입니다. 각 값을 잃어버렸을 때 앱 설정 내부에서 재발급을 받을 수 있지만, API를 사용할 때마다 매번 재발급을 받을 순 없기 때문에 키들과 토큰을 따로 보관해야 합니다. 단 값들이 외부에 노출되지 않도록 보안에 신경 써서 보관해야 합니다.

 

🔓 Ads API 액세스 요청

위의 두 단계는 일반적으로 Twitter API를 사용하기 위한 절차와 동일합니다. Ads API를 사용하기 위해선 추가로 액세스 요청을 진행해야 합니다. 공식문서에 나와있는 액세스 신청 페이지로 넘어가면 아래와 같은 페이지가 나옵니다.

Ads API 액세스 요청

첫 번째로 가장 기본적인 내용을 기재합니다. 이미지에 나와 있는 Company handle에는 트위터 계정을 입력하면 됩니다.

Ads API 액세스 요청 - 기본 내용 입력

그다음 컨택포인트에 관한 내용을 기재합니다.

Ads API 액세스 요청 - 컨택포인트 관련 입력

광고 계정으로 운영하는 사업체에 대한 설명을 기재합니다.

Ads API 액세스 요청 - 사업체 관련 설명 입력

사업에 관한 상세한 내용을 입력하고, API를 이용하는 다른 플랫폼에 대한 내용도 선택합니다. 다음 Client에 대한 내용을 기재합니다.

Ads API 액세스 요청 - 타사 운영 플랫폼 기입

트위터 광고 API를 통해 만들 제품에 대한 설명을 기재합니다. 저의 경우 데이터를 제공할 목적으로 사용하기 때문에 Internal business system을 선택했습니다.

Ads API 액세스 요청 - 제품에 대한 설명 기재

마지막으로 동의 여부를 체크하고 제출하면 신청이 완료됩니다. 신청이 완료되면 위에 작성한 컨택포인트 메일로 안내 메일이 발송됩니다. 메일 내용에선, 영업일 기준 7일 이내에 트위터 광고 API 승인 결과가 나온다고 안내합니다. 신청서에 별다른 문제가 없으면 보통 1~2일 안에 승인이 완료되었다는 메일을 받을 수 있습니다.

 

📺 광고 매니저로 데이터 구조 파악하기

트위터 API 개발 문서를 살펴보기에 앞서 트위터 광고가 어떻게 운영되고 있고, 어떤 기준으로 데이터를 제공하고 있는지 살펴볼 필요가 있습니다. 광고 매니저로 들어가면 아래 이미지와 같은 페이지를 볼 수 있습니다. 광고를 운영 중이라면, 매니저 페이지에 필터 조건에 따른 비용에 관한 차트를 보여주고 광고 단위별로 비용, 노출, 클릭 등을 집계하여 표로 제공합니다.

트위터 광고 매니저

위 사진을 자세히 살펴보면 캠페인, 광고 그룹, 광고 이 3개의 탭을 볼 수 있습니다. 대부분의 매체는 어떤 소재(광고)로 어떤 그룹(광고 그룹)에 어떤 액션(캠페인)을 하게 할지에 대한 형태로 광고를 구성합니다. 즉 광고는 광고 그룹에 포함되고, 광고 그룹은 캠페인에 포함됩니다. 자세히 설명하자면, 매니저 페이지의 캠페인 탭은 동일한 캠페인으로 지정한 모든 광고 그룹 데이터를 합산한 데이터를 제공합니다. API가 제공하는 데이터 역시 광고 매니저와 같은 소스를 사용하기 때문에 이점을 고려하면서 개발 문서를 살펴보면 좋습니다.

 

💻 트위터 광고 API 개발 문서 살펴보기

트위터 광고 API 개발 문서를 살펴보면, 광고 분석에 대한 문서가 있습니다. 문서에서는 트위터에서 광고 중인 콘텐츠의 성과를 이해하는 데 도움이 되는 정보(데이터)를 제공한다고 언급하고 있습니다. 데이터에는 노출 수, 클릭 수, 지출 등이 있습니다. 문서를 자세히 읽어보면 광고 API에서 실적 지표를 검색하는 2가지 방법(synchronously, asynchronously)을 지원한다고 말합니다. 저의 경우 동기식(synchronously) 방법을 사용했습니다. 2가지 방법에 대한 차이는 문서에 나와 있는 내용을 자세히 읽어보면 이해에 도움이 됩니다.

 

아래 링크의 Synchronous Analytics 문서에는 API 요청할 때 사용할 수 있는 파라미터와 파라미터의 내용을 설명합니다.

https://developer.twitter.com/en/docs/twitter-ads-api/analytics/api-reference/synchronous

Synchronous Analytics

Synchronous Analytics 리소스의 경우 안내하는 모든 파라미터가 필수조건입니다. 파라미터 중에서 entity는 데이터를 검색할 엔터티 유형을 선택할 수 있는 파라미터입니다. 앞서 광고 매니저를 살펴볼 때 데이터를 캠페인, 광고 그룹, 광고의 유형으로 나누었는데, entity의 값을 파라미터에 담아 요청하면 관련 리포트를 받을 수 있다는 것을 의미합니다. 파라미터 설명 아래에는 요청 예시 및 응답 예시를 같이 안내하고 있습니다. 요청 및 응답 예시는 API를 호출하는 양식을 살펴볼 수 있어 본격적으로 작업할 때 유용합니다.

 

위 설명을 보면서 느껴졌겠지만, 개발자 문서와 광고 매니저에서 제공하는 용어나 마케터들이 사용하는 용어가 다르기도 합니다. 담당자와 지속적인 커뮤니케이션을 통해 용어에 대한 싱크를 맞춰가면서 작업하면 훨씬 원활하게 작업할 수 있습니다.

 

⌨️ Python 코드 작성 및 데이터 가져오기

API로 데이터를 가져오기 위해선 요청할 때 인증이 필요합니다. 이때 앞서 설명한 토큰과 키가 필요합니다. 인증에 대한 내용은 아래 링크를 참고하면 됩니다.

https://developer.twitter.com/en/docs/twitter-ads-api/making-authenticated-requests

Making Authenticated Requests

 

본론으로 들어가, 개발 문서에서는 대부분의 설명을 Twurl을 바탕으로 설명하고 있습니다. Twurl은 curl과 비슷하지만, Twitter API용으로 특별히 조정된 커맨드 명령어 툴입니다. 하지만 API 요청과 동시에 데이터를 직접 가공하기 위해선 커맨드 명령어 툴로는 불편함이 있습니다. 따라서 API 호출 및 데이터 처리를 구조화해서 처리하기 위해 Python을 활용했습니다.

 

먼저 Twitter Ads API 엔드포인트에 액세스해야 합니다. 하지만 애플리케이션에선 인증된 요청만 허용하기 때문에 엔드포인트에 접근할 때 인증 요청도 같이 이뤄져야 합니다. 트위터 광고 API는 인증 OAuth 1.0A 헤더를 생성하는 작업이 필요하다고 언급합니다. 따라서 OAuth1 및 클라이언트를 구축하기 위한 사용하기 쉬운 파이썬 인터페이스를 제공하는 라이브러리 requests_oauthlib를 사용합니다.

(아래 코드 예시를 첨부합니다.)

import requests
from requests_oauthlib import OAuth1

url = 'https://...'

client_key = '...'
client_secret = '...'
resource_owner_key = '...'
resource_owner_secret = '...'

headeroauth = OAuth1(
    client_key,
    client_secret,
    resource_owner_key,
    resource_owner_secret,
    signature_type='auth_header'
)

r = requests.get(url, auth=headeroauth)

위 코드 예시를 간략히 설명하면, requests_oauthlib 라이브러리를 사용하여 OAuth1 헤더 인증을 생성하고 requests 요청할 때 auth인자로 같이 전달한다는 의미입니다.

 

설명한 예시를 활용하면 트위터 광고 API 엔드포인트로 액세스 할 수 있습니다. 위 인증 코드에 더불어 앞선 문단에서 얘기한 Synchronous Analytics 데이터를 가져오는 로직을 예시 코드와 함께 설명하겠습니다.

 

먼저 라이브러리입니다. 라이브러리는 인증 및 요청에 사용된 라이브러리에 더불어 데이터 가공에 사용되는 json 라이브러리를 더 사용합니다.

import requests
from requests_oauthlib import OAuth1

import json

그다음은 토큰입니다. 라이브러리 Docs와 트위터에서 언급하는 키와 토큰의 변수명이 달라 조금 생소할 수 있습니다. 주석을 참고하여 발급한 키와 토큰을 변수에 적용하면 됩니다. 관련해서 OS 환경변수를 활용하여 변수로 받는 등 좀 더 보안을 신경 써서 키와 토큰을 사용하는 방법도 있습니다.

consumer_key = '...'          #라이브러리 Docs의 client_key
consumer_secret = '...'       #라이브러리 Docs의 client_secret
access_token = '...'          #라이브러리 Docs의 resource_owner_key
access_token_secret = '...'   #라이브러리 Docs의 resource_owner_secret

account_id = '...'            #광고계정의 account_id

 

 

아래 내용은 API 요청에 필요한 URL, OAuth1 헤더 인증, 파라미터입니다. 헤더 인증은 위에서 설명한 것처럼 트위터에서 제공하는 토큰을 가지고 requests_oauthlib 라이브러리로 생성하면 됩니다. 여기서 자세히 살펴볼 부분은 파라미터입니다. 개발문서에 사용할 수 있는 파라미터의 목록들이 있습니다. 파라미터로 API 데이터 요청 시 필터 조건을 줄 수 있습니다.

url = f'https://ads-api.twitter.com/12/stats/accounts/{account_id}'

headeroauth = OAuth1(
    consumer_key,
    consumer_secret,
    access_token,
    access_token_secret,
    signature_type='auth_header'
)

params = {
    "account_id": f"{account_id}",
    "start_time": "2023-01-30",
    "end_time": "2023-01-31",
    "entity": "PROMOTED_TWEET",
    "entity_ids": [
    	"entity_id1",
        "entity_id2",
        "entity_id3",
	],
    "granularity": "DAY",
    "metric_groups": "ENGAGEMENT,BILLING,WEB_CONVERSION",
    "placement": "ALL_ON_TWITTER",
}

마지막으로 데이터 요청 및 가공입니다. 전 단계에서 준비한 URL, 헤더 인증, 파라미터를 requests 라이브러리로 요청합니다. 요청에 사용되는 HTTP 메서드의 경우 앤드포인트마다 다를 수 있습니다. Synchronous Analytics의 경우 GET 메서드를 활용합니다. 요청한 값을 변수에 저장하여 해당 변수를 확인했을 때 응답코드 200이 나오면 데이터 요청을 성공한 것입니다. 응답코드 200이 나오면 json 라이브러리를 통해 json으로 읽을 수 있도록 변환합니다. json으로 변환한 값은 개발문서의 응답 예시와 같이 출력됩니다. 응답 예시처럼 데이터가 잘 나온다면 이제 각자의 방식대로 데이터를 가공하면 됩니다.

r = requests.get(url, params, auth=headeroauth)

data = r.json()['data']

 

🏜️ 마무리하며

단계를 차근차근 따라하면 API로 데이터를 가져오는 것은 어렵지 않습니다. 모든 작업이 그렇겠지만, 작업에 가장 큰 어려움은 커뮤니케이션의 부재에서 발생합니다. 실제로 데이터를 필요로 하는 조직과 가공하는 조직의 이해도가 각기 달라 정말 필요한 값을 놓쳐 작업을 여러 번 하게 되는 등의 이슈가 발생할 수 있습니다. 문서를 자세히 읽어보고 데이터를 필요로 하는 조직과 꾸준히 커뮤니케이션하면서 작업을 한다면 큰 어려움 없이 작업을 수행할 수 있습니다. 해당 글을 통해 API 다루고, 협업하는데 큰 도움이 되면 좋겠습니다.