文档

支持

Offerwall

开始使用 Monetization（变现）

开始使用 User Acquisition

Unity SDK 集成

Offerwall

自管货币

为 Tapjoy Offerwall 设置自管虚拟货币，包括配置奖励回调以及在自有服务器上处理交易。
阅读时间11 分钟最后更新于 4 天前
当您使用自有服务器来处理用户货币时，需采用自管货币模式。此模式可让您更全面掌控用户货币，但也意味着您需要全权负责后端货币管理工作，包括存储和处理所有用户的货币金额。getCurrencyBalance、awardCurrency 或 spendCurrency 仅适用于托管货币模式。对于自管货币，Tapjoy 不会向客户端/应用端发送通知；当我们调用您的回调服务器时，应用和用户的通知由您自行处理。您必须设置一个回调服务器才能使用自管货币。 尽管 Tapjoy 会尽最大努力尽快为用户发放奖励，但不能保证用户立即收到奖励。用户收到奖励的时间受很多因素影响。最好是定期检查用户的最新余额，并在应用发生某些事件时进行此检查，例如在应用启动后、应用恢复运行后、关卡切换期间、视频广告关闭后、商店加载前等。此外，建议告知用户，完成任务后可能需要一些时间才能收到奖励。

回调 URL

当用户完成任务获得虚拟货币后，我们将向此 URL 发起一次 HTTP GET 请求。参数的格式如下： 
<callback_url>?snuid=<user_id>&currency=<currency>&mac_address=<mac_address>//Examplehttp://www.sampledoman.com/payments/offers/tapjoy?&amp;snuid=42&amp;currency=50&amp;mac\_address=00-16-41-34-2C-A6
默认的请求参数包括 snuid 和 currency（表示应为用户帐户增加的货币数量）以及用户的 WiFi mac_address（如果可用）。

服务器响应

Tapjoy 服务器期望服务器返回 
200
或 
403
响应。

服务器响应

案例

200
- 用户成功获得货币。
403
  • verifier 参数与计算出的值不匹配。
  • 系统无法识别 snuid 参数。
  • 存在其他不应重试的错误。
如果 Tapjoy 服务器收到 200 或 403 以外的任何其他响应，Tapjoy 将继续重试。 Tapjoy 每 5 分钟左右重试一次回调，持续 4 天。如果服务器的响应时间超过 5 秒，Tapjoy 的算法会将该请求视为失败。

用于检测和预防欺诈的可选参数

您可以在 Dashboard（后台） > Monetize（变现） > Virtual Currency（虚拟货币） > Create/Edit（创建/编辑） 中访问虚拟货币密钥。此密钥与应用程序 SDK 密钥不同。此虚拟货币密钥用于对回调进行签名。 如果货币中存在密钥 (
secret_key=
)，我们会向回调请求中添加以下参数：

参数

描述

注意

id
这是具有唯一性的标识符，用于标记奖励的特定货币。表示 
request_id
而不是 
currency_id
。
verifier
ID、snuid、货币和密钥的 MD5 哈希值。

应始终注意的欺诈情况

  • 如果您发现 ID 被重用和/或校验值不正确，表示回调 URL 不是来自 Tapjoy，应视为欺诈。
  • 如果您的用户 ID 仅包含整数，建议您执行简单的验证以确保用户 ID 未被篡改。例如，Tapjoy 将“001234”和“1234”视为两个不同的用户 ID，但后端服务器的逻辑可能并非如此。

校验值

校验值 (verifier) 的计算方法是用冒号将 ID、snuid、货币和密钥连接成一个字符串，然后对该字符串计算 MD5 哈希值。在 Ruby 代码中，如下所示： 
Digest::MD5.hexdigest("#{id}:#{snuid}:#{currency}:#{secret_key}")
您的服务器应重新计算校验值，并拒绝任何不匹配的请求。如果校验值不匹配，服务器应返回 403 Forbidden 响应。

改进回调 URL

我们对上面列出的回调进行了改进，提供更多信息和更高安全性。如果希望使用此改进版本，请联系您的客户经理或我们的支持团队，他们会帮助您启用此版本的回调。 用户通过完成任务赚取货币后，我们将向您提供的 URL 发起一次 POST 请求。参数的格式如下： 
{   "cp": "some_string",   "currency": {      "currency_sale":"1.0",      "id": "reward_id",      "reward":100   },   "id": "some_id",   "offer": {      "advertiser_app_name": "a_cool_app",      "currency": {         "max_reward_value":1360      },      "expires_at":1768175428,      "icon_url": "some_URL/icon.jpg",      "name": "eye_catching_headline",      "task":{         "is_iap": false,         "name": "event_name"      },      "type": ""   },   "placement":{      "content_type": "offerwall",      "name": "placement_name"   },   "rev":100,   "timestamp":1762993750,   "user": {      "id": "user_id"   }}

参数

类型

描述

id
字符串此请求的唯一奖励 ID
rev
双精度获得的收入（以美元为单位）
cp
字符串通过 SDK 的 setCustomParameter 方法传递的自定义参数
currency.id
字符串此货币的唯一标识符
currency.reward
整数奖励给用户的货币金额
currency.currency_sale
浮点货币促销乘数（如果适用）
currency.max_reward_value
整数用户完成此次所有任务后可以获得的最大货币量。
offer.name
字符串广告主提供的任务的名称
offer.type
字符串目前不支持此参数
offer.icon_url
字符串任务的图标 URL
offer.advertiser_app_name
字符串广告主的应用名称
offer.task.name
字符串用户完成并得到奖励的任务的名称或描述。
offer.task.is\_iap
布尔值如果奖励事件对应的是 IAP 事件，则值为 true
offer.expires_at
时间戳用户在该时间戳（以秒为单位）之后无法再通过此任务获得奖励。
placement.name
字符串与此次转化关联的广告位
placement.content_type
字符串使用的广告位类型
user.id
字符串通过 SDK 的 setUserID 方法传递的用户 ID
timestamp
时间戳此次交易的时间戳
JSON 正文将首先进行递归排序，然后用 SHA256 哈希算法进行哈希计算。通过 POST 货币回调请求正文和我们的共享密钥（在 Tapjoy 后台上通过您的回调 URL 可以找到此密钥）将生成校验值。此校验值将置于 POST 货币回调请求标头中发送。 
HMAC_SHA-256(<Request-Body>,<Secret-Key>)
包含签名的 Tapjoy 标头示例： 
X-Tapjoy-Signature => 7205ccfdfa1fe28cd05a1b56a9508d898cc938aa555a6c18848097fe4ee0975b

用户 ID

如果您使用自管货币，那么设置用户 ID 就至关重要。此值是回调 URL 中设置的 
snuid
值。在请求任何内容之前，建议使用连接标志在连接时设置用户 ID。 如果设置不正确，您的用户将不会得到奖励，您也将不会得到报酬。应设置具有唯一性的用户 ID（通常为数字）。 为保障数据安全和 GDPR 合规性，setUserID 参数不应包含任何可识别或可追溯个人身份的信息，例如用户名、真实姓名或电子邮件地址。 出于安全防护与欺诈检测目的，用户 ID 应在用户整个生命周期内保持不变。（例如，请勿使用用户 ID 参数来披露用户等级或分数等信息。） 用户 ID 最长为 190 个字符。 下面为不同平台提供了相应的代码示例，演示了如何使用连接标志，以及如何在必要时直接调用 
setUserID
API（连接后）。直接调用 API 时，请使用回调确保已成功设置 ID。强烈建议尽可能使用连接标志： 
// Recommended approach using connect flagNSDictionary *connectFlags = @{TJC_OPTION_USER_ID : @"<USER_ID_HERE>"};[Tapjoy connect:@"SDK_KEY_GOES_HERE" options:connectFlags];// Setting the user id directly[Tapjoy setUserIDWithCompletion:@"<USER_ID_HERE>" completion:^(BOOL success, NSError *error) {}];
您可以在 iOS、Android、Unity 和 React Native 平台对应的快速入门页面上找到更多示例。 故障排除： 如果要调用 setUserID，但回调 URL 中的 snuid 不是预期值，则需在用户进入应用内 Offerwall 或 tapjoy.com 完成任务之前调用 setUserID。如果设备没有关联 userID，Tapjoy 将在回调 URL 中将设备 ID 作为 snuid 发送。例如，用户可能启动应用后就转到 tapjoy.com，但此时该应用尚未向我们发送 userID。为了防止这种情况，您需要确保在每次启动应用时进行 connect 调用后都调用 setUserID。 如果未设置用户 ID，系统将尝试使用可用的最优设备 ID。在大多数情况下，这个 ID 值就是设备的广告 ID。但是，根据 SDK 版本、设备型号/版本、设备操作系统版本和 Google Play 服务，具体的 ID 可能会有所不同。其他可能的值包括 Android ID、udid 和 mac_address。

设置用户余额

每次请求广告位时，您都可以将用户的当前余额告知 Tapjoy。必须在请求广告位内容之前进行此设置。 
TJPlacement *placement = [TJPlacement placementWithName:@"placementName" delegate:nil];[placement setBalance:100 forCurrencyId:@"1234" withCompletion:^(NSError * _Nullable error) {  if (error != nil) {    //Failure    NSString *message = error.localizedDescription;  } else {    //Success  }}];

所需金额

如果设置了用户余额，还可以设置广告位所需的金额值。 
TJPlacement* placement = [TJPlacement placementWithName:@"placementName" delegate:nil];[placement setRequiredAmount:100 forCurrencyId:@"1234" withCompletion:^(NSError * _Nullable error) {  if (error != nil) {    //Failure    NSString *message = error.localizedDescription;  } else {    //Success  }}];

奖励回调 IP 白名单

如果您的奖励回调服务器需要额外权限（白名单）才能访问，下面是 Tapjoy 的 IP 地址列表。（最后修改时间：2024 年 5 月 12 日） 
18.215.207.8918.235.142.16523.20.255.11323.23.134.1653.210.188.323.215.42.1403.217.209.1773.218.95.353.219.236.533.231.137.161

从 Tapjoy 托管货币切换到自管货币

如果您的应用尚未发布，可以在 Tapjoy 后台的 Edit Virtual Currency（编辑虚拟货币）屏幕上，从 Tapjoy 托管货币切换到自管货币。请务必在回调 URL 字段中输入格式正确的 URL，否则更改将无法生效。 如果您的应用程序已上线并采用 Tapjoy 托管货币，切换过程会更加复杂。这种情况下，请注意以下事项：
  • 您需要创建新应用并生成新的 SDK 密钥。这样可以确保使用旧版应用（未升级到最新版本）的用户不受影响。如果您在采用自管货币的应用中继续使用原来的 SDK 密钥，则采用 Tapjoy 托管货币的应用中的所有用户将无法获得完成任务的奖励。
  • 您需要禁用所有指向旧 App ID 的广告系列，并重新创建广告系列并使其指向新 App ID。
  • 切换到自管货币还需要更改应用中的代码。您将无法使用 getCurrencyBalance、awardCurrency 或 spendCurrency，因为它们仅适用于托管货币。
  • 建议在考虑进行更改之前联系您的客户经理。
  • 无法从自管货币切换到 Tapjoy 托管货币。因此，请务必在更改之前三思。
要迁移用户的余额，建议按照以下步骤操作：
  1. 首次发布应用时，使用旧的 SDK 密钥（采用 Tapjoy 托管货币），并调用 getCurrencyBalance 来获取余额。
  2. 将余额更新为 getCurrencyBalance 返回的值。
  3. 在所有后续发布时，使用新的 SDK 密钥。
如果您正在考虑切换到自管货币，但不确定如何实现自己的虚拟货币服务器，建议您查看 Parse 或 UrbanAirship 的解决方案。