文档

支持

Offerwall

开始使用 Monetization（变现）

开始使用 User Acquisition

Unity SDK 集成

Offerwall

Reporting API 最佳实践

了解 Tapjoy Offerwall Reporting API 终端、请求结构和错误处理机制，从而有效获取准确的用户获取数据。
阅读时间6 分钟最后更新于 5 天前
Reporting API 使广告主和发行商能够使用 GraphQL 查询语言从 Tapjoy 平台访问报告数据并管理 Offerwall 内容。如需有关 GraphQL 的更多信息，请参阅 GraphQL 官方网站。 您可以使用 API 资源管理器来协助构建查询。单击左上角的书本图标可展开文档资源管理器，然后查找可在查询中使用的字段和指标的相关信息。
单击书本图标后在 Reporting API 资源管理器中显示的文档资源管理器面板

API 终端

Reporting API 只有一个终端： 
https://api.tapjoy.com/graphql
无论执行任何操作，终端都保持不变。

与 API 通信

有了访问令牌时，即可向 API 发出请求。要向 API 发起请求，无论执行查询还是变更操作，都需要通过 HTTP POST 提供 JSON 编码的请求正文。 请求示例：
POST /graphql Host: api.tapjoy.com Authorization: Bearer <OAuth Token>{ "query": "query { user { firstName } }" }

处理错误

使用 API 时，可能会遇到以下几类错误：
  • 服务器/网络错误
  • 身份验证/授权错误
  • 查询语法错误
  • 数据验证错误
为了确保系统正确集成，需要考虑系统应如何处理这些类别的错误。 下面描述的每个错误类别都将使用以下查询作为上下文： 
query {  user {    firstName    lastName  }}

服务器/网络错误

使用 API 时，偶尔可能会遇到无法恢复的服务器/网络错误。在此类情况下，您将收到与相关场景对应的正确 http 状态代码。例如，如果 API 中出现阻止执行查询的问题，那么您将收到一个包含 500 状态代码的 HTTP 响应。 在这种场景下，最好的处理方式是使用指数退避的重试策略。

身份验证/授权错误

身份验证/授权错误可能由以下几种原因导致：
  • 您的 OAuth 令牌到期
  • 您的 OAuth 令牌无效
  • 我们的底层身份验证系统出现了问题
在这些情况下，您会收到 HTTP 200 OK 响应，其中包含以下数据： 
{  "errors": [    {      "message": "Authentication could not be verified. Please try again later.",      "code": 403    }  ]}
  • message
    - 人类可读的错误描述
  • code
    - 与 HTTP 状态代码相对应的 GraphQL 状态代码
在这种场景下，最好的处理方式是获取新的访问令牌并重试相应请求。

查询语法错误

所有查询和变更都会经过预先验证以确认其语法正确并遵循所述的数据架构。如果提供的查询未能通过所有架构验证，您将收到 HTTP 200 OK 响应，其中包含以下数据： 
{  "errors": [    {      "message": "Field 'user' doesn't exist on type 'Query'",      "locations": [        {          "line": 2,          "column": 3        }      ],      "fields": [        "query",        "user"      ]    }  ]}
  • message
    - 人类可读的错误描述
  • locations
    - 出现语法错误的位置
  • fields
    - 语法错误影响的字段
在这种场景下，最好的处理方式是参考 API 文档并在交互式资源管理器中测试查询。

数据验证错误

即使提供的变更具有正确的结构和所有必填字段，仍可能因业务验证失败而导致提交失败。例如，假设广告主将广告出价更改为低于 AdSet 的最小值，如下所示： 
mutation {  updateAdSet(input: {    id: "00000000-0000-0000-0000-000000000000",    bidding: {amount: 10000}  }) {    adSet {      id    }  }}
在这种场景下，您会收到 HTTP 200 OK 响应，其中包含以下数据： 
{  "data": {    "updateAdSet": null  },  "errors": [    {      "message": "Amount is below the minimum (20000 micros)",      "locations": [        {          "line": 2,          "column": 3        }      ],      "path": [        "updateAdSet",        "input",        "bidding",        "amount"      ],      "code": 422    }  ]}
  • message
    - 人类可读的错误描述
  • locations
    - 出现验证错误的位置
  • path
    - 对判定无效字段的完全限定引用
  • code
    - 与 HTTP 状态代码相对应的 GraphQL 状态代码
在这种场景下，最好的处理方式是将错误消息以及相应字段（通过路径）一起呈现给用户。

局限性

Reporting API 具有一些保护措施，可防止过度或滥用 API 调用。如果您的集成超过现有限制，请联系 Tapjoy 客户经理或支持团队，了解如何优化集成或提高上限。 以下示例以广告主为例进行展示，但同样适用于发行商的集成场景。

数据留存

Reporting API 可以访问过去两年的数据。

分页

在查询分页类型时，客户端必须：
  • 提供 
    first
    或 
    last
    参数
  • 在单个页面中不超过 100 个节点
如果超过最大值，则结果将被截断，因此，请求的第一个/最后一个参数将被忽略。 例如： 
{  advertiser {    adSets(first: 50) {      edges {        node {          id          name          ads(first: 50) {            edges {              node {                id                name              }            }          }        }      }    }  }}
在以上查询中，最多返回 50 个广告集，每个广告集最多包含 50 个广告。 为了对集合进行分页，必须提供 
after
或 
before
参数来控制页面的开头位置。例如： 
{  advertiser {    adSets(first: 50, after: "Mg==") {      edges {        node {          id          name        }      }      pageInfo {        endCursor        hasNextPage      }    }  }}
在以上查询中，最多返回 50 个广告集，从光标位置“Mg==”开始。该位置根据从上一个查询返回的 endCursor 确定。当 hasNextPage 为 false 时，应认定分页已完成。 如需了解关于分页的更多信息，请参阅 GraphQL 文档。

调用复杂性

为了通过架构验证，所有 Marketing API 调用不得超过 10,000 次“调用”。在这种情况下，一次“调用”是指对资源的一次请求。由于 GraphQL 允许将多次调用合并到单个查询中，因此在执行查询之前，API 会提前计算单个查询的调用总数。 调用次数大致相当于从结果中选择的资源数量（例如广告系列、广告集、广告、应用、洞察等） 考虑以上同一个示例： 
{  advertiser {    adSets(first: 50) {     # <= 50 calls      edges {        node {          id          name          ads(first: 50) {  # <= 50 calls            edges {              node {                id                name              }            }          }        }      }    }  }}
在此示例中，客户端一次最多请求 50 个广告集；对于每个广告集，最多从广告集请求 50 个广告。 调用总次数的计算方法： 
50      = 50 ad sets+50 x 50 = 2500 ads        = 2550 calls
目前，对于每小时的调用次数，没有速率限制。但是，这种情况未来可能会所有改变。

洞察复杂性

在任何级别查询的报告洞察都会产生额外的复杂性成本，而上述基本计算中并未反映这一成本。每天查询需要在计算中额外增加 1 次调用。 考虑以下示例： 
{  advertiser {    # 50 calls    adSets(first: 50) {      edges {        node {          id          name          # 7 calls          insights(timeRange: {from: "2024-03-01T00:00:00Z", until: "2024-03-08T00:00:00Z"}) {            timestamps            reports {              country              impressions              conversions              spend            }          }        }      }    }  }}
在此示例中，客户端一次最多请求 50 个广告集；对于每个广告集，都会请求 7 天的报告数据，涵盖 3 个指标和 1 个细分段。 调用总次数的计算方法： 
50      = 50 ad sets+50 x 7  = 350 insights        = 400 calls