最全面的Apple Search Ads Report API接入和數據拉回指南

茄子妹妹

發佈時間: 2023-02-27 01:54:17

更新時間: 2023-02-27 02:39:30

一、集成方案介紹

本文將介紹如何將 Apple Search Ads 的數據回傳到自己內部系統，本方案支持：通過 Apple Search Ads Report API 回傳聚合指標數據，數據中包含曝光、點擊、安裝、收入、成本指標等數據。

Apple Search Ads 數據的接入流程如下：

  1. 創建一個帶有 API 權限的用戶（如果已經存在這樣的用戶，可以跳過此步）
  2. 生成私鑰與公鑰，使用帶有 API 權限的用戶登錄 Apple Search Ads 後臺，上傳公鑰，並向 TA 工作人員提供：client_id；team_id；key_id；私鑰文件
  3. 確定數據拉取的數據維度、指標類型、拉取頻率以及拉取時間範圍
  4. 完成數據拉取開發工作
  5. 搭建看板、報表，並完成數據驗收

二、集成前準備工作

2.1 授權總流程

在使用拉取 ASA 數據之前，首先需要生成 Access Token，整個流程分爲以下幾個步驟：

  1. 創建一個擁有 API 訪問權限的用戶
  2. 生成私鑰與公鑰，並將公鑰上傳到 ASA 後臺
  3. 創建客戶端密鑰
  4. 請求訪問令牌

2.2 邀請用戶

管理員賬號可以按照以下流程創建一個帶有 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.3 生成私鑰與公鑰

如果您使用的是 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.4 提供以下信息完成Access Token的創建

  • client_id
  • team_id
  • key_id
  • 與 ASA 後臺配置公鑰對應的私鑰文件（private-key.pem）

接下來完成 Access Token 的創建。

三、數據拉取

接口基本信息

接口名API 類型產品化數據粒度歸因數據成本數據收益數據展示數據點擊數據轉化數據
彙報 API 拉式 否聚合數據是是是是是是

3.1 數據拉取規則

Apple Search Ads 的 Reporting API 提供了多種層級的數據報表，我目前嘗試過以下幾個層級的數據拉取，也可以給各位讀者參考：

廣告計劃級別報告（Campaign-Level Reports）：獲取按小時「廣告計劃級別」的數據報表

廣告組級別報告（Ad Group-Level Reports）：獲取按小時廣告計劃內「廣告組級別」的數據報表

關鍵詞級別報告（Keyword-Level Reports）：獲取按小時廣告計劃內「關鍵詞級別」的數據報表

素材集級別報告（Creative Set-Level Reports）：獲取按小時廣告計劃內「素材集級別」的數據報表

默認情況下，在一次數據拉取任務中，我會同時拉取這四個層級的報表數據

3.2 接口參數

時間：

  • 時間範圍：可以拉取以天爲單位
  • 時間粒度：按天或按小時聚合（按小時）
  • 時區：可以選擇  UTC 時區或者 ASA 後臺設置的時區

3.3 入庫規則

1. Campaign 層級

  • Campaign 層級數據是聚合數據，因此我將使用一個固定值作爲其用戶標識，您可以認爲所有數據掛載在一個虛擬用戶上
  • 使用數據中的 date 字段，即數據的日期，設置爲聚合數據的 #event_time
  • Ad Group 層級數據的數據事件名爲 -- 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

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. 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

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

四、數據集成配置信息模板

在閱讀完以上文檔之後，你將收集到以下相關的信息，此時可以完成Apple Search Ads 的數據拉取：

数据接口： Apple Search Ads Report API
---------
数据接收地址 push_url: XXX
---------
keyId: XXX
clientId: XXX
teamId: XXX
orgId 列表: XXX
时区：[UTC/ASA] 后台配置时区
时间粒度：[天/小时]（注意：素材集级别报告不支持每小时的数据拉取，仅支持按天拉取）
历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取：每天 X 点拉取前一天的数据

五、聯調測試

拉回數據後，可以上報至自己目前在使用的數據系統，在系統或者數據看板上可以看到以下事件：

- asa_campaign_level_data：到廣告計劃級別，更多維度和指標

- asa_adgroup_level_data：到廣告組級別，更細分析粒度

- asa_keyword_level_data：關鍵詞的投放效果數據

- asa_creative_level_data：到廣告素材級別，更細分析粒度

HTML Sitemap
聯絡我們: chachingtech123@gmail.com