跳到主要内容

Apple Search Ads 数据集成解决方案

最近更新 2026/10/05

最近更新时间：2022-07-18

一、集成方案介绍​

提示

请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量

概要​

本文将介绍如何将 Apple Search Ads 的数据回传到 Agentic Engine（后文简称 AE 系统） ，本方案支持：

流程​

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

  1. 创建一个带有 API 权限的用户（如果已经存在这样的用户，可以跳过此步）

  2. 生成私钥与公钥，使用带有 API 权限的用户登录 Apple Search Ads 后台，上传公钥，并向 AE 工作人员提供：

    1. client_id
    2. team_id
    3. key_id
    4. 私钥文件

  3. 确定数据拉取的数据维度、指标类型、拉取频率以及拉取时间范围

  4. 由 AE 工作人员完成数据拉取开发工作

  5. 在 AE 后台搭建看板、报表，并完成数据验收

二、集成前准备工作​

在拉取 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
  1. 接着，在同一目录下，执行如下命令，生成公钥（公钥文件为 public-key.pem）
openssl ec -in private-key.pem -pubout -out public-key.pem
  1. 进入 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 向 AE 工作人员提供以下信息​

接下来，您需要将以下信息提供给 AE 工作人员

  • client_id
  • team_id
  • key_id
  • 与 ASA 后台配置公钥对应的私钥文件（private-key.pem）

接下来，将由 AE 工作人员完成 Access Token 的创建。

三、数据拉取​

接口基本信息

接口名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）：获取按天广告计划内「素材集级别」的数据报表

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

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

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

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 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 点拉取前一天的数据

五、联调测试​

在 AE 后台事件管理页面查看以下事件：

  • asa_campaign_level_data：到广告计划级别，更多维度和指标
  • asa_adgroup_level_data：到广告组级别，更细分析粒度
  • asa_keyword_level_data：关键词的投放效果数据
  • asa_creative_level_data：到广告素材级别，更细分析粒度
这篇文档对你有帮助吗？
本页内容