Table of Contents
通过Tapjoy Manged Currency (货币管理服务) 您可以选择用Tapjoy的服务器来贮存并管理您用户虚拟货币。这是一个对于所有集成了Tapjoy软件包的开发商所提供的一个免费服务,从而使您不用担心虚拟货币的后台储存。集成这项服务的过程相对简单,详细步骤如下:
显示奖励内容
获取货币额度
检查用户是否已获得货币
消费 Tap Points
奖励 Tap Points
测试货币管理 (Managed Currency)
多种货币
最佳范例
显示奖励内容
关于如何显示奖励内容的详细步骤请参考SDK集成部分 Tapjoy Knowledge Center.
获取货币额度
通过以下途径来获取摸个用户的货币余额信息。
虚拟货币最佳执行范例: 我们建议经常调用 getCurrencyBalance 从而使用户显示最新余额。一些常见的应该调用这个函数的地方有:当应用刚刚启动时,当应用从后台重新调用时,当Tapjoy广告显示关闭以后,或是当一个placement内容关闭时。
注意: 虽然我们会进我们所能来给予用户奖励,但是我们不能保证所有奖励转账的时间是实时的。关于何时奖励一个用户的条件有很多。作为最佳流程,您应当在您的集成中隔一段时间便更新用户的余额。并且在诸如程序启动,重新回到程序,通关,启动应用商店等等情况之前更新用户的账户余额。我们也建议您告知您的用户:某些奖励过程需要一定的时间,请耐心等待。
iOS 说明
// 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]); } }];
如上所属,通过整个区域执行来调用余额 — 参数 “currencyName”对应货币名称,“amount” 对应余额。
更多实例请参考集成包中示范标准程序。
安卓说明
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回调函数使其返回。
注意: 我们建议在程序初始和重新启动时调用 getCurrencyBalance(…) 函数。SPEND和AWARD两个回调指针同时也返回虚拟货币的总数,您可以通过其更新用户的账户余额。
Unity说明
// Get currency
Tapjoy.GetCurrencyBalance();
// on enable, add delegates
void OnEnable() {
Tapjoy.OnGetCurrencyBalanceResponse += HandleGetCurrencyBalanceResponse;
Tapjoy.OnGetCurrencyBalanceResponseFailure += HandleGetCurrencyBalanceResponseFailure;
}
// on disable, remove delegates
void 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指针中返回。
AIR 说明
// Get currency
TapjoyAIR.getCurrencyBalance();
// Setup handlers
TapjoyAIR.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 中返回。
检查用户是否成功获取货币
iOS说明
通过设置一个观察者对象来接受某一用户自从上次登陆后是否成功被奖励货币:
// 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];
}
安卓说明
通过设置你“earned points”接受函数来获取某一用户是否被奖励货币:
// 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货币的转换,onEarnedCurrency将会在下一次getCurrencyBalance()函数被调取时返回25额度。
Unity 说明
// on enable, add delegates
void OnEnable() {
Tapjoy.OnEarnedCurrency += HandleEarnedCurrency;
}
// on disable, remove delegates
void OnDisable() {
Tapjoy.OnEarnedCurrency -= HandleEarnedCurrency;
}
public void HandleEarnedCurrency(string currencyName, int amount) {
Debug.Log("C#: HandleEarnedCurrency: currencyName: " + currencyName + ", amount: " + amount);
}
你制定的OnEarnedCurrency函数将返回currencyName和amount两个量值。
AIR 说明
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两个量值。
消费Tap Points
通过调用以下这些函数来消费某个额度的虚拟货币:
iOS 说明
// 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])
}
}];
如上所属,通过整个区域执行来调用余额 — 参数 “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);
}
});
通过 您定义的onSpendCurrencyBalanceResponse(String currencyName, int balance) 回调函数取得用户余额。如有错误,则通过onSpendCurrencyBalanceResponseFailure回调函数使其返回。
Unity Instructions
// Spend currency
Tapjoy.SpendCurrency(10);
// on enable, add delegates
void OnEnable() {
Tapjoy.OnSpendCurrencyResponse += HandleSpendCurrencyResponse;
Tapjoy.OnSpendCurrencyResponseFailure += HandleSpendCurrencyResponseFailure;
}
// on disable, remove delegates
void 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);
}
您将会在OnSpendCurrencyBalanceResponse通过currencyName(货币名称)以及balance(余额)返回结果中得到您所需的货币余额。如有错误将在OnSpendCurrencyBalanceResponseFailure指针中返回。
AIR Instructions
// Spend currency
TapjoyAIR.spendCurrency(10);
// Setup handlers
TapjoyAIR.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_BALANCE_SUCCESS 指针取得用户余额,这个函数会返回一个 TJCurrencyEvent 对象. 这个对象包块 currencyName 和 balance 两个属性. 错误会在 TJCurrencyEvent.SPEND_CURRENCY_BALANCE_FAILURE 中返回。
奖励 Tap Points
通过调用一下函数来达到奖励用户虚拟货币的目的:
iOS 说明
// 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])
}
}];
如上所属,通过整个区域执行来调用余额 — 参数 “currencyName”对应货币名称,“amount” 对应余额。
Android Instructions
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);
}
});
通过 您定义的onAwardCurrencyBalanceResponse(String currencyName, int balance) 回调函数取得用户余额。如有错误,则通过onAwardCurrencyBalanceResponseFailure回调函数使其返回。
Unity Instructions
// Award currency
Tapjoy.AwardCurrency(10);
// on enable, add delegates
void OnEnable() {
Tapjoy.OnAwardCurrencyResponse += HandleAwardCurrencyResponse;
Tapjoy.OnAwardCurrencyResponseFailure += HandleAwardCurrencyResponseFailure;
}
// on disable, remove delegates
void 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);
}
您将会在OnAwardCurrencyBalanceResponse通过currencyName(货币名称)以及balance(余额)返回结果中得到您所需的货币余额。如有错误将在OnAwardCurrencyBalanceResponseFailure指针中返回。
Air Instructions
// Award currency
TapjoyAIR.awardCurrency(10);
// Setup handlers
TapjoyAIR.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_BALANCE_SUCCESS 指针取得用户余额,这个函数会返回一个 TJCurrencyEvent 对象. 这个对象包块 currencyName 和 balance 两个属性. 错误会在 TJCurrencyEvent.AWARD_CURRENCY_BALANCE_FAILURE 中返回。
测试货币管理
如果您想在广告墙中查看测试广告,您可以在您的应用中加一个测试设备。步骤是:在控制面板 -> (您的应用名字) -> 设置 -> 测试设备。这样做的结果是在广告墙的最上端显示一个测试用广告,使您轻送测试您的虚拟货币功能:
注意测试广告和测试用的视屏广告一同都在广告墙的顶端。
最佳范例,更多信息
- 注意: 请务必确实spendCurrency以及awardCurrency函数调用的结果,只有在成功的情况下才解锁内容或购买。如果awardCurrency或spendCurrency调用失败,则有很高的几率说明这台设备的账户余额被盗取。查看SDK集成包中的工程实例。
- 有些应用开发者只用货币管理服务(Managed Currency)来返回客户端的一些提示信息,他们的货币点数则是存在客户端本地。我们强烈建议您不要只依靠客户本地端的货币余额,我们无法在您有技术困难时对您提供支持。如果您有此类需要,请考虑使用 Non-Managed Currency.
- spendCurrency函数只应该在您解锁一个物品或内容需要扣除货币时调用。
- 货币管理服务只对一个应用ID对应一种货币这种形式提供支持。如果您在一个应用中有实现多种货币的需要请用 Non-Managed Currency.
- 账户额度对应储存的是在每个设备上的每个应用,所以额度不能在不同设备直接转存。
注意: 虽然我们会进我们所能来给予用户奖励,但是我们不能保证所有奖励转账的时间是实时的。关于何时奖励一个用户的条件有很多。作为最佳流程,您应当在您的集成中隔一段时间便更新用户的余额。并且在诸如程序启动,重新回到程序,通关,启动应用商店等等情况之前更新用户的账户余额。我们也建议您告知您的用户:某些奖励过程需要一定的时间,请耐心等待。