一、集成方案介绍

概要

本文将介绍如何将 Apple Search Ads 的数据回传到 Thinking Analytics (后文简称 TA 系统) ，本方案支持：

通过 Apple Search Ads Report API 回传聚合指标数据，数据中包含曝光、点击、安装、收入、成本指标

流程

Apple Search Ads 数据的接入流程如下：

创建一个带有 API 权限的用户（如果已经存在这样的用户，可以跳过此步）
生成私钥与公钥，使用带有 API 权限的用户登录 Apple Search Ads 后台，上传公钥，并向 TA 工作人员提供：
1. client_id
2. team_id
3. key_id
4. 私钥文件
确定数据拉取的数据维度、指标类型、拉取频率以及拉取时间范围
由 TA 工作人员完成数据拉取开发工作
在 TA 后台搭建看板、报表，并完成数据验收

二、集成前准备工作

在使用拉取 ASA 数据之前，首先需要生成 Access Token，整个流程分为以下几个步骤：

创建一个拥有 API 访问权限的用户
生成私钥与公钥，并将公钥上传到 ASA 后台
创建客户端密钥
请求访问令牌

2.1 创建拥有 API 访问权限的用户

管理员账号可以按照以下流程创建一个带有 API 权限的用户：

进入 Apple Search Ads UI，登录管理员账号
进入「Account Settings」-「User Management」（「账号设置」-「用户管理」）
点击「Invite Users」邀请一个在您的 ASA 组织内的用户
在「User Details」栏目，输入用户的姓名以及 Apple ID
在「User Access and Role」栏目，选择具有 API 访问权限的用户角色
点击「Send Invite」发送邀请邮件，受邀请用户会收到一份带有 secure code 的邮件，用户点击邮件中的 Apple 网址并输入 secure code 即可激活用户的账号

2.2 生成私钥与公钥

在命令行中输入以下命令，即可生成私钥（私钥文件为 private-key.pem）

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

接着，在同一目录下，执行如下命令，生成公钥（公钥文件为 public-key.pem）

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

进入 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

三、数据拉取

接口基本信息

接口名	API 类型	产品化	数据粒度	归因数据	成本数据	收益数据	展示数据	点击数据	转化数据
Reporting API	拉式	否	聚合数据		是		是	是	是

3.1 数据拉取规则

Apple Search Ads 的 Reporting API 提供了多种层级的数据报表，目前 TA 系统支持以下几个层级的数据拉取：

广告计划级别报告（Campaign-Level Reports）：获取按小时「广告计划级别」的数据报表

广告组级别报告（Ad Group-Level Reports）：获取按小时广告计划内「广告组级别」的数据报表

关键词级别报告（Keyword-Level Reports）：获取按小时广告计划内「关键词级别」的数据报表

素材集级别报告（Creative Set-Level Reports）：获取按小时广告计划内「素材集级别」的数据报表

默认情况下，在一次数据拉取任务中，我们将会同时拉取这四个层级的报表数据

3.2 接口参数

时间：
- 时间范围：可以拉取以天为单位
- 时间粒度：按天或按小时聚合（按小时）
- 时区：可以选择 UTC 时区或者 ASA 后台设置的时区

3.3 入库规则

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

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

四、数据集成配置信息模板

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在数数科技的客户成功经理，我们将根据该信息模板完成 Apple Search Ads 的数据拉取：

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

五、联调测试

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