Tapjoy 托管货币

使用 Tapjoy Offerwall 托管货币在 Tapjoy 服务器上存储和管理用户货币余额。

阅读时间10 分钟

最后更新于 2 个月前

Tapjoy 托管货币支持在 Tapjoy 的服务器上存储用户的货币金额。这是 Tapjoy 为所有集成了 Tapjoy 发行商 SDK 的开发者提供的免费服务。通过使用此服务，免除了您为应用程序存储用户货币数据所需的常规后端工作。集成过程相对简单，下面将详细介绍集成说明。

获取货币余额

要获取用户的当前虚拟货币，请调用以下方法： 虚拟货币最佳实践： 建议尽可能频繁调用 getCurrencyBalance，以便用户的余额始终是最新数据。检查用户余额的常见时机包括：应用启动时、应用恢复运行时、Tapjoy 视图关闭时以及广告位内容消失时。通常，在广告内容消失后 3.5 秒调用 getCurrencyBalance（或任何平台上的等效方法）尤其有用。这样就能确保在您检查货币余额时，奖励已经在我们的系统中到账。如果在内容展示完成后立即调用 getCurrencyBalance，奖励可能在余额查询前尚未及时计入用户余额。

注意

尽管 Tapjoy 会尽最大努力尽快为用户发放奖励，但不能保证用户立即收到奖励。用户收到奖励的时间受很多因素影响。最好是除了在视频广告关闭时检查余额外，还应该定期检查用户的最新余额，并在应用发生某些事件时进行此检查，例如在应用启动后、应用恢复运行后、关卡切换期间、商店加载前等。此外，建议告知用户，完成任务后可能需要一些时间才能收到奖励。


// This method requests the tapjoy server for current virtual currency of the user.//Get currency[Tapjoy getCurrencyBalanceWithCompletion:^(NSDictionary *parameters, NSError *error) {  if (error) {    //Show error message    NSLog(@"getCurrencyBalance error: %@", [error localizedDescription]);  } else {    //Update currency value of your app    NSLog(@"getCurrencyBalance returned %@: %d", parameters[@"currencyName"], [parameters[@"amount"] intValue]);  }}];

如上所述，在 completion 代码块中会告知货币余额，其中的参数

currencyName

提供货币名称，“amount”提供用户的余额。如需了解实现细节，请参考 SDK 包中的示例应用程序。


Tapjoy.getCurrencyBalance(new TJGetCurrencyBalanceListener(){  @Override  public void onGetCurrencyBalanceResponse(String currencyName, int balance) {    Log.i(TAG, "getCurrencyBalance returned " + currencyName + ":" + balance);  }    @Override  public void onGetCurrencyBalanceResponseFailure(String error) {    Log.i("Tapjoy", "getCurrencyBalance error: " + error);  }});

您将在指定的 TJGetCurrencyBalanceListener 中的 onGetCurrencyBalanceResponse(String currencyName, int balance) 回调方法中收到货币余额通知。您将在 onGetCurrencyBalanceResponseFailure(String error) 回调方法中收到错误情况通知。

注意

最好在应用程序启动和恢复运行时调用 getCurrencyBalance(…)。SPEND 和 AWARD 货币的回调通知器也会返回用户的总虚拟货币余额，因此可以使用这些回调通知器来更新用户拥有的货币总额。


// Get currencyTapjoy.GetCurrencyBalance();// on enable, add delegatesvoid OnEnable() {  Tapjoy.OnGetCurrencyBalanceResponse += HandleGetCurrencyBalanceResponse;  Tapjoy.OnGetCurrencyBalanceResponseFailure += HandleGetCurrencyBalanceResponseFailure;}// on disable, remove delegatesvoid OnDisable() {  Tapjoy.OnGetCurrencyBalanceResponse -= HandleGetCurrencyBalanceResponse;  Tapjoy.OnGetCurrencyBalanceResponseFailure -= HandleGetCurrencyBalanceResponseFailure;}public void HandleGetCurrencyBalanceResponse(string currencyName, int balance) {  Debug.Log("C#: HandleGetCurrencyBalanceResponse: currencyName: " + currencyName + ", balance: " + balance);}  public void HandleGetCurrencyBalanceResponseFailure(string error) {  Debug.Log("C#: HandleGetCurrencyBalanceResponseFailure: " + error);}

您将在指定的 OnGetCurrencyBalanceResponse 处理程序中收到货币余额通知，该处理程序将传递

currencyName

和

balance

参数。您将在 OnGetCurrencyBalanceResponseFailure 处理程序中收到错误通知。


try {  let result = await Tapjoy.getCurrencyBalance();  let currencyName = result['currencyName'];  let amount = result['amount'];} catch (error: any) {  //Handle error}

在 React Native 中，我们对没有参数的

getCurrencyBalance()

使用了一个 Promise。这个 Promise 会返回一个字典或一个错误（错误应被捕获）。字典的键

currencyName

包含一个字符串以及货币金额。


// Get currencyTapjoyAIR.getCurrencyBalance();// Setup handlersTapjoyAIR.addEventListener(TJCurrencyEvent.GET_CURRENCY_BALANCE_SUCCESS, tapjoyCurrencyEventHandler);TapjoyAIR.addEventListener(TJCurrencyEvent.GET_CURRENCY_BALANCE_FAILURE, tapjoyCurrencyEventHandler);private function tapjoyCurrencyEvents(event:TJCurrencyEvent):void {  trace("Tapjoy sample event listener for " + event.type + ", " + event.balance + ", " + event.currencyName);}

您将在指定的

TJCurrencyEvent

.GET_CURRENCY_BALANCE_SUCCESS 处理程序中收到货币余额通知，该处理程序将传递

TJCurrencyEvent

对象。此对象包含

currencyName

和

balance

属性。您将在

TJCurrencyEvent.GET\_CURRENCY\_BALANCE\_FAILURE

处理程序中收到错误通知。

检查用户是否已获得货币

为了告知用户自上次应用查询用户货币余额以来的虚拟货币收入，请设置一个通知观察器：


// Set the notification observer for earned-currency-notification.It's recommended that this be placed within the applicationDidBecomeActive method.[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(showEarnedCurrencyAlert:) name:TJC_CURRENCY_EARNED_NOTIFICATION object:nil];// In the following method, you can set a custom message or use the default UIAlert to inform the user that they just earned some currency.- (void)showEarnedCurrencyAlert:(NSNotification*)notifyObj{  NSNumber *currencyEarned = notifyObj.object;  int earnedNum = [currencyEarned intValue];  NSLog(@"Currency earned: %d", earnedNum);  // Pops up a UIAlert notifying the user that they have successfully earned some currency.  // This is the default alert, so you may place a custom alert here if you choose to do so.  [Tapjoy showDefaultEarnedCurrencyAlert];  // This is a good place to remove this notification since it is undesirable to have a pop-up alert more than once per app run.  [[NSNotificationCenter defaultCenter] removeObserver:self name:TJC_CURRENCY_EARNED_NOTIFICATION object:nil];}

为了在用户获得虚拟货币（例如通过完成任务）时收到通知，请使用以下方法来设置货币收入监听器：


  // Get notifications whenever Tapjoy currency is earned.Tapjoy.setEarnedCurrencyListener(new TJEarnedCurrencyListener() {  @Override  public void onEarnedCurrency(String currencyName, int amount) {    Log.i("Tapjoy", "You've just earned " + amount + " " + currencyName);  }});

您将在指定的

TJEarnedCurrencyListener

中的

onEarnedCurrency(String currencyName, int amount)

回调方法中收到货币收入通知。例如，如果当前货币余额为 100，而用户完成了货币金额为 25 的任务，则在下次调用

getCurrencyBalance()

时将以金额 25 触发 onEarnedCurrency 方法。


// on enable, add delegatesvoid OnEnable() {  Tapjoy.OnEarnedCurrency += HandleEarnedCurrency;}// on disable, remove delegatesvoid OnDisable() {  Tapjoy.OnEarnedCurrency -= HandleEarnedCurrency;}public void HandleEarnedCurrency(string currencyName, int amount) {  Debug.Log("C#: HandleEarnedCurrency: currencyName: " + currencyName + ", amount: " + amount);}

您将在指定的 OnEarnedCurrency 处理程序中收到货币收入通知，该处理程序将传递 currencyName 和收入金额参数。


TapjoyAIR.addEventListener(TJEarnedCurrencyEvent.EARNED_CURRENCY, tapjoyEarnedCurrencyEventHandler);private function tapjoyEarnedCurrencyEventHandler(event:TJEarnedCurrencyEvent):void{  trace("You can notify user's here that they've just earned " + event.amount + " " + event.currencyName);}

您将在指定的

TJEarnedCurrencyEvent.EARNED\_CURRENCY

处理程序中收到货币收入通知，该处理程序将传递

TJEarnedCurrencyEvent

对象。此对象包含 currencyName 和 amount 属性。

花费 Tapjoy 托管货币

要花费用户的一些虚拟货币，请调用以下方法：


// This method call will deduct 10 virtual currencies from the user's total.[Tapjoy spendCurrency:10 completion:^(NSDictionary *parameters, NSError *error) {  if (error) {    NSLog(@"spendCurrency error: %@", [error localizedDescription]);  } else {    NSLog(@"spendCurrency returned %@: %d", parameters[@"currencyName"], [parameters[@"amount"] intValue]);  }}];

如上所述，在 completion 代码块中会告知货币余额，其中的参数

currencyName

提供货币名称，

amount

提供用户的余额。


Tapjoy.spendCurrency(10, new TJSpendCurrencyListener() {  @Override  public void onSpendCurrencyResponse(String currencyName, int balance) {    Log.i("Tapjoy", currencyName + ": " + balance);  }  @Override  public void onSpendCurrencyResponseFailure(String error) {    Log.i("Tapjoy", "spendCurrency error: " + error);  }});

您将在指定的

TJSpendCurrencyListener

中的

onSpendCurrencyResponse(String currencyName, int balance)

回调方法中收到货币余额通知。您将在

onSpendCurrencyResponseFailure(String error)

方法中收到错误通知。


// Spend currencyTapjoy.SpendCurrency(10);// on enable, add delegatesvoid OnEnable() {  Tapjoy.OnSpendCurrencyResponse += HandleSpendCurrencyResponse;  Tapjoy.OnSpendCurrencyResponseFailure += HandleSpendCurrencyResponseFailure;}// on disable, remove delegatesvoid OnDisable() {  Tapjoy.OnSpendCurrencyResponse -= HandleSpendCurrencyResponse;  Tapjoy.OnSpendCurrencyResponseFailure -= HandleSpendCurrencyResponseFailure;}public void HandleSpendCurrencyResponse(string currencyName, int balance) {  Debug.Log("C#: HandleSpendCurrencyResponse: currencyName: " + currencyName + ", balance: " + balance);}  public void HandleSpendCurrencyResponseFailure(string error) {  Debug.Log("C#: HandleSpendCurrencyResponseFailure: " + error);}

您将在指定的

OnSpendCurrencyResponse

处理程序中收到货币余额通知，该处理程序将传递

currencyName

和

balance

参数。您将在

OnSpendCurrencyResponseFailure

处理程序中收到错误通知。


try {  let result = await Tapjoy.spendCurrency(10);  let currencyName = result['currencyName'];  let amount = result['amount'];} catch (error: any) {  //Handle error}

在 React Native 中，我们对以金额为参数的

spendCurrency()

使用了一个 Promise。这个 Promise 会返回一个字典或一个错误（错误应被捕获）。字典的键

currencyName

包含一个字符串以及货币金额。


// Spend currencyTapjoyAIR.spendCurrency(10);// Setup handlersTapjoyAIR.addEventListener(TJCurrencyEvent.SPEND_CURRENCY_SUCCESS, tapjoyCurrencyEventHandler);TapjoyAIR.addEventListener(TJCurrencyEvent.SPEND_CURRENCY_FAILURE, tapjoyCurrencyEventHandler);private function tapjoyCurrencyEventHandler(event:TJCurrencyEvent):void {  trace("Tapjoy sample event listener for " + event.type + ", " + event.balance + ", " + event.currencyName);}

您将在指定的

TJCurrencyEvent.SPEND\_CURRENCY\_SUCCESS

处理程序中收到货币余额通知，该处理程序将传递

TJCurrencyEvent

对象。此对象包含

currencyName

和 balance 属性。您将在

TJCurrencyEvent

SPEND\_CURRENCY\_FAILURE

处理程序中收到错误通知。

奖励 Tapjoy 托管货币

警告

任何希望使用此功能的新应用，都需要与其客户经理协商以获得批准，由此带来的不便，深表歉意。

要奖励用户一定数量的虚拟货币，请调用以下方法：


// This method call will award 10 virtual currencies to the user's total.[Tapjoy awardCurrency:10 completion:^(NSDictionary *parameters, NSError *error) {  if (error) {    NSLog(@"awardCurrency error: %@", [error localizedDescription]);  } else {    NSLog(@"awardCurrency returned %@: %d", parameters[@"currencyName"], [parameters[@"amount"] intValue]);  }}];

如上所述，在 completion 代码块中会告知货币余额，其中的参数

currencyName

提供货币名称，

amount

提供用户的余额。


Tapjoy.awardCurrency(10, new TJAwardCurrencyListener() {  @Override  public void onAwardCurrencyResponseFailure(String error) {    Log.i("Tapjoy", "awardCurrency error: " + error);  }  @Override  public void onAwardCurrencyResponse(String currencyName, int balance) {    Log.i("Tapjoy", currencyName + ": " + balance);  }});

您将在指定的

TJAwardCurrencyListener

中的

onAwardCurrencyResponse(String currencyName, int balance)

回调方法中收到货币余额通知。


// Award currencyTapjoy.AwardCurrency(10);// on enable, add delegatesvoid OnEnable() {  Tapjoy.OnAwardCurrencyResponse += HandleAwardCurrencyResponse;  Tapjoy.OnAwardCurrencyResponseFailure += HandleAwardCurrencyResponseFailure;}// on disable, remove delegatesvoid OnDisable() {  Tapjoy.OnAwardCurrencyResponse -= HandleAwardCurrencyResponse;  Tapjoy.OnAwardCurrencyResponseFailure -= HandleAwardCurrencyResponseFailure;}public void HandleAwardCurrencyResponse(string currencyName, int balance) {  Debug.Log("C#: HandleAwardCurrencySucceeded: currencyName: " + currencyName + ", balance: " + balance);}  public void HandleAwardCurrencyResponseFailure(string error) {  Debug.Log("C#: HandleAwardCurrencyResponseFailure: " + error);}

您将在指定的

OnAwardCurrencyResponse

处理程序中收到货币余额通知，该处理程序将传递

currencyName

和

balance

参数。您将在

OnAwardCurrencyResponseFailure

处理程序中收到错误通知。


try {  let result = await Tapjoy.awardCurrency(10);  let currencyName = result['currencyName'];  let amount = result['amount'];} catch (error: any) {  //Handle error}

在 React Native 中，我们对以金额为参数的

awardCurrency()

使用了一个 Promise。这个 Promise 会返回一个字典或一个错误（错误应被捕获）。字典的键

currencyName

包含一个字符串以及货币金额。


// Award currencyTapjoyAIR.awardCurrency(10);// Setup handlersTapjoyAIR.addEventListener(TJCurrencyEvent.AWARD_CURRENCY_SUCCESS, tapjoyCurrencyEventHandler);TapjoyAIR.addEventListener(TJCurrencyEvent.AWARD_CURRENCY_FAILED, tapjoyCurrencyEventHandler);private function tapjoyCurrencyEventHandler(event:TJCurrencyEvent):void {  trace("Tapjoy sample event listener for " + event.type + ", " + event.balance + ", " + event.currencyName);}

您将在指定的

TJCurrencyEvent.AWARD\_CURRENCY\_SUCCESS

处理程序中收到货币余额通知，该处理程序将传递

TJCurrencyEvent

对象。此对象包含

currencyName

和 balance 属性。您将在

TJCurrencyEvent

AWARD\_CURRENCY\_FAILURE

处理程序中收到错误通知。

测试托管货币

如果要查看 Offerwall 中的测试任务，您可以向应用程序添加测试设备。这样，测试任务将显示在 Offerwall 的顶部，因此可以轻松测试货币。还有一个工具可用于验证 Tapjoy 托管货币实现是否正常工作，这就是 Tapjoy 后台上的“Get User Balance（获取用户余额）”工具：

如果应用向用户显示的余额与此工具显示的余额不同，可能的原因是应用与 Tapjoy 的余额不同步。要更正此问题，通常可以让应用更频繁调用

getCurrencyBalance

。

最佳实践

重要

请务必验证 awardCurrency 和 spendCurrency 调用，仅在调用成功时解锁内容/购买。如果 awardCurrency 和 spendCurrency 调用失败，设备上的余额很有可能已受到影响。请查看 SDK 附带的 Tapjoy EasyApp 项目中的示例。

部分发行商仅在客户端通知中实现了托管货币，并将货币值存储在本地。强烈建议不要仅依赖本地存储的货币值。如果您因此遇到问题，我们将无法提供支持。如果这会对您造成困扰，您可能需要考虑使用自管货币。
仅当需要扣除货币来解锁物品或内容时，才应调用
```
spendCurrency
```
。
托管货币仅支持每个 App ID 绑定一种货币。如果您有多种货币，则需采用自管货币。
货币余额按每个设备、每个应用分别进行存储，因此无法在设备之间共享余额。

注意

文档

引擎

服务

增长

工业

支持

Offerwall

开始使用 Monetization（变现）

开始使用 User Acquisition

Unity SDK 集成

Offerwall

Tapjoy 托管货币

获取货币余额

检查用户是否已获得货币

花费 Tapjoy 托管货币

奖励 Tapjoy 托管货币

测试托管货币

最佳实践