CHN广告主Reporting API
上次更新时间：2025年1月22日
概览
作为广告客户，您可以使用Reporting API检索您在Offerwall中投放的广告的数据。
**开始之前：**您必须按照此处 的步骤使用该AP 进行身份验证。
- 有关如何通过ReportingAPI管理您的广告系列的信息，请参阅广告管理。
- 有关Reporting API的错误处理和限制的信息，请参阅 Reporting API最佳实践。
广告主报告指标
Reporting API可用于请求广告和多奖励事件的效果数据，包括收入、展示次数和转化次数等指标。所有可用的广告主报告指标均列于下表。
我们建议广告主首先使用以下基本查询来检索效果指标：
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"}) {
timestamps
reports {
impressions
}
}
}
}
| 广告客户指标 | 描述 |
|---|---|
| amount | 此事件的出价 |
| averageBid | 总支出除以总转化次数 |
| callToActionClicks | 用户点击call-to-action的次数（如果存在call-to-action） |
| clickToConversionTime | 点击到转化时间数据以几种不同的方式细分。 注意：CTCT指标仅在每天的第一个UTC小时报告。当使用 HOURLY粒度时，只有表示“00:00:00 UTC - 00:59:59 UTC”的小时才会具有非0的值。 |
| conversions | 广告的转化次数 |
| csConversions | 广告的客户服务转化次数 |
| csSpend | 客户服务总支出 |
| ecpi | 总支出除以总互动次数 |
| engagementInstalls | 根据互动带来的安装次数 |
| impressions | 广告在积分墙中被点击的次数。注意：此指标更准确地表示clicks，而不是impressions。我们将很快重命名此指标。 |
| offerwallAverageRank | 广告投放的积分墙平均排名（加权）。该值从 1开始递增，1表示积分墙的最高排名。值为0表示该广告在选定时间段内未显示在积分墙中。 |
| offerwallImpressions | 广告在积分墙中出现的次数。 注意：广告可能会出现在积分墙中，但用户并没有查看（即用户未滚动到足够远的位置以查看广告）。我们建议广告主使用下方的 offerwallTrueImpressions。 |
| offerwallTrueImpressions | 用户在offerwall中查看广告的次数。每次查看都记为一次真实展示。 |
| returnOnAdSpend | 每天安装用户的广告支出回报率数据。 注意：广告支出回报率指标仅在每天第一个UTC小时报告。 |
| dayXRoas | 安装后 X 天的广告支出总回报率。计算方法为 day_X_roas_revenue 除以 day_X_roas_spend。如果 day_X_roas_revenue 为 0，则此字段也为 0。适用于 X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90。 |
| dayXRoasAdRevenue | 安装后 X 天的用户广告总收入。适用于 X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90。 |
| dayXRoasEngagements | 安装后 X 天内的用户参与总数。适用于 X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90。 |
| dayXRoasIapRevenue | 安装后 X 天内的用户应用内购总收入。适用于 X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90。 |
| dayXRoasRevenue | 安装后 X 天内的用户应用内购总收入。计算公式为 day_X_roas_iap_revenue 加上 day_X_roas_ad_revenue。 适用于 X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90。 |
| dayXRoasSpend | 自安装以来 X 天的广告客户总支出。适用于 X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90。 |
| spend | 总支出金额 |
控制面板中提供的其他广告主指标
- 转化率(CVR)
- 指导页CVR
- 转化次数/展示次数
- 点击率(CTR)
- 按总支出计算的广告支出回报率(ROAS)（报告API返回按群组支出计算的广告支出回报率）
指标细分
通过在查询中添加细分字段，API可以返回按事件、开发者应用、国家/地区等细分的效果数据。报告API支持按以下细分进行细分：
- 国家/地区
- 归因来源
- 语言
- 平台
- ID（开发者应用ID）
- ID（广告ID）
- 多奖励事件
细分示例
按国家/地区，归因来源和/或语言细分
{
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(timeRange: {from: "2024-08-01T00:00:00Z", until: "2024-08-01T11:59:59Z"}, timeIncrement: DAILY) {
timestamps
reports {
country
attributionSource
language
conversions
}
}
}
}
按平台细分
{
advertiser{
id
campaigns(first: 2){
nodes{
insights{
reports{
impressions
platform
}
}
}
}
}
}
按开发者应用细分
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
ads {
id
insights(timePreset: TODAY) {
reports {
app {
bundleId
}
impressions
conversions
spend
}
}
}
}
}
按广告细分
query {
advertiser {
adSets(first: 50, configuredStatus: ACTIVE) {
edges {
node {
id
insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-16T00:00:00Z"}) {
timestamps
reports {
conversions
spend
}
}
}
}
}
}
}
按多事件奖励事件细分
{
adSet(id: "00000000-0000-0000-0000-000000000000") {
id
insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-15T11:59:59Z"}, timeIncrement: DAILY) {
timestamps
reports {
conversions
returnOnAdSpend {
day0Roas
}
multiRewardEngagementEvent {
eventName
}
}
}
}
}
过滤功能
通过在查询中添加过滤器，API将仅返回来自指定来源的效果指标。Reporting API支持以下过滤功能：
- adSet（单个广告）
- adSets（多个广告）
- appId（开发者应用）
- configuredStatus（ACTIVE、ARCHIVED 或 PAUSED）
- 国家/地区
- timePreset
- timeRange
过滤示例
按广告过滤
这会将结果限制为单个 adSet
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(timeRange: {from: "2024-08-06T00:00:00Z", until: "2024-08-07T00:00:00Z"}) {
timestamps
reports {
impressions
conversions
spend
offerwallAverageRank
}
}
}
}
按多个广告过滤
这会将结果限制为_first_或者_last_个广告集
query {
advertiser {
adSets(first: 2) {
edges {
node {
insights(timePreset:TODAY) {
reports {
conversions
}
}
}
}
}
}
}
按开发者应用过滤
这会将结果限制为特定的开发者应用ID
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(filter:{appIds: ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000"]}) {
timestamps
reports {
conversions
}
}
}
}
按配置状态过滤
这会将结果限制为特定配置状态的广告
Options: ACTIVE, ARCHIVED, or PAUSED
query {
advertiser {
adSets(first: 2, configuredStatus: ACTIVE) {
edges {
node {
insights(timePreset:TODAY) {
reports {
conversions
}
}
}
}
}
}
}
按国家/地区过滤
This limits results to the specified countries
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(filter:{countries: [JP, US]}) {
timestamps
reports {
conversions
}
}
}
}
Filter by a Preset Timeframe
按预设时间范围过滤 这会将结果限制在预设的时间范围内。这是一个相对时间范围，结果会根据查询的运行时间而变化。
Options: LAST_30D, LAST_WEEK, TODAY, YESTERDAY.
注意：要定义数据聚合级别，请包含timeIncrement，其值可以是_DAILY_、HOURLY、MONTHLY。timeIncrement是可选参数，默认为_ALL_
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(timePreset:LAST_30D, timeIncrement: DAILY) {
reports {
impressions
}
}
}
}
按绝对时间范围过滤
这会将结果限制在指定的绝对时间范围内。
最大范围为3个月，支持的最早日期为2年前。
注意：要定义数据聚合级别，请添加 timeIncrement，其值可以是 DAILY、HOURLY 和 MONTHLY。timeIncrement 是可选参数，默认为 ALL
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-17T00:00:00Z"}, timeIncrement: DAILY) {
reports {
impressions
}
}
}
}
已弃用的维度
以下旧版维度将于 2025 年 2 月 3 日从 Reporting API 中移除。请确保您的 API 查询不引用下方粗体列出的任何维度，以免从 Tapjoy 的 offerwall 获取数据时出错。
- Enums > TargetConnectionType > MOBILE
- Enums > TargetDeviceType > WINDOWS