Apple Search Ads 통합 계획

최근 업데이트 2026. 10. 05.

이 문서에서는 AE 백엔드에서 Apple Search Ads 데이터를 연동하는 방법을 소개합니다. 현재 AE 백엔드에서 연동을 지원하는 것은 Apple Search Ads의 Reporting API입니다.

AE 4.2 이전 버전을 사용 중인 경우 Apple Search Ads 데이터 연동 솔루션을 참고하여 데이터를 연동하십시오

팁

서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다

개요

인터페이스 소개

인터페이스명	타입	세분화	어트리뷰션	비용	수익	노출	클릭	전환
Reporting API	API	집계 데이터		✅		✅	✅	✅

Apple Search Ads의 Reporting API는 캠페인(Campaign-Level)부터 광고(Ad-Level)까지 여러 계층의 데이터 리포트를 제공하며, 현재 AE 시스템은 다음 계층의 데이터 수집을 지원합니다:

• Campaign 계층 리포트(Campaign-Level Reports)
• Ad Group 계층 리포트(Ad Group-Level Reports)
• Keyword 계층 리포트(Keyword-Level Reports)

Apple Search Ads의 기능 변경으로 인해 Creative Set 계층 리포트(Creative Set-Level Reports)는 더 이상 지원되지 않으며, 기존 설정이 작동하지 않을 수 있으니 유의하십시오

통합 절차

Apple Search Ads 데이터 연동 절차는 다음과 같습니다:

1. Apple Search Ads API 인증을 완료합니다
2. AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 Apple Search Ads 통합 계획을 추가하고 관련 설정을 완료합니다
3. AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다

1. Apple Search Ads API 인증 완료

ASA 데이터를 연동하기 전에 먼저 ASA 인증 작업을 완료해야 합니다. 전체 절차는 다음 단계로 구성됩니다:

1. API 액세스 권한이 있는 사용자를 생성합니다
2. 개인 키와 공개 키를 생성하고 공개 키를 ASA 백엔드에 업로드합니다
3. 클라이언트 시크릿(Client Secret)을 생성합니다
4. 액세스 토큰(Access Token)을 요청합니다

Apple Search Ads의 공식 문서를 직접 참고하여 인증 작업을 완료할 수 있습니다. 또는 이 절의 절차에 따라 인증을 완료할 수도 있으며, 다음 내용은 모두 해당 공식 문서에서 가져온 것입니다.

1.1 API 액세스 권한이 있는 사용자 생성

먼저 관리자 계정으로 로그인하고 다음 절차에 따라 API 권한이 있는 사용자를 생성해야 합니다:

1. Apple Search Ads UI에 접속하여 관리자 계정으로 로그인합니다
2. Account Settings - User Management(계정 설정 - 사용자 관리)로 이동합니다
3. Invite Users를 클릭하여 ASA 조직 내 사용자를 초대합니다
4. User Details 섹션에서 사용자의 이름과 Apple ID를 입력합니다
5. User Access and Role 섹션에서 API 액세스 권한이 있는 사용자 역할을 선택합니다
6. Send Invite를 클릭하여 초대 이메일을 보냅니다. 초대받은 사용자는 secure code가 포함된 이메일을 받으며, 이메일의 Apple 링크를 클릭하고 secure code를 입력하면 계정이 활성화됩니다

1.2 개인 키와 공개 키를 생성하고 공개 키를 ASA 백엔드에 업로드

다음으로 코드를 통해 개인 키와 공개 키를 생성해야 합니다. 이 절은 어느 정도의 기술적 배경 지식이 필요합니다. 개발자가 아닌 경우 개발자 또는 ThinkingAI 담당자에게 문의하여 이 단계를 완료하십시오

팁

Windows 시스템을 사용하는 경우 OpenSSL을 다운로드하여 설치하십시오

1. 명령줄에 다음 명령을 입력하여 private-key.pem이라는 개인 키 파일을 생성합니다

openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem

1. 이어서 같은 디렉터리에서 다음 명령을 실행하여 public-key.pem이라는 공개 키 파일을 생성합니다

openssl ec -in private-key.pem -pubout -out public-key.pem

1. Apple Search Ads UI에 접속하여 이전 단계에서 생성한 API 권한이 있는 사용자로 로그인합니다. Account Settings - API를 선택하고 공개 키를 Public Key 영역에 복사합니다. 저장을 클릭하면 Public Key 영역 위에 clientId, teamId, keyId가 표시됩니다. 다음은 데이터 예시입니다:

clientId SEARCHADS.aeb3ef5f-0c5a-4f2a-99c8-fca83f25a9
teamId SEARCHADS.hgw3ef3p-0w7a-8a2n-77c8-scv83f25a7
keyId a273d0d3-4d9e-458c-a173-0db8619ca7d7

1.3 클라이언트 시크릿 생성

다음으로 코드를 통해 클라이언트 시크릿을 생성해야 합니다. 이 절은 어느 정도의 기술적 배경 지식이 필요합니다. 개발자가 아닌 경우 개발자 또는 ThinkingAI 담당자에게 문의하여 이 단계를 완료하십시오.

Apple Search Ads의 클라이언트 시크릿은 JSON web token(JWT)입니다. 공식적으로 Python 3 코드 예시가 제공되므로, 의존 라이브러리를 설치한 후 다음 코드를 실행하여 클라이언트 시크릿을 생성하십시오:

import os
import datetime as dt
from authlib.jose import jwt
from Crypto.PublicKey import ECC

# 개인 키와 공개 키 파일을 py 파일과 같은 디렉터리에 두는 것을 권장합니다
private_key_file = "private-key.pem"
public_key_file = "public-key.pem"

# 이전 단계에서 가져온 clientId, teamId, keyId로 바꿔야 합니다
client_id = "SEARCHADS.9703f56c-10ce-4876-8f59-e78e5e23a152"
team_id = "SEARCHADS.9703f56c-10ce-4876-8f59-e78e5e23a152"
key_id = "d136aa66-0c3b-4bd4-9892-c20e8db024ab"

audience = "https://appleid.apple.com"
alg = "ES256"


# 개인 키 파일이 없으면 개인 키 파일을 생성합니다
if os.path.isfile(private_key_file):
    with open(private_key_file, "rt") as file:
        private_key = ECC.import_key(file.read())
else:
    private_key = ECC.generate(curve='P-256')
    with open(private_key_file, 'wt') as file:
        file.write(private_key.export_key(format='PEM'))


# 공개 키 파일이 없으면 공개 키 파일을 생성합니다
public_key = private_key.public_key()
if not os.path.isfile(public_key_file):
    with open(public_key_file, 'wt') as file:
        file.write(public_key.export_key(format='PEM'))


# 현재 타임스탬프를 가져옵니다
issued_at_timestamp = int(dt.datetime.utcnow().timestamp())
# 만료 시간을 정의합니다. 180일을 초과할 수 없으며, 초과하면 Client Secret이 무효화됩니다
expiration_timestamp = issued_at_timestamp + 86400*180


# JWT headers를 정의합니다.
headers = dict()
headers['alg'] = alg
headers['kid'] = key_id


# JWT payload를 정의합니다.
payload = dict()
payload['sub'] = client_id
payload['aud'] = audience
payload['iat'] = issued_at_timestamp
payload['exp'] = expiration_timestamp
payload['iss'] = team_id


# 개인 키 내용을 가져옵니다
with open(private_key_file, 'rt') as file:
    private_key = ECC.import_key(file.read())


# JWT를 인코딩하고 개인 키로 서명합니다
client_secret = jwt.encode(
    header=headers,
    payload=payload,
    key=private_key.export_key(format='PEM')
).decode('UTF-8')


# Client secret을 파일에 기록합니다
with open('client_secret.txt', 'w') as output:
     output.write(client_secret)

위 코드에서 다음 사항에 유의해야 합니다:

1. 이전 단계에서 생성한 개인 키와 공개 키 파일을 .py 파일과 같은 디렉터리에 두거나, 코드에서 개인 키와 공개 키 파일의 경로를 수정합니다
2. 이전 단계에서 가져온 clientId, teamId, keyId로 코드의 해당 위치를 바꿉니다

이어서 이 코드를 실행하면 클라이언트 시크릿이 해당 디렉터리의 client_secret.txt 파일에 기록됩니다. 이 정보를 기록해 두십시오. 다음은 클라이언트 시크릿의 예시입니다:

eyJraWQiOiJiYWNhZWJkYS1lMjE5LTQxZWUtYTkwNy1lMmMyNWIyNGQxYjIiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJEcmVhbWNvbXBhbnkiLCJhdWQiOiJBdXRoZW50aWNhdG9yIiwiZXhwIjoxNTcxNjcwNjIxLCJuYmYiOjE1NzE2NjcwMjEsInN1YiI6Im11c3RlciIsImNsaWVudF9pZCI6ImFiY2QxMjM0IiwiYWRtaW4iOiJ0cnVlIn0.s4C3p9kVNFeRAB5tChatC3ldQX07v9mG7thL7FeEO6cClfNuiaLSgq8f8ymbfO3OQYW_KuwaA1KYRuoy1JmKk 4DBbYLcz6aoABe0pzI5Z_6wgMzAyqz8pQtwDAcd4Idoi8JdRbtzZce9o-0nZiFA4hVAXqYwpEYC4UU8ZmJO_z8tY4juHPTV3nDugdtqyNnmAiBoLryOfGNngQZccdY1_QvkXS1y0bg1a0k8cVVtnq- _93fYJIt9Z64CTvlH3uOeh7uaEv3nIxpXhvhkTySpUmY8e04TO09oTyZijiloByv3KFQ92OOJ8L 5N5_CeEc5p9LWjT1pcX8ATamOycZz2Q

1.4 Org ID 가져오기

마지막으로 Org ID, 즉 ASA 백엔드의 Campaign Group ID를 가져와야 합니다. ASA 백엔드에서 확인할 수 있으며, 아래 그림에서 빨간 상자로 표시한 ID입니다:

1.5 필요한 정보

마지막으로 위 인증 절차에서 다음 정보를 가져와 기록했는지 확인하십시오:

• client_id
• org_id
• client_secret

2. 계획 설정

ASA 인증 작업을 완료한 후 AE 시스템에 로그인하여 서드파티 통합 모듈에서 새 계획을 설정할 수 있습니다. 다음은 ASA 설정 화면입니다. 이 장의 내용에 따라 계획을 생성하십시오:

2.1 인증 정보 설정

인증 정보 아래의 인증 정보 설정 버튼을 클릭하고, 팝업 창에 인증 작업에서 가져온 정보를 입력합니다

여기서 Org ID는 Apple Search Ads 백엔드의 Campaign Group ID입니다(확인 방법은 1.4 참고)

2.2 동기화

동기화 모듈에서 AE 시스템이 ASA 데이터를 정기적으로 수집하는 전략을 설정할 수 있으며, 매일 특정 시각 또는 매시간 일정 기간의 데이터를 수집하도록 선택할 수 있습니다. 수집한 데이터도 데이터량에 포함되므로 너무 긴 기간의 데이터를 정기적으로 수집하지 않는 것을 권장합니다. Reporting API에서 가져올 수 있는 기간은 최대 과거 1000일이며, 1회 최대 31일까지 가져올 수 있습니다. 동기화 아래에는 데이터 수집 시간대 항목도 있으며, 기본값은 ORTZ입니다.

2.3 저장 설정

ASA 데이터를 이벤트 형태로 기록할지 여부를 제어할 수 있습니다. ASA 데이터는 이벤트 테이블에만 기록되므로 이 설정을 끄지 마십시오.

2.4 통합 설정

마지막으로 통합 설정 모듈에서 데이터 수집의 세부 설정을 제어할 수 있습니다. 데이터의 시간 집계 단위, 수집할 지표 필드와 차원, 저장 후 이벤트 이름 등이 포함됩니다.

통합 설정의 내용은 JSON이며, 다음 내용에 따라 커스텀 설정할 수 있습니다:

모듈	이름	의미
sink_event	event_name	저장 후 이벤트 이름, 커스텀 가능
	event_mapping	계층별로 저장 후 이벤트 이름을 지정. key는 report_types의 계층 이름, value는 저장 후 이벤트 이름이며 사용법은 2.4.4 참고. 새 계획 생성 시 기본 설정은 event_mapping을 사용
source	time_granularity	데이터의 시간 집계 단위, 즉 수집한 데이터를 일 단위로 집계할지 시간 단위로 집계할지 여부 선택 가능한 값: day, hour
	report_types	데이터를 수집할 계층, 리스트 타입. 요소를 하나만 입력하여 한 번에 한 계층의 데이터만 수집할 것을 권장 선택 가능한 값: campaign, ad_group, keyword
	metrics	데이터의 지표, 리스트 타입. 계층마다 지원하는 metrics가 다르므로 입력 시 주의 필요
	group_by	데이터의 그룹 차원, 리스트 타입. 계층마다 지원하는 group_by가 다르므로 입력 시 주의 필요
transfer	double_columns	숫자 타입 필드 정의, 리스트 타입. 여기에 입력한 필드는 숫자 타입으로 저장됨. 새 계획 생성 시 기본 설정에 impressions, taps, installs 등 지표 필드가 이미 나열되어 있음

계층마다 데이터 설정이 크게 다르므로 각 계층의 설정 템플릿을 그대로 사용하거나 템플릿을 약간 조정하여 사용하는 것을 권장합니다.

2.4.1 Campaign 계층 템플릿

Campaign 계층 리포트의 템플릿은 다음과 같습니다:

{
  "sink_event": {
    "event_name": "asa_campaign_level_data"
  },
  "source": {
    "time_granularity": "hour",
    "group_by": [
      "countryOrRegion"
    ],
    "report_types": [
      "campaign"
    ]
  }
}

• 템플릿의 시간 단위는 시간별이며, 시스템은 데이터의 date 필드, 즉 데이터의 날짜+시간을 데이터의 시간으로 사용합니다
• 템플릿에서 사용하는 이벤트 이름은 -- asa_campaign_level_data입니다
• 다음은 Campaign 계층 리포트의 저장 필드입니다

------------------------차원 필드------------------------
campaignid
campaignname
deleted
campaignstatus
app_adamid
app_appname
servingstatus
servingstatereasons
countriesorregions
modificationtime
totalbudget_amount
totalbudget_currency
dailybudget_amount
dailybudget_currency
displaystatus
supplysources
adchanneltype
orgid
countryorregionservingstatereasons
countryorregion
billingevent
------------------------지표 필드------------------------
impressions
taps
installs
newdownloads
redownloads
latoninstalls
latoffinstalls
ttr
avgcpa_amount
avgcpa_currency
avgcpt_amount
avgcpt_currency
avgcpm_amount
avgcpm_currency
localspend_amount
localspend_currency
conversionrate

2.4.2 Ad Group 계층 템플릿

• Ad Group 계층 리포트의 템플릿은 다음과 같습니다:

{
  "sink_event": {
    "event_name": "asa_adgroup_level_data"
  },
  "source": {
    "time_granularity": "hour",
    "group_by": [
      "countryOrRegion"
    ],
    "report_types": [
      "ad_group"
    ]
  }
}

• 템플릿의 시간 단위는 시간별이며, 시스템은 데이터의 date 필드, 즉 데이터의 날짜+시간을 데이터의 시간으로 사용합니다
• 템플릿에서 사용하는 이벤트 이름은 -- asa_adgroup_level_data입니다
• 다음은 Ad Group 계층 리포트의 저장 필드입니다

------------------------차원 필드------------------------
campaignid
adgroupid
adgroupname
adgroupdisplaystatus
adgroupstatus
adgroupservingstatus
adgroupservingstatereasons
deleted
cpagoal
orgid
modificationtime
pricingmodel
defaultbidamount_amount
defaultbidamount_currency
countryorregion
------------------------지표 필드------------------------
impressions
taps
installs
newdownloads
redownloads
latoninstalls
latoffinstalls
ttr
avgcpa_amount
avgcpa_currency
avgcpt_amount
avgcpt_currency
avgcpm_amount
avgcpm_currency
localspend_amount
localspend_currency
conversionrate

2.4.3 Keyword 계층 템플릿

• Keyword 계층 리포트의 템플릿은 다음과 같습니다:

{
  "sink_event": {
    "event_name": "asa_keyword_level_data"
  },
  "source": {
    "time_granularity": "hour",
    "group_by": [
      "countryOrRegion"
    ],
    "report_types": [
      "keyword"
    ]
  }
}

• 템플릿의 시간 단위는 시간별이며, 시스템은 데이터의 date 필드, 즉 데이터의 날짜+시간을 데이터의 시간으로 사용합니다
• 템플릿에서 사용하는 이벤트 이름은 -- asa_keyword_level_data입니다
• 다음은 Keyword 계층 리포트의 저장 필드입니다

------------------------차원 필드------------------------
keywordid
keyword
keywordstatus
matchtype
bidamount_amount
bidamount_currency
deleted
keyworddisplaystatus
adgroupid
adgroupname
adgroupdeleted
modificationtime
countryorregion
------------------------지표 필드------------------------
impressions
taps
installs
newdownloads
redownloads
latoninstalls
latoffinstalls
ttr
avgcpa_amount
avgcpa_currency
avgcpt_amount
avgcpt_currency
avgcpm_amount
avgcpm_currency
localspend_amount
localspend_currency
conversionrate

2.4.4 다중 계층 템플릿

한 번에 여러 계층의 데이터를 수집하려면 다음 템플릿을 사용하는 것을 권장합니다. 주요 변경 사항은 다음과 같습니다:

1. report_types에 수집할 계층 이름을 입력합니다
2. event_mapping으로 여러 계층의 이벤트 이름을 관리합니다. event_mapping의 각 요소에서 key는 report_types의 계층 이름에 대응하고, value는 저장 후 이벤트 이름입니다
3. 각 계층의 데이터는 동일한 설정, 즉 같은 time_granularity, group_by로 수집됩니다

{
  "sink_event": {
    "event_mapping":{
          "campaign": "asa_campaign_level_data",
          "ad_group": "asa_adgroup_level_data",
          "keyword": "asa_keyword_level_data"
     }
  },
  "source": {
    "time_granularity": "hour",
    "group_by": [
      "countryOrRegion"
    ],
    "report_types": [
      "campaign",
      "ad_group",
      "keyword"
    ]
  }
}

2.5 표준화 필드

다음은 Apple Search Ads의 표준화 필드입니다:

원본 필드	표준화 필드	의미
orgid	te_ads_object.ad_account_id	광고 계정 ID
campaignname	te_ads_object.campaign_name	캠페인 이름
campaignid	te_ads_object.campaign_id	캠페인 ID
adgroupname	te_ads_object.ad_group_name	광고 그룹 이름, 수익화 광고의 Unit 이름
adgroupid	te_ads_object.ad_group_id	광고 그룹 ID, 수익화 광고의 Unit ID
adname	te_ads_object.ad_name	광고 이름
adid	te_ads_object.ad_id	광고 ID
app_adamid	te_ads_object.app_id	앱 ID
app_appname	te_ads_object.app_name	앱 이름
iOS(고정값)	te_ads_object.platform	플랫폼(Android, iOS 등)
countryorregion	te_ads_object.country	국가/지역 코드
localspend_currency	te_ads_object.currency	비용 또는 수익의 통화
impressions	te_ads_object.impressions	노출 수
taps	te_ads_object.clicks	클릭 수
installs	te_ads_object.installs	전환 수(설치)
localspend_amount	te_ads_object.cost	UA 비용

3. 후속 사용

3.1 데이터 저장 확인

데이터 관리 페이지에서 콜백 이벤트가 저장되었는지 확인할 수 있습니다:

• asa_campaign_level_data: Campaign 계층 데이터
• asa_adgroup_level_data: Ad Group 계층 데이터
• asa_keyword_level_data: Keyword 계층 데이터

3.2 단일 수집

과거 데이터나 수집에 실패한 데이터를 보완하는 등 이전 일정 기간의 데이터를 연동하려면, 계획을 저장한 후 계획 페이지에 다시 들어가 오른쪽 상단의 단일 수집 버튼을 클릭하여 지정한 기간의 데이터를 한 번 수집할 수 있습니다. 수집하는 데이터의 기간이 이전과 겹치는 경우, 예를 들어 2023-08-01 데이터를 수집했는데 이 날짜의 데이터를 이전에 이미 수집한 적이 있다면 가장 최근에 수집한 데이터가 이전 데이터를 덮어씁니다: