ironSource Impression Level Revenue API

TIP

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

概要

接口简介

接口名	类型	粒度	归因	成本	收益	展示	点击	转化
Impression Level Revenue API	API	用户数据			✅	✅

Impression Level Revenue API (opens new window) 提供用户粒度的广告展示数据，您可以从这些数据中分析每个用户的收益情况以及不同用户的广告展示情况。

集成流程

1. 在 ironSource SDK 中设置 TE SDK 的用户识别字段
2. 登录 ironSource 后台，获得 App Key、Secret Key 与 Refresh Token
3. 登录 TE 后台，进入三方集成模块，新增 ironSource Impression Level Revenue API 方案，并完成相关配置
4. 查看 TE 系统否成功接收数据，并完成报表搭建

一、客户端 SDK 配置

为了将 ironSource 用户数据与 TE 项目关联起来，需要使用 IronSource 的 setUserId() 方法将 TE 的访客 ID 设置为 IronSource 的 UserId：

1.1 方案一（自动集成）

• 如果您接入的 Android、iOS SDK
  • SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
  • SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考 安卓 SDK 对接文档 与 iOS SDK 对接文档
• 如果您接入的 Unity SDK 版本为 2.4.0 及以上 ，Unreal SDK 版本为 1.5.0 及以上可以直接使用本方案

WARNING

请注意 TE SDK初始化需要在 IronSource的SDK初始化之前完成，并在IronSource的SDK初始化后立即开启自动集成代码。请按照以下步骤操作：

1. 初始化 TE SDK。

2. 初始化 IronSource SDK

3. 调用enableThirdPartySharing 自动设置访客 ID。

以下各端 SDK 的代码样例：

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、初始化 IronSource SDK
//  。。。
// 3、调用 enableThirdPartySharing 接口设置 ta_distinct_id 到 IronSource 事件中
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.IRON_SOURCE);

// 1、初始化 iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、初始化 IronSource SDK
//  。。。
// 3、调用 enableThirdPartySharing 接口 设置 ta_distinct_id 到 ironSource 事件中
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeIronSource];

// 1、初始化 Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2、初始化 ironSource SDK
//  。。。
//3、调用 enableThirdPartySharing 接口 设置 ta_distinct_id 到 IronSource 事件中
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.IRONSOURCE);

// 1、初始化 Unreal SDK
UTDAnalytics::Initialize();
// 2、初始化 ironSource SDK
//  。。。
// 3、调用 enableThirdPartySharing 设置 ta_distinct_id 到 IronSource 事件中
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeIRONSOURCE"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID);

1.2 方案二（手动集成）

手动集成方案，需要您在 IronSource SDK 中使用 setUserId() 接口设置 TE 项目的访客 ID 。

WARNING

请注意 TE 的 SDK 初始化和调用 setUserId 接口必须在 IronSource 的 SDK 初始化之后完成，请按照以下步骤操作：

1. 初始化 TE SDK。

2. 初始化 IronSource SDK。

3. 调用setUserId 设置访客 ID。

以下各端 SDK 手动集成代码样例：

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、初始化 ironSource SDK
//  。。。
// 3、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
String distinctId = TDAnalytics.getDistinctId();
// 4、 将 TE 的访客 ID 设置为 IronSource 的 User ID
IronSource.setUserId(distinctId);

// 1、初始化 iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、初始化 IronSource SDK
//  。。。

// 3、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
NSString *distinctId = [TDAnalytics getDistinctId];
// 4、将访客ID设置到 ironSource 采集事件中
[IronSource setUserId:distinctId];

// 1、初始化 Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);

// 2、初始化 ironSource SDK
//  。。。
// 3、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
var distinctId = TDAnalytics.GetDistinctId();
// 4、将访客ID设置到 ironSource 采集事件中
IronSource.Agent.setUserId(distinctId);

二、获得授权信息

接下来您需要登录 ironSource 后台，获取必要的授权信息

1. 首先，点击右上角的用户菜单，进入到「My Account」页面的「Reporting API」标签页，获取 Secret Key 与 Refresh Token

2. 接下来，进入到 ironSource 后台「Ad Unit」页面，在「APPLICATIONS」列表中选中您想要接入的应用，在右侧卡片中将会展示该应用的 App Key，将其记录下来（注意 iOS 和安卓是分开的，如需接入两个平台的数据，需要配置两个方案，并输入各自的 App Key）

三、方案配置

完成 SDK 配置后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成 ironSource Impression Level Revenue API 的配置。下图是 ironSource 的配置界面：

3.1 授权信息配置

点击「授权信息」按钮，在弹出框内填写您在授权工作中获取到的信息

3.2 定时拉取

您可以在「定时拉取」模块设置 TE 系统定时拉取 ironSource Impression Level Revenue API 数据的策略，可以选择在每天的某时或者每小时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据

3.3 用户识别字段

由于 ironSource Impression Level Revenue API 的是用户级别数据，因此需要为其设置用户识别规则。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。

如果您按照本文档进行客户端 SDK 配置，请使用以下配置：

• 账号 ID 关联字段：无
• 访客 ID 关联字段：user_id
  

3.4 事件表入库设置

打开「事件表入库设置」开关后，回传的数据都将写入到事件表中，我们建议您开启事件数据入库。

3.5 用户属性入库规则

在默认情况下，TE 系统不会将 ironSource Impression Level Revenue API 数据写入到用户属性中。如果您希望将一些字段写入用户表，请首先打开规则，使其运行，再通过属性映射功能添加需要写入用户表的字段，来源属性名需填写字段的入库名：

3.6 集成配置

您可以在集成配置模块对数据拉取的细节配置进行控制。比如入库后的事件名等。

集成配置是一个 JSON，你可以按照需要对其中的内容进行调整

模块	名称	含义
sink_event	event_name	入库后的事件名，可以自定义
transfer	double_columns	会被转化为数值类型的指标字段，其他入库字段均将以字符串类型入库，不建议调整

3.7 数据入库规则

• 使用数据中的 user_id 作为数据中的访客 ID，该字段应可对应 TE 项目中的访客ID
• 使用数据中的 event_timestamp 字段，即广告展示时间，作为事件的 #event_time
• 数据事件名为 -- ironsource_ad_revenue_impression_level
• 其他字段将全数入库，以下是 Impression Level Revenue API 返回的字段：
• 维度字段

字段名	描述	取值举例
event_timestamp	曝光时间戳	2021-09-01 11:26:46
#zone_offset	时区（TE 预置属性）	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 设置的用户 ID	c7d9fed7-aa40-4bfa-918f-8d4b155bfd4b
ad_unit	广告单元	rewarded_video
ad_network	广告媒体	Admob
instance_name	实例名	Bidding, High
country	国家（地区）编号	US
placement	版位	Home_Screen
segment	用户被归到的流量分组名	Tier 1
AB_Testing	A/B Test 标签	A,B
app_key	应用 Key
app_name	应用名称
platform	平台	iOS, android

- 指标字段

字段名	描述	取值举例
revenue	收益金额	0.5

3.8 标准化字段

以下事件属性会进行标准化处理：

原始字段	标准化字段	含义
ad_network	te_ads_object.media_source	变现渠道
ad_unit	te_ads_object.ad_group_name	变现广告 Unit 名
placement	te_ads_object.placement	变现广告位置
app_name	te_ads_object.app_name	应用名
country	te_ads_object.country	国家地区编码
platform	te_ads_object.platform	平台，即 Android、iOS 等
【USD】定值	te_ads_object.currency	变现收益的币种
revenue	te_ads_object.revenue	变现收益