适用于广告主的 Reporting API

以广告主身份访问 Tapjoy Offerwall 的 Reporting API，从而获取详细数据，监控和评估应用表现，以及优化报告查询以获得更好的广告系列洞察。

阅读时间7 分钟

最后更新于 3 个月前

作为广告主，您可以使用 Reporting API 来获取在 Offerwall 中投放的广告的报告数据。

先决条件

您必须通过 API 的身份验证。

如需了解如何通过 Reporting API 管理您的广告系列，请参阅广告系列管理。
如需了解 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	用户点击号召性用语的次数（如果存在号召性用语）。
clickToConversionTime	点击至转化时间数据，按多种方式进行细分。请注意，CTCT 指标仅在每天的第一个小时（UTC 时间）报告。使用 `HOURLY` 粒度时，只有表示 `00:00:00 UTC - 00:59:59 UTC` 的这一小时才会具有非 0 值。
conversions	广告目标转化次数。
csConversions	广告目标客户服务转化次数。
csSpend	客户支持总支出金额。
ecpi	总支出除以总参与次数。
engagementInstalls	从参与次数推断的安装量。
iaaRevenue	任务在所选时间范围内产生的总广告收入。
iapRevenue	任务在所选时间范围内产生的总 IAP 收入。
impressions	广告在 Offerwall 中被点击的次数。请注意，这一指标更准确反映了 `clicks` ，而不是 `impressions` 。我们很快将重命名这一指标。
offerwallAverageRank	广告在 Offerwall 中展示的（加权）平均排序位置。值从 1 开始递增，1 表示 Offerwall 中的首位。值为 0 表示在所选时间段内该任务未在 Offerwall 中展示。
offerwallImpressions	广告在 Offerwall 中出现的次数。请注意，广告可能出现在 Offerwall 中，但用户未查看（即用户滚动的距离不够远，未看到广告）。建议广告主使用下面的 `offerwallTrueImpressions` 。
offerwallTrueImpressions	用户在 Offerwall 中查看广告的次数。每次查看广告均登记为真实广告展示。
returnOnAdSpend	每日安装用户的广告支出回报率数据。请注意，广告支出回报率指标仅在每天的第一个小时（UTC 时间）报告。
dayXRoas	安装后 `X` 天的总广告支出回报率。计算方式为 `dayXRoasRevenue` / `dayXRoasSpend` 。如果 `dayXRoasRevenue` 为 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` 天由安装用户在所选时间范围内产生的总 IAP 收入。适用于 `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90` 。
dayXRoasRevenue	安装后 `X` 天由安装用户在所选时间范围内产生的总收入（IAP + 广告收入）。计算方式为 `dayXRoasIapRevenue` + `dayXRoasAdRevenue` 。适用于 `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	支出总金额。
totalRevenue	任务在所选时间范围内产生的总收入（IAP + 广告收入）。计算方式为 `iaaRevenue` + `iapRevenue` 。

后台上提供的其他广告主指标

转化率 (CVR)
指引 CVR
转化/展示量
点击率 (CTR)
按_总_支出计算的 ROAS（Reporting API 返回按_群组_支出划分的 ROAS）

指标细分

通过向查询中添加细分段字段，API 可以返回按事件、发行商应用、国家/地区等细分的效果数据。Reporting API 支持以下细分段：

country
attributionSource
language
platform
id（发行商 App ID）
id（AdSet/任务 ID）
multiRewardEngagementEvent

细分示例

按国家/地区、归因源和/或语言细分

{ 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（多个广告集）
appIds（发行商应用）
configuredStatus（ACTIVE、ARCHIVED 或 PAUSED）
countries
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      }    }  }}

按多个广告集过滤

结果将限于_前_或_后_ x 个广告集


query {  advertiser {    adSets(first: 2) {      edges {        node {          insights(timePreset:TODAY) {            reports {              conversions            }          }        }      }    }  }}

按发行商应用过滤

结果将限于指定的发行商 App 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      }    }  }}

按已配置状态过滤

结果将限于具有指定状态的广告集/广告系列选项：

ACTIVE

、

ARCHIVED

或

PAUSED


query {  advertiser {    adSets(first: 2, configuredStatus: ACTIVE) {      edges {        node {          insights(timePreset:TODAY) {            reports {              conversions            }          }        }      }    }  }}

按国家/地区过滤

结果将限于指定的国家/地区


query {  adSet(id: "00000000-0000-0000-0000-000000000000") {    insights(filter:{countries: [JP, US]}) {      timestamps      reports {        conversions      }    }  }}

按预设时间范围过滤

结果将限于预设时间范围。这是一个相对时间范围，结果将因查询运行时间而有所不同。选项：

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 年。

注意