跳到主要内容

ironSource 数据集成解决方案

最近更新 2026/10/05

最近更新日期：2022-08-17

一、概述​

提示

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

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

  • 使用 客户端 SDK 上报数据，可以实时获取收入数据，但是收入数据是估计值，与最终结算数据略有偏差
  • 使用 Impression Level Revenue API 获取更为准确的收入数据，但实时性较差 (T+1 可以获取收入数据，T+2 可以获取最终数据)
  • 使用 Reporting API 获取包括曝光、收益以及用户活跃等聚合的指标数据。

在开始接入 ironSource 之前，请确保您已经阅读 AE 系统数据规则，理解 AE 的数据结构。另外，建议您将拉取数据所需的信息交给我们的客户成功经理，格式可参考数据集成配置信息模板。

二、客户端 SDK 上报​

接口基本信息

接口名API 类型产品化数据粒度归因数据成本数据收益数据展示数据点击数据转化数据
ILR SDK客户端 SDK否用户级别是

Impression Level Revenue (ILR) SDK API 是 ironSource SDK 的实时收益接口，在 ironSource 客户端 SDK (Android、iOS、Unity SDK) 7.0.3 及之后的版本中提供。该接口可以在广告展示后，通过回调实时获取预估的收入数据，再配合 AE 客户端 SDK 进行上报，即可获取实时性很高的收益数据。

2.1 ironSource 配置​

为了开启 ILR SDK 的实时收入回传功能，您需要先登录 ironSource 后台，并在「My Account」-「API」页面中的「ARM SDK Postbacks」栏目中勾选「Enable ad revenue measurements (ARM) SDK postbacks」

2.2 AE 客户端 SDK 配置​

方案一（自动集成）：

提示

如果您接入的 AE SDK 版本为 2.8.0~2.8.1 ，推荐使用自动关联方案

如果您接入的 AE SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件

本方案是自动集成方案，请在初始化 AE 客户端 SDK 后调用以下代码开启，详情请参考安卓 SDK 三方数据 与 iOS SDK 三方数据

// 初始化 AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// 开启ironSource id关联
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_IRON_SOURCE);

// 初始化 ironSource SDK
// ...

本方案的原理就是内部自动注册 onImpressionSuccessEvent 回调，在收到回调之后，自动解析IronSourceImpressionData 中的参数，然后通过 AE SDK 发送事件 ta_ironSource_callback

方案二（手动集成）：

手动集成方案需要您实现 ImpressionData Listener，在其中加上 AE SDK 数据上报接口。以下是 Unity 的代码样例，实现 ImpressionSuccessEvent() 并将其挂载在 onImpressionSuccessEvent 上，在广告展示后触发回调，上报数据。如果希望了解各 SDK 的实现方式，请查看以下链接：

// 注册 ImpressionSuccessEvent，并在其中配置上报给 AE 数据的代码逻辑
private void ImpressionSuccessEvent(IronSourceImpressionData impressionData) {
    Debug.Log ("unity-script:  ImpressionSuccessEvent impressionData = " + impressionData);
    if (impressionData != null) {
        Dictionary<string, object> properties = new Dictionary<string, object>()
        {
            // 收入来源: 广告单元
            {"adUnit", impressionData.adUnit},
            // 收入来源: 广告渠道
            {"adNetwork", impressionData.adNetwork},
            // 收入来源: ironSource 实例名称
            {"instanceName", impressionData.instanceName},
            // 收入来源: ironSource 实例 ID
            {"instanceId", impressionData.instanceId},
            // Placement
            {"placement", impressionData.placement},
            // 货币类型
            {"currency", "USD"},
            // 收入
            {"revenue", impressionData.revenue},
            // 收入类型
            {"precision",impressionData.precision}
        };

        // 将收入数据上报到 AE，假设收入事件名称为 ironSource_sdk_postbacks
        ThinkingAnalyticsAPI.Track("ironSource_sdk_postbacks", properties);
    }
}

ironSource SDK Postbacks 回传字段列表如下，您也可以查看 ironSource 官网文档：

字段名描述数据类型
auctionId竞价唯一标识 IDString
adUnit展示的广告单元 (如：Rewarded Video、Interstitial、Banner)String
adNetwork广告媒体渠道名String
instanceName广告实例名String
instanceId广告实例 IDString
countryISO 3166-1 格式的国家（地区）编号String
placement广告版位String
revenue收入数据 (USD) ，该值可能为预估值，详情可参考 precision 字段的取值Double
precision

revenue 值的来源:

  • BID – 通过实时竞价获取的收入数据，准确值
  • RATE – 在 ironSource 后台人工为实例设置的费率 (instance rate)
  • CPM – 基于实例 (instance) 的历史数据计算的估计值
String
abironSource 后台配置的 A/B Test 标记String
segmentName用户被归到的流量分组名（即 Segment，在 ironSource 后台配置）String
lifetimeRevenue用户累计创造的收入值Double
encryptedCPM该字段只存在于 Meta Audience Network（即 Facebook Audience Network）的广告数据中String

三、Impression Level Revenue API​

接口基本信息

接口名API 类型产品化数据粒度归因数据成本数据收益数据展示数据点击数据转化数据
Impression Level Revenue API拉式否用户级别是是

Impression Level Revenue API 提供展示层级 (impression-level) 与用户层级(user level) 两类数据，其中展示层级的每条数据都是一次广告曝光，符合事件数据的意义；而用户层级的数据则是聚合了一个用户的终生指标，并不适合作为事件数据回传，并且由于该数据会不断变化，不适合 AE 系统处理分析，因此我们仅支持接入展示层级数据。

3.1 获取授权码以及 App Key​

在接入 Impression Level Revenue API 之前，您需要先获取授权码以及拉取数据项目的 App Key。

  1. 登录 ironSource 后台，点击右上角的用户菜单，进入到「My Account」页面的「Reporting API」标签页，将 Secret Key 与 Refresh Token 发送给 AE 工作人员：
  1. 接下来进入到 ironSource 后台「Ad Unit」页面，在「APPLICATIONS」列表中选中您想要接入的应用，在右侧卡片中将会展示该应用的 App Key，将其发送给 AE 工作人员或记录在数据集成配置信息模板中（注意 iOS 和安卓是分开的，如需接入两个平台的数据，需发送两个 App Key）

3.2 客户端 SDK 配置​

为了将 ironSource 用户数据与 AE 项目关联起来，需要使用 ironSource 的 setUserId() 方法将 AE 用户的 访客 ID 上报至 ironSource。以下示例代码以 Unity SDK 为例，将 AE 的访客 ID 设置为 ironSource 的 UserId：

// 将 AE 的访客 ID 设置为 IronSource 的 User ID
IronSource.Agent.setUserId(ThinkingAnalyticsAPI.GetDistinctId());
警告

AE 客户端 SDK 的默认访客 ID 取值如下：

  • 安卓端，AE SDK 的访客 ID 为 GAID，ironSource 的 advertising_id 取 GAID
  • iOS 端，AE SDK 的访客 ID 为 IDFV；ironSource 的 advertising_id 取 IDFA/IDFV

3.3 涵盖字段​

以下是 Impression Level Revenue API 返回的字段：

  • 维度字段
字段名描述取值举例
event_timestamp曝光时间戳2021-09-01 11:26:46
#zone_offset时区（AE 预置属性）0（定值）
advertising_id用户的广告 ID（GAID / IDFA）137cf2f0-609c-4ae3-ab64-ed5c0d7392fd
advertising_vendor_id

用户的 Vendor ID（app Set ID

/ IDFV）

A0810F0B-16C2-474B-B765-77B3A3113AA2
user_id用户设置的 User ID，即 3.2 设置的用户 IDc7d9fed7-aa40-4bfa-918f-8d4b155bfd4b
ad_unit广告单元rewarded_video
ad_network广告媒体Admob
instance_name实例名Bidding, High
country国家（地区）编号US
placement版位Home_Screen
segment用户被归到的流量分组名Tier 1
AB_TestingA/B Test 标签A,B
app_key应用 Key
app_name应用名称
platform平台iOS, android
  • 指标字段
字段名描述取值举例
impressions曝光数1000
revenue收益金额0.5

3.4 接口参数​

  • 时间：

    • 拉取以日为时间单位、UTC 时区的数据

      • 仅能拉取近 14 天的数据（比如 1 月 1 日的数据最晚保留到 1 月 14 日，之后拉取无数据）
      • 每天 UTC 时间下午 2 点（北京时间晚上 10 点）可以获取前一天（UTC 时区）的数据
      • 数据的修复只会作用于过去 2 天的数据（即昨天、前天），之后数据保持稳定、不再调整

3.5 数据入库规则​

默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中，一条展示数据写入一条事件数据：

  • 使用数据中的 user_id 作为数据中的访客 ID，该字段应可对应 AE 项目中的访客ID
  • 使用数据中的 event_timestamp 字段，即广告展示时间，作为事件的 #event_time
  • 数据事件名为 -- ironsource_ad_revenue_impression_level
  • 其他字段将全数入库

3.6 数据集成配置信息模板​

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

数据接口：ironSource Impression Level Revenue API
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
secretkey: XXX
refreshToken: XXX
---------
数据拉取配置
appKey：XXX, XXX(iOS, Android 分开)

历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd（仅支持拉取近 14 天的数据）
定时拉取：每天北京时间 22 点拉取前一天的数据

四、Reporting API​

接口基本信息

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

Reporting API 是 ironSource 的聚合指标数据接口，您可以通过该接口获得包括曝光、收益以及用户活跃等聚合的指标数据。

4.1 获取授权码​

在接入 Reporting API 之前，您需要先获取授权码。登录 ironSource 后台，点击右上角的用户菜单，进入到「My Account」页面的「Reporting API」标签页，将 Secret Key 与 Refresh Token 发送给 AE 工作人员：

4.2 涵盖字段​

以下是 Reporting API 返回的字段：

  • 维度字段

以下是 Reporting API 的分析维度，请注意，每个分析维度可以支持的指标都是不同的，具体对应关系，可以参考 ironSource 官网文档：

维度名字段名描述是否默认备注
datedate数据时间是
adUnitsadUnits广告单元是

app

appKey应用 Key是
bundleId应用 ID是
appName应用名是
platformplatform应用平台是
adSourceproviderName广告来源是
instanceinstanceName实例名与 segment, placement 互斥
instanceId实例 ID
countrycountryCode国家（地区）编号是
segmentsegment用户被归到的流量分组名与 instance, placement 互斥
placementplacement版位与 instance, segment 互斥
osVersionosVersion操作系统版本

最多四选一

connectionTypeconnectionType网络连接类型
sdkVersionsdkVersionSDK 版本
appVersionappVersion应用版本
attattATT 状态
idfaidfaIDFA 是否可用
abTestabTestA/B Test 标签
  • 指标字段

以下是 Reporting API 支持的指标列表。需要注意，可用指标会受到分析维度的影响，实际接收到的指标会少于下表所示内容：

字段名描述
revenue总收益
eCPMeCPM
appFillRate广告填充率（曝光数 / 请求数）
appRequests广告请求数
impressions曝光数
completions

完成数

  • 奖励视频：视频完播数
  • Offerwall：完成目标数
revenuePerCompletion平均完成收益额（收益 / 完成数）
appFills广告填充数
useRate广告曝光填充比
activeUsersDAU
engagedUsers广告互动用户数
engagedUsersRate广告互动用户占比
impressionsPerEngagedUser广告互动用户平均广告曝光数
revenuePerActiveUser即 ARPU 值（单位是美分）
revenuePerEngagedUser广告互动用户 ARPU 值（单位是美分）
clicks总点击数
clickThroughRate点击率（CTR）
completionRate完成特定行为的比例，即转化率
adSourceChecks广告源检查广告是否可用次数
adSourceResponses广告源产生响应次数
adSourceAvailabilityRate广告可用比例（曝光数 / 广告响应数）
sessionsSession 数
engagedSessions有广告互动的 Session 数
impressionsPerSession平均每 Session 曝光数
impressionPerEngagedSessions平均每次有广告互动的 Session 的曝光数
sessionsPerActiveUser平均每用户 Session 数

4.3 接口参数​

  • 时间：
    • 拉取以日为时间单位、UTC 时区的数据
  • 应用：
    • 可以指定拉取的应用（安卓和 iOS 端分开）

4.4 数据入库规则​

默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：

  • 由于 Reporting API 是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
  • 使用数据中的 date 字段，即数据时间，作为事件的 #event_time
  • 数据事件名为 -- ironsource_reporting_level
  • 其他字段将全数入库

4.5 数据集成配置信息模板​

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

数据接口：ironSource Reporting API
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
secretkey: XXX
refreshToken: XXX
---------
数据拉取配置
分析粒度：xxx，xxx（不填为使用默认）
拉取应用 Key：xxx，xxx（默认为全拉取）

历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取：每天 X 点拉取前一天的数据

五、数据校验​

可以在 AE 系统后台的「数据管理」—「事件管理」页面 或「SQL IDE」页面搜索以下事件是否入库：

  • 客户端 SDK 对应事件

    • ta_ironSource_callback（方案一）
    • ironSource_sdk_postbacks（方案二）

  • Impression Level Revenue API 对应事件

    • ironsource_ad_revenue_impression_level

  • Reporting API 对应事件

    • ironsource_reporting_level

六、FAQ​

6.1 客户端 SDK 上报和 Impression Level Revenue API 上报数据有何不同？​

  • 客户端 SDK 上报数据的及时性高，但准确性低
  • Impression Level Revenue API 数据会有一天的延迟，并且数据需要在第三天才稳定，因此及时性较低，但数据稳定后的准确性高。

6.2 为什么入库 AE 后的数据和 ironSource 后台 UI 的数据会有略微差异？​

  1. ironSource 只提供 UTC 时区的拉取，请检查您在 AE 后台设置的时区是否为 UTC
  2. 数据的略微差异可能是 ironSource API 的数据通道和 ironSource 后台 UI 数据通道的略微不同导致，比如：UI 的数据通道是从数据库 A-B，外加前端代码对小数的四舍五入逻辑；API 的数据通道是数据库 A-C；
这篇文档对你有帮助吗？
本页内容