Apple Search Ads 데이터 연동 솔루션

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

최종 업데이트 날짜: 2022-07-18

1. 통합 계획 소개

팁

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

개요

이 문서에서는 Apple Search Ads의 데이터를 Agentic Engine(이하 AE 시스템)으로 콜백하는 방법을 소개합니다. 이 계획은 다음을 지원합니다:

• Apple Search Ads Report API로 집계 지표 데이터를 콜백하며, 노출, 클릭, 설치, 비용 지표를 포함합니다

절차

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

1. API 권한이 있는 사용자를 생성합니다(이미 이러한 사용자가 있으면 이 단계를 건너뛸 수 있습니다)

2. 개인 키와 공개 키를 생성하고, API 권한이 있는 사용자로 Apple Search Ads 백엔드에 로그인하여 공개 키를 업로드한 후 ThinkingAI 담당자에게 다음 정보를 제공합니다:

   1. client_id
   2. team_id
   3. key_id
   4. 개인 키 파일

3. 수집할 데이터 차원, 지표 타입, 수집 빈도 및 수집 기간을 확정합니다

4. ThinkingAI 담당자가 데이터 수집 개발 작업을 완료합니다

5. AE 백엔드에서 대시보드와 리포트를 구축하고 데이터 검증을 완료합니다

2. 통합 전 준비 작업

ASA 데이터를 수집하기 전에 먼저 Access Token을 생성해야 합니다. 전체 절차는 다음 단계로 구성됩니다:

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

2.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를 입력하면 계정이 활성화됩니다

2.2 개인 키와 공개 키 생성

팁

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

1. 명령줄에 다음 명령을 입력하면 개인 키가 생성됩니다(개인 키 파일은 private-key.pem)

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

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

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

3. Apple Search Ads UI에 접속하여 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

2.3 ThinkingAI 담당자에게 다음 정보 제공

다음으로 아래 정보를 ThinkingAI 담당자에게 제공해야 합니다

• client_id
• team_id
• key_id
• ASA 백엔드에 설정한 공개 키에 대응하는 개인 키 파일(private-key.pem)

이후 ThinkingAI 담당자가 Access Token 생성을 완료합니다.

3. 데이터 수집

인터페이스 기본 정보

인터페이스명	API 타입	제품화	데이터 세분화	어트리뷰션 데이터	비용 데이터	수익 데이터	노출 데이터	클릭 데이터	전환 데이터
Reporting API	풀 방식	아니요	집계 데이터		예		예	예	예

3.1 데이터 수집 규칙

Apple Search Ads의 Reporting API는 여러 계층의 데이터 리포트를 제공하며, 현재 AE 시스템은 다음 계층의 데이터 수집을 지원합니다:

캠페인 수준 리포트(Campaign-Level Reports): 캠페인 수준의 시간별 데이터 리포트를 가져옵니다

광고 그룹 수준 리포트(Ad Group-Level Reports): 캠페인 내 광고 그룹 수준의 시간별 데이터 리포트를 가져옵니다

키워드 수준 리포트(Keyword-Level Reports): 캠페인 내 키워드 수준의 시간별 데이터 리포트를 가져옵니다

소재 세트 수준 리포트(Creative Set-Level Reports): 캠페인 내 소재 세트 수준의 일별 데이터 리포트를 가져옵니다

기본적으로 1회의 데이터 수집 작업에서 이 네 계층의 리포트 데이터를 동시에 수집합니다

3.2 인터페이스 파라미터

• 시간:

  • 기간: 일 단위로 데이터를 수집합니다
  • 시간 단위: 일별 또는 시간별 집계(시간별)
  • 시간대: UTC 시간대 또는 ASA 백엔드에 설정된 시간대를 선택할 수 있습니다

3.3 저장 규칙

3.3.1 Campaign 계층

• Campaign 계층 데이터는 집계 데이터이므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결되어 있다고 보면 됩니다
• 데이터의 date 필드, 즉 데이터의 날짜를 집계 데이터의 #event_time으로 설정합니다
• Campaign 계층 데이터의 데이터 이벤트 이름은 asa_campaign_level_data입니다
• 다음은 Campaign 계층의 저장 필드입니다

------------------------차원 필드------------------------
campaignId
campaignName
deleted
campaignStatus
app.adamId
servingStatus
servingStateReasons
countriesOrRegions
modificationTime
totalBudget.amount
totalBudget.currency
dailyBudget.amount
dailyBudget.currency
displayStatus
supplySources
adChannelType
orgId
countryOrRegionServingStateReasons
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

3.3.2 Ad Group 계층

• Ad Group 계층 데이터는 집계 데이터이므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결되어 있다고 보면 됩니다
• 데이터의 date 필드, 즉 데이터의 날짜를 집계 데이터의 #event_time으로 설정합니다
• Ad Group 계층 데이터의 데이터 이벤트 이름은 asa_adgroup_level_data입니다
• 다음은 Ad Group 계층 데이터의 저장 필드입니다

------------------------차원 필드------------------------
campaignId
adGroupId
adGroupName
adGroupDisplayStatus
adGroupStatus
adGroupServingStatus
adGroupServingStateReasons
deleted
cpaGoal
orgId
modificationTime
automatedKeywordsOptIn
pricingModel
defaultBidAmount.amount
defaultBidAmount.currency
------------------------지표 필드------------------------
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

3.3.3 Keywords 계층

• Keywords 계층 데이터는 집계 데이터이므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결되어 있다고 보면 됩니다
• 데이터의 date 필드, 즉 데이터의 날짜를 집계 데이터의 #event_time으로 설정합니다
• Keywords 계층 데이터의 데이터 이벤트 이름은 asa_keyword_level_data입니다
• 다음은 Keywords 계층 데이터의 저장 필드입니다

------------------------차원 필드------------------------
keywordId
keywordStatus
matchType
deleted
keywordDisplayStatus
adGroupId
adGroupDeleted
------------------------지표 필드------------------------
impressions
taps
installs
newDownloads
redownloads
latOnInstalls
latOffInstalls
ttr
avgCPA.amount
avgCPA.currency
avgCPT.amount
avgCPT.currency
localSpend.amount
localSpend.currency
conversionRate

3.3.4 Creative Set 계층

• Creative Set 계층 데이터는 집계 데이터이므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결되어 있다고 보면 됩니다
• 데이터의 date 필드, 즉 데이터의 날짜를 집계 데이터의 #event_time으로 설정합니다
• Creative Set 계층 데이터의 데이터 이벤트 이름은 asa_creative_level_data입니다
• 다음은 Creative Set 계층 데이터의 저장 필드입니다

------------------------차원 필드------------------------
creativeSetId
creativeSetName
displayStatus
creativeSetLanguageDisplayName
deleted
status
orgId
campaignId
adGroupId
adGroupCreativeSetId
creationTime
modificationTime
countryOrRegion
adFormat
------------------------지표 필드------------------------
impressions
taps
installs
newDownloads
redownloads
latOnInstalls
latOffInstalls
ttr
avgCPA.amount
avgCPA.currency
avgCPT.amount
avgCPT.currency
localSpend.amount
localSpend.currency
conversionRate

4. 데이터 연동 설정 정보 템플릿

위 문서를 읽은 후 다음 정보 템플릿을 작성하여 ThinkingAI의 고객 성공 매니저에게 보내는 것을 권장합니다. 저희는 이 정보 템플릿에 따라 Apple Search Ads의 데이터 수집을 완료합니다:

데이터 인터페이스: Apple Search Ads Report API
---------
AE 고객사 이름: XXX
AE 고객 프로젝트 이름: XXX
AE 프로젝트 환경: XXX (SAAS/프라이빗 배포)
AE 고객 프로젝트 app_id: XXX
AE 데이터 수신 주소 push_url: XXX
---------
keyId: XXX
clientId: XXX
teamId: XXX
orgId 목록: XXX
시간대: [UTC/ASA] 백엔드 설정 시간대
시간 단위: [일/시간](주의: 소재 세트 수준 리포트는 시간별 데이터 수집을 지원하지 않으며 일별 수집만 지원)
과거 데이터 수집 기간: yyyy/mm/dd - yyyy/mm/dd
정기 수집: 매일 X시에 전날 데이터 수집

5. 연동 테스트

AE 백엔드의 이벤트 관리 페이지에서 다음 이벤트를 확인합니다:

• asa_campaign_level_data: 캠페인 수준까지의 데이터로, 차원과 지표가 더 많습니다
• asa_adgroup_level_data: 광고 그룹 수준까지의 데이터로, 분석 단위가 더 세분화됩니다
• asa_keyword_level_data: 키워드의 광고 집행 성과 데이터
• asa_creative_level_data: 광고 소재 수준까지의 데이터로, 분석 단위가 더 세분화됩니다