Tapjoy-Managed Currency

Tapjoy managed currency enables you to use Tapjoy’s servers to store your user’s currency amount. This is a free service provided by Tapjoy for all developers that integrate Tapjoy’s publisher SDKs. This eliminates the back-end work normally needed to store your user’s currency data for your application. Integration is relatively simple and integration instructions are detailed below.

1. Get Currency Balance

To get the current virtual currency of a user, call the following method:

VIRTUAL CURRENCY BEST PRACTICE: We recommend calling getCurrencyBalance as often as possible so the user’s balance is always up-to-date. Common places to check the user’s balance are when the app launches, when the app resumes, when Tapjoy views close, and when placement content disappears. It is often particularly useful to call getCurrencyBalance (or the equivalent call on whatever platform you are using) 3.5 seconds after advertising content disappears. This gives the reward time to get through our system by the time you check for the currency balance. If you check getCurrencyBalance immediately after the content is finished displaying, the reward might not have time to appear in the user’s balance before the balance is queried.

NOTE: It’s important to note that while Tapjoy does its best to reward users as quickly as possibly we can’t guarantee that the user will be rewarded instantaneously. There are a lot of factors that determine how long it may take to reward a user. As a best practice, in addition to checking when the video ad closes you should check for an updated balance at regular intervals and after certain app events like app launch, app resume, in between levels, before your store loads, etc. We also recommend that you let your users know that it may take some time before an offer gets completed.

iOS Instructions

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

As described above, you will be notified about the currency balance in the completion block, with the parameter “currencyName” providing the name of the currency and “amount” providing the user’s balance.

For implementation details, refer to the sample application in the SDK package.

Android Instructions

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

You will be notified with the currency balance in the onGetCurrencyBalanceResponse(String currencyName, int balance) callback method in the TJGetCurrencyBalanceListener you specified. You will be notified of an error condition in the onGetCurrencyBalanceResponseFailure(String error) callback method.

NOTE: It is best to call getCurrencyBalance(…) on application startup and resume. The callback notifiers for SPEND and AWARD currency also return the total virtual currency balance of the user, so use these to update the total amount of currency the user has.

Unity Instructions

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

You will be notified about the currency balance in the OnGetCurrencyBalanceResponse handler you specified, which will pass currencyName and balance parameters. You will be notified of an error in the OnGetCurrencyBalanceResponseFailure handler.

React Native Instructions

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

We use a promise in React Native for getCurrencyBalance() which takes no parameters. The promise resolves with a dictionary or an error (which should be caught). The dictionary key currencyName holds a String with the currency amount.

AIR Instructions

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

You will be notified about the currency balance in the TJCurrencyEvent.GET_CURRENCY_BALANCE_SUCCESS handler you specified, which will pass a TJCurrencyEvent object. This object contains currencyName and balance properties. You will be notified of an error in the TJCurrencyEvent.GET_CURRENCY_BALANCE_FAILURE handler.

2. Checking if the user has earned currency

iOS Instructions

In order to notify users that they’ve earned virtual currency since the last time the last time the app queried the user’s currency balance, set a notification observer:

// 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 Instructions

To be notified whenever the user earns virtual currency (eg. through Offers), set up your earned currency listener with the following method:

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

You will be notified with the currency earned in the onEarnedCurrency(String currencyName, int amount) callback method in the TJEarnedCurrencyListener you specified. For example if the current currency balance is 100 and the user completes an Offer for 25 currency, the next time getCurrencyBalance() is called, the onEarnedCurrency method will fire with an amount of 25.

Unity Instructions

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

You will be notified with the currency earned in the OnEarnedCurrency handler you specified, which will pass currencyName and amount earned parameters.

AIR Instructions

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

You will be notified about the currency earned in the TJEarnedCurrencyEvent.EARNED_CURRENCY handler you specified, which will pass a TJEarnedCurrencyEvent object. This object contains currencyName and amount properties.

3. Spend Tapjoy Managed Currency

To spend some amount of virtual currency of a user, call the following method:

iOS Instructions

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

As described above, you will be notified about the currency balance in the completion block, with the parameter “currencyName” providing the name of the currency and “amount” providing the user’s balance.

Android Instructions

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

You will be notified with the currency balance in the onSpendCurrencyResponse(String currencyName, int balance) callback method in the TJSpendCurrencyListener you specified. You will be notified of errors in the onSpendCurrencyResponseFailure(String error) method.

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

You will be notified about the currency balance in the OnSpendCurrencyResponse handler you specified, which will pass currencyName and balance parameters. You will be notified of an error in the OnSpendCurrencyResponseFailure handler.

React Native Instructions

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

We use a promise in React Native for spendCurrency() which takes the amount as a parameter. The promise resolves with a dictionary or an error (which should be caught). The dictionary key currencyName holds a String with the currency amount.

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

You will be notified about the currency balance in the TJCurrencyEvent.SPEND_CURRENCY_SUCCESS handler you specified, which will pass a TJCurrencyEvent object. This object contains currencyName and balance properties. You will be notified of an error in the TJCurrencyEvent.SPEND_CURRENCY_FAILURE handler.

4. Award Tapjoy Managed Currency

Apologies for any inconvenience, but any new apps that wish to use this feature, needs to consult with their account manager to get approval.

To award some amount of virtual currency of a user, call the following method:

iOS Instructions

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

As described above, you will be notified about the currency balance in the completion block, with the parameter “currencyName” providing the name of the currency and “amount” providing the user’s balance.

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

You will be notified with the currency balance in the onAwardCurrencyResponse(String currencyName, int balance) callback method in the TJAwardCurrencyListener you specified.

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

You will be notified about the currency balance in the OnAwardCurrencyResponse handler you specified, which will pass currencyName and balance parameters. You will be notified of an error in the OnAwardCurrencyResponseFailure handler.

React Native Instructions

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

We use a promise in React Native for awardCurrency() which takes the amount as a parameter. The promise resolves with a dictionary or an error (which should be caught). The dictionary key currencyName holds a String with the currency amount.

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

You will be notified about the currency balance in the TJCurrencyEvent.AWARD_CURRENCY_SUCCESS handler you specified, which will pass a TJCurrencyEvent object. This object contains currencyName and balance properties. You will be notified of an error in the TJCurrencyEvent.AWARD_CURRENCY_FAILURE handler.

5. Testing Managed Currency

If you want to view test offers in the Offerwall, you can add a test device to your application. This will allow a test offer to appear at the top of the Offerwall so you can easily test currency

Another tool you can use to verify that your Tapjoy Managed Currency implementation is working correctly is the "Get User Balance" tool on the Tapjoy dashboard:

If your app shows a different balance for a user than what this tool shows, it is likely your app has gotten out of synch with the Tapjoy balance. Usually this can be corrected by making sure your app calls getCurrencyBalance sufficiently frequently.

6. Best Practices/More Info

• IMPORTANT: Be sure to validate awardCurrency and spendCurrency calls and ONLY unlock content/purchases if the calls succeed. If the awardCurrency and spendCurrency calls fail, there is a high probability that the balance on the device has been compromised. Check the Tapjoy EasyApp project included with the SDK for examples.
• Some publishers have implemented Managed Currency only for client side notifications, and store the currency locally. We strongly recommend that you do NOT rely solely on locally stored currency value. We will not be able to support you if you run into issues. If this is an issue you may have to consider using Self-Managed Currency.
• spendCurrency should only be called if you are deducting currency for unlocking an item or content.
• Managed currency only supports 1 currency per app id. If you have multiple currencies you’ll need to use Self-Managed Currency.
• The balance is stored per device per app so a balance can’t be shared between devices.

NOTE: It’s important to note that while Tapjoy does its best to reward users as quickly as possibly we can’t guarantee that the user will be rewarded instantaneously. There are a lot of factors that determine how long it may take to reward a user. As a best practice, in addition to checking when the video ad closes you should check for an updated balance at regular intervals and after certain app events like app launch, app resume, in between levels, before your store loads, etc. We also recommend that you let your users know that it may take some time before an offer gets completed.