# 适用于发行商的 Reporting API

> 以发行商身份访问 Tapjoy Offerwall 的 Reporting API，从而获取详细数据，监控和评估 app 表现，以及优化 Monetization 策略。

作为发行商，您可以使用 Reporting API 来获取集成了 Offerwall 的应用的报告数据。

## 先决条件##prerequisites

您必须通过 API 的身份验证。请参阅 [API 身份验证](/grow/offerwall/monetization/api/api-authentication.md)。

* 如需了解如何通过 Reporting API 管理您的内容，请参阅[内容管理](/grow/offerwall/monetization/api/content-management.md)。
* 如需了解 Reporting API 的错误处理机制和限制，请参阅 [Reporting API 最佳实践](/grow/offerwall/monetization/api/reporting-api-best-practices.md)。

## 发行商报告指标##publisher-reporting-metrics

Reporting API 可用于请求 Offerwall 内容的效果数据，包括点击、转化和总收入等指标。下表列出了所有可用的发行商报告指标。

建议发行商使用以下基本查询开始获取效果指标：

```graphql
{
  publisher {
    placements(appId: "00000000-0000-0000-0000-000000000000") {
      id
      name
      insights(
        timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"}
      ) {
        timestamps
        reports {
          dailyUniqueViewers
          earnings
        }
      }
    }
  }
}
```

| 发行商指标                             | 描述                                                                                | Country（国家/地区） | 应用组 | 单个发行商应用 | 广告位 | 所有发行商应用总和 |
| --------------------------------- | --------------------------------------------------------------------------------- | -------------- | --- | ------- | --- | --------- |
| `averageDuc`                      | 在应用、广告位或内容卡片中通过 Offerwall 广告完成转化的独立用户的平均数量（每个用户每 24 小时最多计一次），以天数取平均值              | 是              | 是   | 是       | 是   | 是         |
| `arpdau`                          | 每个每日活跃用户的平均收入（总收入除以每日活跃用户数）                                                       | 是              | 是   | 是       | 否   | 是         |
| `arpduv`                          | 每日独立 Offerwall 浏览用户的平均收入（即总收入除以在应用中浏览过 Offerwall 的独立用户数，每个用户每 24 小时最多计一次）         | 是              | 是   | 是       | 否   | 是         |
| `averageDau`                      | 每日活跃用户的平均数量（每个用户每 24 小时最多计一次），以天数取平均值                                             | 是              | 是   | 是       | 否   | 是         |
| `averageDuv`                      | 在应用中浏览过 Offerwall 的独立用户的平均数量（每个用户每 24 小时最多计一次），以天数取平均值                            | 是              | 是   | 是       | 否   | 是         |
| `clicks`                          | 广告位产生的点击量                                                                         | 是              | 否   | 否       | 是   | 否         |
| `conversions`                     | 广告位产生的转化量                                                                         | 是              | 否   | 否       | 是   | 否         |
| `dailyActiveUsers`                | 每日活跃用户数                                                                           | 是              | 是   | 是       | 否   | 是         |
| `dailyUniqueConversions`          | 在此广告位或内容卡片中通过广告完成转化的用户数（每个用户每 24 小时最多计一次）。目前仅适用于 Offerwall 内容卡片                   | 是              | 否   | 否       | 是   | 否         |
| `dailyUniqueOfferwallEngagements` | 在应用中通过 Offerwall 广告完成转化的独立用户数（每个用户每 24 小时最多计一次）                                   | 是              | 是   | 是       | 否   | 是         |
| `dailyUniqueOfferwallViewers`     | 在应用中浏览过 Offerwall 的独立用户数（每个用户每 24 小时最多计一次）                                        | 是              | 是   | 是       | 否   | 是         |
| `dailyUniqueViewers`              | 在此广告位或内容卡片中浏览过广告的独立用户数（每个用户每 24 小时最多计一次）。目前仅适用于 Offerwall 内容卡片                    | 是              | 否   | 否       | 是   | 否         |
| `ducduv`                          | 在此广告位或内容卡片中通过广告完成转化的用户数（每个用户每 24 小时最多计一次）除以在此广告位或内容卡片中浏览过广告的用户数（每个用户每 24 小时最多计一次） | 是              | 是   | 是       | 是   | 是         |
| `duvDau`                          | 在应用中浏览过 Offerwall 的独立用户数（每个用户每 24 小时最多计一次）除以每日活跃用户数                               | 是              | 是   | 是       | 否   | 是         |
| `earnings`                        | 收入总金额                                                                             | 是              | 否   | 否       | 是   | 否         |
| `eCPM`                            | 总收入 /（总 Offerwall 打开次数 / 1000）。以美元为单位表示                                           | 是              | 否   | 否       | 是   | 否         |
| `impressions`                     | 广告位产生的展示量                                                                         | 是              | 否   | 否       | 是   | 否         |
| `newUsers`                        | 新用户数量                                                                             | 是              | 是   | 是       | 否   | 是         |
| `offerwallViews`                  | 打开 Offerwall 的总次数                                                                 | 是              | 是   | 是       | 否   | 是         |
| `sessions`                        | 打开应用的次数                                                                           | 是              | 是   | 是       | 否   | 是         |
| `totalRevenue`                    | 总收入                                                                               | 是              | 是   | 是       | 否   | 是         |

**后台上提供的其他发行商指标：**

* 展示量/观看量
* 转化率 (CVR)

## 指标细分##metric-segmentations

通过向查询中添加细分段字段，API 可以返回按应用、广告位和/或国家/地区细分的效果数据。

Reporting API 支持以下细分段：

* country
* id（应用组 ID）
* id（发行商 App ID）
* placement
* platform
* 所有发行商应用总计

### 细分示例##segmentation-examples

#### 按国家/地区细分##segment-by-country

以下查询返回指定的广告放置/位置的每日唯一视角者数据（按国家/地区细分）。

1. **Query**

   ```graphql
   {
     publisher {
       placements(appId: "00000000-0000-0000-0000-000000000000") {
         id
         insights(timePreset: TODAY) {
           timestamps
           reports {
             country
             dailyUniqueViewers
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "placements": [
           {
             "id": "00000000-0000-0000-0000-000000000001",
             "insights": {
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ],
               "reports": [
                 {
                   "country": "AU",
                   "dailyUniqueViewers": [
                     115
                   ]
                 },
                 {
                   "country": "IR",
                   "dailyUniqueViewers": [
                     18
                   ]
                 },
                 {
                   "country": "ZA",
                   "dailyUniqueViewers": [
                     2
                   ]
                 }
               ]
             }
           }
         ]
       }
     }
   }
   ```

#### 按应用组细分##segment-by-app-group

以下查询返回前三个应用的每日激活用户数据（按 app group ID 细分）。

1. **Query**

   ```graphql
   {
     publisher {
       apps(first: 3) {
         nodes {
           appGroupId
           insights(timePreset: TODAY) {
             reports {
               dailyActiveUsers
             }
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "apps": {
           "nodes": [
             {
               "appGroupId":"00000000-0000-0000-0000-000000000000",
               "insights": {
                 "reports": [
                   {
                     "dailyActiveUsers": [
                       12
                     ]
                   }
                 ]
               }
             },
             {
               "appGroupId":"00000000-0000-0000-0000-000000000001",
               "insights": {
                 "reports": [
                   {
                     "dailyActiveUsers": [
                       31
                     ]
                   }
                 ]
               }
             },
             {
               "appGroupId":"00000000-0000-0000-0000-000000000002",
               "insights": {
                 "reports": [
                   {
                     "dailyActiveUsers": [
                       3
                     ]
                   }
                 ]
               }
             }
           ]
         }
       }
     }
   }
   ```

#### 按发行商应用细分##segment-by-publisher-app

以下查询返回前三个发布者应用的每日激活用户数据（按 app 名称细分）。

1. **Query**

   ```graphql
   query {
     publisher {
     apps(first:3) {
         edges {
           node {
             name
             insights(timePreset:TODAY) {
               reports {
                 dailyActiveUsers
               }
             }
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql"
   {
     "data": {
       "publisher": {
         "apps": {
           "edges": [
             {
               "node": {
                 "name": "example_app1",
                 "insights": {
                   "reports": [
                     {
                       "dailyActiveUsers": [
                         78
                       ]
                     }
                   ]
                 }
               }
             },
             {
               "node": {
                 "name": "example_app2",
                 "insights": {
                   "reports": [
                     {
                       "dailyActiveUsers": [
                         12
                       ]
                     }
                   ]
                 }
               }
             },
             {
               "node": {
                 "name": "example_app3",
                 "insights": {
                   "reports": [
                     {
                       "dailyActiveUsers": [
                         15
                       ]
                     }
                   ]
                 }
               }
             }
           ]
         }
       }
     }
   }
   ```

#### 按广告位细分##segment-by-placement

以下查询返回指定的app中所有广告位的展示数据（按放置/位置位细分）。

1. **Query**

   ```graphql
   {
     publisher{
       placements(appId: "00000000-0000-0000-0000-000000000000") {
         id
         name
         insights(timePreset: TODAY) {
           reports {
             impressions
           }
           timestamps
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "placements": [
           {
             "id": "00000000-0000-0000-0000-000000000000",
             "name": "AppLaunch",
             "insights": {
               "reports": [
                 {
                   "impressions": [
                     0
                   ]
                 }
               ],
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ]
             }
           },
           {
             "id": "00000000-0000-0000-0000-000000000000",
             "name": "offerwall",
             "insights": {
               "reports": [
                 {
                   "impressions": [
                     2590
                   ]
                 }
               ],
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ]
             }
           }
         ]
       }
     }
   }
   ```

#### 按平台细分##segment-by-platform

以下查询返回指定的广告放置/位置的每日唯一视角者数据（按平台细分）。

1. **query**

   ```graphql
     publisher {
       placements(appId: "00000000-0000-0000-0000-000000000000") {
         id
         insights(timePreset: TODAY) {
           timestamps
           reports {
             platform
             dailyUniqueViewers
           }
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "placements": [
           {
             "id": "00000000-0000-0000-0000-000000000001",
             "insights": {
               "timestamps": [
                 "2024-11-15T00:00:00Z"
               ],
               "reports": [
                 {
                   "platform": "ios",
                   "dailyUniqueViewers": [
                     78
                   ]
                 }
               ]
             }
           }
         ]
       }
     }
   }
   ```

#### 所有发行商应用总和##sum-across-all-publisher-apps

表示此发行商下所有应用的请求指标的总和。

以下查询返回今天所有发布者应用程序中汇总的 eCPM、总收入和 offerwall 视图。

1. **query**

   ```graphql
   {
     publisher {
       publisherAppInsights(timePreset: TODAY) {
         timestamps
         reports {
           ecpm
           totalRevenue
           offerwallViews
         }
       }
     }
   }
   ```

2. **Result**

   ```graphql
   {
     "data": {
       "publisher": {
         "publisherAppInsights": {
           "timestamps": [
             "2025-08-27T00:00:00Z"
           ],
           "reports": [
             {
               "ecpm": [
                 4.108913673386
               ],
               "totalRevenue": [
                 57149851536
               ],
               "offerwallViews": [
                 461224
               ],
             }
           ]
         }
       }
     }
   }
   ```

## 过滤功能##filtering-capabilities

通过向查询中添加过滤器，API 将仅返回指定来源的效果指标。Reporting API 支持以下过滤功能：

* appId（单个应用）
* apps（*前\_或\_后* x 个应用）
* appGroupId
* content
* country
* platform
* timePreset
* timeRange

### 过滤示例##filtering-examples

#### 按应用过滤##filter-by-app

结果将限于单个应用

```graphql
{
  publisher{
    app(id: "<app ID>") {
      id
      name
      insights(timePreset: TODAY) {
        reports {
          arpdau
        }
        timestamps
      }
    }
  }
}
```

#### 按多个应用过滤##filter-for-multiple-apps

结果将限于\_前\_或\_后\_ x 个应用

```graphql
{
  publisher {
    apps(first: 3) {
      nodes {
        id
        platform
        insights {
          reports {
            arpdau
            totalRevenue
          }
        }
      }
    }
  }
}
```

#### 按应用组 ID 过滤##filter-by-app-group-id

结果将限于特定应用组 ID 下的应用

```graphql
{
  publisher {
    publisherAppInsights(timePreset: TODAY, filter: {appGroupIds: ["00000000-0000-0000-0000-000000000000"]}) {
      timestamps
      reports {
        offerwallViews
        eCPM
        totalRevenue
      }
    }
```

#### 按内容卡片过滤##filter-by-content-card

结果将限于单个内容卡片 ID

```graphql
{
  publisher {
    placements(appId: "<app ID>") {
      id
      name
      content(id: "<content ID>") {
        id
        type
        insights(timePreset: TODAY) {
        timestamps
          reports {
            earnings
          }
        }
      }
    }
  }
} 
```

#### 按国家/地区过滤##filter-by-country

结果将限于指定的地域

```graphql
{
  publisher {
    publisherAppInsights(timePreset: TODAY, filter: {countries: ["KR, US"]}) {
      timestamps
      reports {
        offerwallViews
        eCPM
        totalRevenue
      }
    }
```

#### 按平台过滤##filter-by-platform

结果将限于指定的平台

```graphql
{
  publisher {
    publisherAppInsights(timePreset: TODAY, filter: {platforms: [ios]}) {
      timestamps
      reports {
        offerwallViews
        eCPM
        totalRevenue
      }
    }
```

#### 按预设时间范围过滤##filter-by-a-preset-timeframe

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

**选项**：*LAST\_30D*、*LAST\_WEEK*、*TODAY*、*YESTERDAY*。

> **Note:**
>
> 要定义数据聚合级别，应包含 **timeIncrement** 参数，此参数可以接受值 *DAILY*、*HOURLY*、*MONTHLY*。**timeIncrement** 是可选参数，其默认值为 *ALL*。

```graphql
{
  publisher {
    placements(appId: "<app ID>") {
      content(id: "<content card ID>") {
        insights(timePreset:LAST_30D, timeIncrement: DAILY) {
        timestamps
          reports {
            dailyUniqueViewers
          }
        }
      }
    }
  }
} 
```

#### 按绝对时间范围过滤##filter-by-an-absolute-time-range

结果将限于指定的绝对时间范围。

最大的时间范围为 3 个月，支持的最早日期为过去 2 年。

> **Note:**
>
> 要定义数据聚合级别，应包含 **timeIncrement** 参数，此参数可以接受值 *DAILY*、*HOURLY*、*MONTHLY*。**timeIncrement** 是可选参数，其默认值为 *ALL*。

```graphql
{
  publisher {
    placements(appId: "<app ID>") {
      content(id: "<content card ID>") {
        insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-17T00:00:00Z"}, timeIncrement: DAILY) {
        timestamps
          reports {
            dailyUniqueViewers
          }
        }
      }
    }
  }
} 
```

## 已弃用的维度##deprecated-dimensions

以下旧版维度于 2025 年 2 月 3 日从 Reporting API 中移除。为防止从 Tapjoy 的 Offerwall 获取数据时出错，请确保您的 API 查询**不会**引用下面以**粗体**格式列出的任何维度。

对象 > ContentCard > **ecpmSettings**

枚举 > PublisherContentType：

* `ANNOUNCEMENT`
* `DIRECT_PLAY_HOUSE_AD`
* `FEATURED`
* `FSI_HOUSE_AD`
* `IAP_PROMOTION`
* `INTERSTITIAL_VIDEO`
* `MEDIATED_DIRECT_PLAY`
* `MEDIATED_FSI`
* `PREVIEW_CODE`
* `PROGRAMMATIC_INTERSTITIAL_VIDEO`
* `PROGRAMMATIC_REWARDED_VIDEO`
* `REWARDED_VIDEO`
* `TJ_RECOMMENDED`
* `REWARD_UNLOCK`

输入对象 > `CreatePlacementAndContentSetInput` > **ecpmSettingsToAdd**

输入对象 > `UpdatePlacementAndContentSetInput`：

* `ecpmSettingsToAdd`
* `ecpmSettingsToDelete`
* `ecpmSettingsToUpdate`