自管理货币

为Tapjoy Offerwall设置自管虚拟货币，包括配置奖励回调以及在自有服务器上处理奖励。

阅读时间8 分钟

最后更新于 12 天前

使用自管理货币，您可以直接在自己的服务器上管理用户的虚拟货币。与 Tapjoy 管理的货币相比，这种方式提供了更大的控制权，但也需要您处理所有后端流程，包括存储和更新货币余额。与 Tapjoy 管理的货币不同，自管理货币不支持

getCurrencyBalance

、

awardCurrency

或

spendCurrency

等函数。此外，Tapjoy 不提供自管理货币的客户端或应用端通知。您需要负责在 Tapjoy 联系您的回调服务器时通知应用和您的用户。自管理货币有以下特殊要求：

奖励延迟：Tapjoy 旨在尽快奖励用户，但无法保证即时到账。为确保余额更新准确，请定期检查余额变化，例如在应用启动、恢复事件、关卡切换、视频广告播放完毕以及商店互动之前。告知用户完成任务可能需要一些时间才能获得奖励。
平台专属货币：即使是自主管理，每个平台（iOS、Android 等）也需要设置各自独立的货币。

回调 URL

当用户通过积分墙赚取货币时，Tapjoy会向您指定的回调URL发送一个HTTP GET请求。该请求包含以下参数：

```
snuid
```
：用户 ID。
```
currency
```
：要添加到用户账户的货币数量。
```
mac_address
```
：用户的 Wi-Fi MAC 地址（如有）。

请参考以下回调示例：


  <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

服务器响应要求

您的服务器必须返回以下 HTTP 状态码之一：

状态码	说明
`200 OK`	自有服务已经收到奖励回调.
`403 Forbidden`	验证器参数与预期值不匹配。 snuid 参数未知。任何其他阻止进一步重试的错误。

Tapjoy 会在以下情况下重试请求：

如果 Tapjoy 没有收到
```
200
```
或
```
403
```
响应，则会每五分钟重试一次，最多持续四天。
如果您的服务器响应时间超过5秒，Tapjoy 会将请求视为失败并重试。
响应必须采用 UTF-8 编码；否则，即使服务器返回
```
200
```
，Tapjoy也会重试。

注意

如果您的服务器返回非 200 响应，请勿向用户发放奖励。Tapjoy 会持续重试，这可能会导致重复奖励。

欺诈检测或预防参数

使用虚拟货币密钥增强安全性。前往 Tapjoy 控制面板中的“变现”>“虚拟货币”>“创建/编辑”配置您的密钥。此密钥与应用程序 SDK 密钥不同，用于对回调进行签名。使用虚拟货币密钥的货币具有以下附加安全参数：

ID：奖励请求的唯一标识符（与
```
currency_id
```
不同）
Verifier：ID、snuid、货币和密钥的MD5哈希值。

需要监控的欺诈场景

管理货币时，请考虑以下欺诈场景：

如果您遇到重复使用的ID或验证器不正确，则回调URL可能并非来自Tapjoy，您可以将其视为欺诈行为。
如果您的用户ID仅包含整数，请验证snuid以防止篡改。例如，Tapjoy 将
```
001234
```
和
```
1234
```
视为两个不同的用户 ID。但是，您的后端服务器逻辑可能并非如此。

验证码计算

验证码是一个 MD5 哈希值，格式如下：


Digest::MD5.hexdigest("#{id}:#{snuid}:#{currency}:#{secret_key}")

如果任何请求不匹配，您的服务器必须重新计算验证器并返回

403 Forbidden

响应。请为每个应用程序使用唯一的密钥，以避免跨应用程序奖励问题。每个应用程序必须拥有独立的密钥。请勿对所有应用程序使用同一个密钥，因为这可能会导致多个应用程序的用户同时获得奖励。

改进的回调 URL

Tapjoy支持团队提供了一种更安全的回调格式。此版本使用带有 JSON 有效负载的 POST 请求，并采用基于 SHA256 哈希的消息认证码 (HMAC) 进行验证。请联系您的客户经理或支持团队以启用此功能。当用户赚取货币时，Tapjoy 会向您提供的 URL 发送 POST 请求。Tapjoy 会根据请求正文和您的共享密钥（可在 Tapjoy 控制面板中找到）生成验证码，并将其包含在请求头中。 Tapjoy 使用类似于以下示例的结构对请求进行签名：


  {    "id": "reward.id",    "rev": 100,    "cp": "your_custom_string",    "currency": {        "id": "currency_id",						        "reward": 100,        "currency_sale": 1.5    },    "offer": {        "name": "Some offer",        "type": "",        "icon_url": "offer_icon_url"    },    "placement": {        "content_type": "offerwall",        "name": "placement_name"    },    "user": {        "id": "pub_user_id"    },    "timestamp": "123491324"}

参数	类型	描述
`id`	string	此请求的唯一奖励 ID
`rev`	double	获得的收入（以美元为单位）
`cp`	string	通过 SDK 的 setCustomParameter 方法传递的自定义参数
`currency.id`	string	此货币的唯一标识符
`currency.reward`	integer	奖励给用户的货币数额
`currency.currency_sale`	float	货币促销乘数（如果适用）
`offer.name`	string	广告主广告名称
`offer.type`		目前不支持此参数
`offer.icon_url`	string	广告的图标 URL
`placement.name`	string	与此次转化关联的广告位
`placement.content_type`	string	使用的广告类型
`user.id`	string	通过 SDK 的 setUserID 方法传递的用户 ID
`timestamp`	timestamp	时间戳

Tapjoy 使用以下格式对请求进行签名：


HMAC_SHA-256(<Request-Body>,<Secret-Key>)

以下示例演示了带有签名的 Tapjoy 标头：


X-Tapjoy-Signature => 7205ccfdfa1fe28cd05a1b56a9508d898cc938aa555a6c18848097fe4ee0975b

设置用户 ID

对于自管理货币，在与 Tapjoy 进行任何交互之前设置唯一的

user_id

至关重要，以确保用户能够收到奖励。此值将成为回调 URL 中的 snuid。在初始连接期间，在发出任何内容请求之前，使用连接标志设置

user_id

。如果设置错误，您的用户将无法收到奖励，您也无法获得收入。为您的货币设置

user_id

时，请参考以下要求：

使用唯一的数字 ID（最多 190 个字符）。
为符合 GDPR 规定，避免使用可识别信息（例如：用户名、真实姓名、电子邮件地址）。
为确保安全性和欺诈检测，请在每个用户的生命周期内保持 ID 的一致性。

如果未设置，Tapjoy 将默认使用设备 ID（通常是广告 ID），该 ID 可能因 SDK 版本、设备或操作系统而异。以下代码示例演示了如何使用 connect 标志，以及在必要时如何直接调用 setUserID API（连接后）。直接调用 API 时，请使用回调函数以确保 ID 设置成功。最佳实践是尽可能使用 connect 标志。


// 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) {}];


// Recommended approach using connect flagHashtable<String, Object> connectFlags = new Hashtable<String, Object>();connectFlags.put(TapjoyConnectFlag.USER_ID, "<USER_ID_HERE>"); // Important for self-managed currencyTapjoy.connect(getApplicationContext(), "SDK_KEY_GOES_HERE", connectFlags, new TJConnectListener() {...});// Setting the user id directlyTapjoy.setUserID("<USER_ID_HERE>", new TJSetUserIDListener() {  @Override  public void onSetUserIDSuccess() {      }  @Override  public void onSetUserIDFailure(String error) {  }});


// Recommended approach using connect flagDictionary<string,string> connectFlags = new Dictionary<string,string>();connectFlags.Add("TJC_OPTION_USER_ID", "<USER_ID_HERE>");#if UNITY_ANDROID  Tapjoy.Connect("your_android_sdk_key", connectFlags);#elif UNITY_IOS  Tapjoy.Connect("your_ios_sdk_key", connectFlags);#endif// Callbacks for SetUserIDTJPlacement.OnSetUserIDSuccess += HandleOnSetUserIDSuccess;TJPlacement.OnSetUserIDFailure += HandleOnSetUserIDFailure;// Setting the user id directlyTapjoy.SetUserID("<USER_ID_HERE>")


// Recommended approach using connect flagtry {  let flags: object = { TJC_OPTION_USER_ID: '<userId>' };  await Tapjoy.connect('<sdk_key>', flags);} catch (error) {  console.log(error);}// Setting the user id directlytry {  await Tapjoy.setUserId('<userId>');} catch (error) {  console.log(error);}

您可以在各平台的快速入门页面找到更多示例。

设置用户余额

每次请求广告位时，在加载内容之前，请将用户的当前余额更新到 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 = Tapjoy.getPlacement("placement", this);placement.setCurrencyBalance("1234", 100, new TJSetCurrencyBalanceListener() {    @Override    public void onSetCurrencyBalanceSuccess() {            }    @Override    public void onSetCurrencyBalanceFailure(int code, String error) {    }});


TJPlacement placement = TJPlacement.CreatePlacement("placementName");placement.SetCurrencyBalance("[CURRENCY_ID]", 100);// Optional callbacksvoid OnEnable() {	    TJPlacement.OnSetCurrencyBalanceSuccess += HandleSetCurrencyBalanceSuccess;	    TJPlacement.OnSetCurrencyBalanceFailure += HandleSetCurrencyBalanceFailure;	}void OnDisable() {	    TJPlacement.OnSetCurrencyBalanceSuccess -= HandleSetCurrencyBalanceSuccess;	    TJPlacement.OnSetCurrencyBalanceFailure -= HandleSetCurrencyBalanceFailure;}public void HandleSetCurrencyBalanceSuccess(TJPlacement placement) {}public void HandleSetCurrencyBalanceFailure(TJPlacement placement, int code, string error){}


let placement = new TJPlacement('placementName');try {  await placement?.setCurrencyBalance('1234', 100);} catch (e: any) {  let code = e.code;  let message = e.message;}

所需金额

如果您设置了余额，也可以同时设置每次投放所需的金额。


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    }}


TJPlacement placement = Tapjoy.getPlacement("placement", this);placement.setCurrencyAmountRequired("1234", 100, new TJSetCurrencyAmountRequiredListener() {    @Override    public void onSetCurrencyAmountRequiredSuccess() {            }    @Override    public void onSetCurrencyAmountRequiredFailure(int code, String error) {    }});


TJPlacement placement = TJPlacement.CreatePlacement("placementName");placement.SetRequiredAmount("[CURRENCY_ID]", 200); // Optional callbacksvoid OnEnable() {	    TJPlacement.OnSetCurrencyAmountRequiredSuccess += HandleSetRequiredAmountSuccess;	    TJPlacement.OnSetCurrencyAmountRequiredFailure += HandleSetRequiredAmountFailure;}void OnDisable() {	    TJPlacement.OnSetCurrencyAmountRequiredSuccess -= HandleSetRequiredAmountSuccess;	    TJPlacement.OnSetCurrencyAmountRequiredFailure -= HandleSetRequiredAmountFailure;}public void HandleSetCurrencyBalanceSuccess(TJPlacement placement){}public void HandleSetCurrencyBalanceFailure(TJPlacement placement, int code, string error){}public void HandleSetRequiredAmountSuccess(TJPlacement placement){}public void HandleSetRequiredAmountFailure(TJPlacement placement, int code, string error){}


let placement = new TJPlacement('placementName');try {await offerwallPlacement?.setRequiredAmount(100, '100');} catch (e: any) {  let code = e.code;  let message = e.message;}

奖励回调 IP 白名单

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

注意

最后修改时间：2024 年 5 月 12 日

```
18.215.207.89
```
```
18.235.142.165
```
```
23.20.255.113
```
```
23.23.134.165
```
```
3.210.188.32
```
```
3.215.42.140
```
```
3.217.209.177
```
```
3.218.95.35
```
```
3.219.236.53
```
```
3.231.137.161
```

故障排除

如果您在回调 URL 中收到意外的 snuid，请确保在每次应用启动后、用户访问优惠之前，在连接调用之后调用

setUserID

。如果设备没有关联的用户 ID，Tapjoy 会在回调 URL 中发送设备 ID 作为 snuid。例如，用户可能启动应用，但在您的应用发送用户 ID 之前就访问了 Tapjoy 网站。为避免这种情况，请确保服务器在每次应用启动后、连接调用之后调用

setUserID

。如果您尚未设置用户 ID，系统将尝试使用最佳可用设备 ID。通常，这将是设备的广告 ID。但是，根据 SDK 版本、设备型号/版本、设备操作系统 (OS) 版本和 Google Play 服务的不同，确切的 ID 可能会有所不同。其他可能的值包括 Android ID、udid 和 mac_address。

文档

引擎

服务

增长

工业

支持

Offerwall

开始使用 Monetization（变现）

开始使用 User Acquisition

Unity SDK 集成