Tapjoy管理虚拟货币

通过Tapjoy管理虚拟货币，您可以选择用Tapjoy的服务器来贮存并管理您用户虚拟货币。这是一个对于所有集成了Tapjoy软件包的开发商所提供的一个免费服务，从而使您不用担心虚拟货币的后台储存。集成这项服务的过程相对简单，详细步骤如下。

1. 获取虚拟货币余额

过以下途径来获取某个用户的虚拟货币余额：

虚拟货币最佳执行范例: 我们建议您尽可能多地调用getCurrencyBalance，这样用户的余额始终是最新的。检查用户余额的常见地方是应用启动时，应用恢复时，Tapjoy广告关闭时以及位置内容关闭时。在广告内容关闭后的3.5秒内调用getCurrencyBalance（或在所使用的任何平台上的等效调用）通常特别有用。如果您在内容显示完毕后立即检查getCurrencyBalance，则在查询余额之前，奖励可能还没来得及添加到用户的余额中。

**注意：**需要特别注意的是，尽管Tapjoy尽最大努力尽快奖励用户，但我们不能保证立即获得用户奖励。有很多因素决定了奖励用户可能需要多长时间。最佳做法是，除了在视频广告关闭时检查之外，您还应定期并在某些应用事件（例如应用启动，应用恢复），两次更新之间，两次加载之前，商店加载之前检查余额是否已更新。我们还建议您让用户知道奖励可能要花一些时间。

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

可以使用如上方法调用获取余额API — 参数 “currencyName”对应货币名称，“amount” 对应余额。

更多实例请参考SDK包中示例程序。

Android 用法

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函数中返回。

React Native 用法

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包含一个包含货币金额的字符串。

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 中返回。

2. 检查用户是否成功获得货币

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

Android 用法

通过设置监听函数来获取某一用户是否被奖励货币:

// 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两个值。

3. 消费Tapjoy管理虚拟货币

通过调用以下这些函数来消费某个额度的虚拟货币:

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

可以使用spendCurrency消费虚拟货币。

Android 用法

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 用法

// 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中返回。

React Native 用法

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包含一个包含货币金额的字符串。

React Native用法

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

在React Native中，我们使用promise来实现 spendCurrency()，它接受金额作为参数。该 promise 解析后会返回一个字典或错误（应该被捕获）。字典的键 currencyName 保存的是货币金额的字符串。

AIR 用法

// 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 中返回。

4. 奖励Tapjoy管理虚拟货币

对于给您带来的不便，我们深表歉意，但任何希望使用此功能的新应用都需要咨询您的客户经理以获得批准。

通过调用一下函数来达到奖励用户虚拟货币的目的:

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

如上所述，您在awardCurrency完成有关奖励用户，其中参数“currencyName”为货币名称，“amount”为用户余额。

Android 用法

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 用法

// 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指针中返回。

React Native Instructions

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包含一个包含货币金额的字符串。

Air 用法

// 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 中返回。

5. 测试Tapjoy管理虚拟货币

如果您想在积分墙中查看测试广告，您可以在设置-应用设置-测试设备中添加一个测试设备。这样可以使您在积分墙上得到测试广告，帮助您测试您的虚拟货币功能

另一种测试的方式是正确实现Tapjoy管理虚拟货币之后，在Tapjoy控制面板中点击“获取用户余额”按钮：

如果在您的应用中得到的余额和使用工具得到的余额不同，很可能是因为您的应用没有和Tapjoy余额同步。您可以通过多次调用getCurrencyBalance来实现余额同步。

6. 最佳实践/更多信息

• 重要提示: 请确保验证awardCurrency和SpreadCurrency调用，并且只有在调用成功后才能解锁内容/购买。如果awardCurrency 和 spendCurrency调用失败，很有可能影响到账户余额的准确性。可以参考SDK中的TapjoyEasyApp示例代码。
• 一些开发者仅使用Tapjoy管理虚拟货币实现客户端通知，并将虚拟货币存储在本地。强烈建议您不要仅依赖本地存储的货币值。如果您遇到问题，我们将无法为您提供支持。如果这是一个问题，您可能必须考虑使用自管理的货币。
• 仅当您扣除用于解锁项目或内容的货币时，才应调用spendCurrency。
• Tapjoy管理虚拟货币每个应用程序ID仅支持1种货币。如果您使用多种货币，则需要使用自管理虚拟货币。
• 余额存储在每个应用程序对应的设备中，因此余额无法在设备之间共享。

注意: 需要特别注意的是，尽管Tapjoy尽其所能尽快奖励用户，但我们不能保证用户立即获得奖励。有许多因素决定了奖励用户可能需要多长时间。最佳做法是，除了在视频广告关闭时检查余额之外，您还应定期并在某些应用事件（例如应用启动，应用恢复）之后，在各个级别之间，在商店加载之前等，检查更新后的余额。我们还建议您让用户知道奖励可能要花一些时间。