# 适用于广告主的 Reporting API > 以广告主身份访问 Tapjoy Offerwall 的 Reporting API，从而获取详细数据，监控和评估应用表现，以及优化报告查询以获得更好的广告系列洞察。 作为广告主，您可以使用 Reporting API 来获取在 Offerwall 中投放的广告的报告数据。 ## 先决条件##prerequisites 您必须[通过 API 的身份验证](./api-authentication.md)。 * 如需了解如何通过 Reporting API 管理您的广告系列，请参阅[广告系列管理](./campaign-management.md)。 * 如需了解 Reporting API 的错误处理机制和限制，请参阅 [Reporting API 最佳实践](./reporting-api-best-practices.md)。 ## 广告主报告指标##advertiser-reporting-metrics Reporting API 可用于请求广告集和多重奖励事件的效果数据，包括收入、展示量和转化等指标。下表列出了所有可用的广告主报告指标。 建议广告主使用以下基本查询开始获取效果指标： ```graphql 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） ## 指标细分##metric-segmentations 通过向查询中添加细分段字段，API 可以返回按事件、发行商 app 或国家/地区等细分中断的性能数据。Reporting API 支持以下细分段： * country * attributionSource * language * platform * id（发行商 App ID） * id（AdSet/任务 ID） * multiRewardEngagementEvent ### 细分示例##segmentation-examples #### 按国家/地区、归因源和/或语言细分##segment-by-country-attribution-source-and/or-language 以下查询返回按国家/地区、归因音频源和语言细分的指定的广告集和时间范围的转化数据。 ```graphql title="Query" { 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 } } } } ``` ```graphql title="Result" { "data": { "adSet": { "insights": { "timestamps": [ "2024-08-01T00:00:00Z" ], "reports": [ { "country": "FR", "attributionSource": "OTHER", "language": "RU", "conversions": [ 1 ] }, { "country": "FR", "attributionSource": "OTHER", "language": "FR", "conversions": [ 17 ] }, { "country": "CA", "attributionSource": "OTHER", "language": "EN", "conversions": [ 16 ] }, { "country": "AU", "attributionSource": "OTHER", "language": "EN", "conversions": [ 3 ] }, ] } } } } ``` #### 按平台细分##segment-by-platform 以下查询返回前两个广告系列的展示数据（按平台细分）。 ```graphql title="Query" { advertiser{ id campaigns(first: 2){ nodes{ insights{ reports{ impressions platform } } } } } } ``` ```graphql title="Result" { "data": { "advertiser": { "id": "00000000-0000-0000-0000-000000000000", "campaigns": { "nodes": [ { "insights": { "reports": [ { "impressions": [ 0 ], "platform": null } ] } }, { "insights": { "reports": [ { "impressions": [ 0 ], "platform": null } ] } } ] } } } } ``` #### 按发行商应用细分##segment-by-publisher-app 以下查询返回指定的广告集的展示量、转化和支出，按发布者app中断。 ```graphql title="Query" query { adSet(id: "00000000-0000-0000-0000-000000000000") { ads { id insights(timePreset: TODAY) { reports { app { bundleId } impressions conversions spend } } } } } ``` ```graphql title="Result" { "data": { "adSet": { "ads": [ { "id": "10000000-0000-0000-0000-000000000000", "insights": { "reports": [ { "app": { "bundleId": "com.example.app", }, "impressions": [ 6147 ], "conversions": [ 24 ], "spend": [ 73000000 ] }, { "app": { "bundleId": "com.example.app2", }, "impressions": [ 4131 ], "conversions": [ 12 ], "spend": [ 73000000 ] }, { "app": null, "impressions": [ 5427 ], "conversions": [ 34 ], "spend": [ 73000000 ] } ] } }, { "id": "20000000-0000-0000-0000-000000000000", "insights": { "reports": [ { "app": { "bundleId": "com.example.app", }, "impressions": [ 6142 ], "conversions": [ 24 ], "spend": [ 73000000 ] }, { "app": { "bundleId": "com.example.app2", }, "impressions": [ 4111 ], "conversions": [ 12 ], "spend": [ 73000000 ] }, { "app": null, "impressions": [ 5227 ], "conversions": [ 30 ], "spend": [ 73000000 ] } ] } } ], "insights": { "reports": [ { "app": { "bundleId": "com.example.app", }, "impressions": [ 12550 ], "conversions": [ 49 ], "spend": [ 147000000 ] }, { "app": { "bundleId": "com.example.app2", }, "impressions": [ 8242 ], "conversions": [ 24 ], "spend": [ 146000000 ] }, { "app": null, "impressions": [ 10654 ], "conversions": [ 64 ], "spend": [ 146000000 ] } ] } } } } ``` #### 按广告集或广告系列细分##segment-by-ad-set-or-campaign 以下查询返回指定时间范围内最多 50 个激活广告集的转化和支出。 ```graphql title="Query" 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 } } } } } } } ``` ```graphql title="Result" { "data": { "advertiser": { "adSets": { "edges": [ { "node": { "id": "00000000-0000-0000-0000-000000000000", "insights": { "timestamps": [ "2024-11-15T00:00:00Z" ], "reports": [ { "impressions": [ 13550 ], "conversions": [ 53 ], "spend": [ 159000000 ] } ] } } }, { "node": { "id": "00000000-0000-0000-0000-000000000001", "insights": { "timestamps": [ "2024-11-15T00:00:00Z" ], "reports": [ { "impressions": [ 1220 ], "conversions": [ 8 ], "spend": [ 12300000 ] } ] } } } ] } } } } ``` #### 按多重奖励互动事件细分##segment-by-multi-reward-engagement-event 以下查询将返回指定的广告集的转化率和第 0 天 ROAS（按多重奖励参与度事件细分）。 ```graphql title="Query" { 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 } } } } } ``` ```graphql title="Result" { "data": { "adSet": { "id": "00000000-0000-0000-0000-000000000000", "insights": { "timestamps": [ "2024-11-15T00:00:00Z" ], "reports": [ { "conversions": [ 10 ], "returnOnAdSpend": { "day0Roas": [ 0 ] }, "multiRewardEngagementEvent": { "eventName": "Purchase=#" } }, { "conversions": [ 15 ], "returnOnAdSpend": { "day0Roas": [ 0 ] }, "multiRewardEngagementEvent": { "eventName": "LEVEL_#" } } ] } } } } ``` ## 过滤功能##filtering-capabilities 通过向查询中添加过滤器，API 将仅返回指定来源的效果指标。Reporting API 支持以下过滤功能： * adSet（单个广告集） * adSets（多个广告集） * appIds（发行商应用） * configuredStatus（*ACTIVE*、*ARCHIVED* 或 *PAUSED*） * countries * timePreset * timeRange ### 过滤示例##filtering-examples #### 按广告集过滤##filter-by-ad-set 结果将限于单个 *adSet* ```graphql title="GraphQL" 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 } } } } ``` #### 按多个广告集过滤##filter-for-multiple-ad-sets 结果将限于\_前\_或\_后\_ x 个广告集 ```graphql title="GraphQL" query { advertiser { adSets(first: 2) { edges { node { insights(timePreset:TODAY) { reports { conversions } } } } } } } ``` #### 按发行商应用过滤##filter-by-publisher-app 结果将限于指定的发行商 App ID ```graphql title="GraphQL" query { adSet(id: "00000000-0000-0000-0000-000000000000") { insights(filter:{appIds: ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000"]}) { timestamps reports { conversions } } } } ``` #### 按已配置状态过滤##filter-by-configured-status 结果将限于具有指定状态的广告集/广告系列 **选项**：`ACTIVE`、`ARCHIVED` 或 `PAUSED` ```graphql title="GraphQL" query { advertiser { adSets(first: 2, configuredStatus: ACTIVE) { edges { node { insights(timePreset:TODAY) { reports { conversions } } } } } } } ``` #### 按国家/地区过滤##filter-by-country 结果将限于指定的国家/地区 ```graphql title="GraphQL" query { adSet(id: "00000000-0000-0000-0000-000000000000") { insights(filter:{countries: [JP, US]}) { timestamps reports { conversions } } } } ``` #### 按预设时间范围过滤##filter-by-a-preset-timeframe 结果将限于预设时间范围。这是一个相对时间范围，结果将因查询运行时间而有所不同。 **选项**：`LAST 30D`、`LAST WEEK`、`TODAY`、`YESTERDAY`。 > **Note:** > > 要定义数据聚合级别，应包含 **timeIncrement** 参数，此参数可以接受值 *DAILY*、*HOURLY*、*MONTHLY*。**timeIncrement** 是可选参数，其默认值为 *ALL*。 ```graphql title="GraphQL" query { adSet(id: "00000000-0000-0000-0000-000000000000") { insights(timePreset:LAST_30D, timeIncrement: DAILY) { reports { impressions } } } } ``` #### 按绝对时间范围过滤##filter-by-an-absolute-time-range 结果将限于指定的绝对时间范围。 最大的时间范围为 3 个月，支持的最早日期为过去 2 年。 > **Note:** > > 要定义数据聚合级别，应包含 **timeIncrement** 参数，此参数可以接受值 *DAILY*、*HOURLY*、*MONTHLY*。**timeIncrement** 是可选参数，其默认值为 *ALL*。 ```graphql title="GraphQL" 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 } } } } ``` ## 已弃用的维度##deprecated-dimensions 以下旧版维度已于 2025 年 2 月 3 日从 Reporting API 中移除。为防止从 Tapjoy 的 Offerwall 获取数据时出错，请确保您的 API 查询不会引用下面以**粗体**格式列出的任何维度。 * 枚举 > TargetConnectionType > **MOBILE** * 枚举 > TargetDeviceType > **WINDOWS**