Use Tapjoy Offerwall managed currency to store and manage user currency balances on Tapjoy's servers.
Read time 6 minutesLast updated a month ago
Use Tapjoy-managed currency to store and manage users’ virtual currency amounts on Tapjoy’s servers. This free service, available to all developers integrating Tapjoy’s publisher SDKs, removes the need for back-end currency storage in your app.
Get currency balance
To check a user’s current virtual currency balance, use the methods outlined for each platform. The recommended best practice is to call
getCurrencyBalance
frequently to ensure the balance remains accurate. Common times to check a balance include when the following scenarios occur:
App launches
App resumes
Tapjoy views close
Placement content disappears
For best results, call
getCurrencyBalance
approximately 3.5 s after ad content finishes. This allows enough processing time for the reward to update. Immediate balance checks might not reflect newly earned rewards.
Retrieve currency balances
Tapjoy strives for prompot reward delivery. However, instant rewards aren’t guaranteed due to potential network delays. Notify your users that rewards from offers might take some time to appear. To maintain accuracy, check the balance at regular intervals and key app events, such as when the following events occur:
App launch
App resume
Between levels
Before store loading
Refer to the following platform-specific methods to retrieve currency balances:
To retrieve the current virtual currency balance for iOS devices, use the following method:
// 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]); }}];
The completion block returns the balance with
currencyName
as the currency’s name and
amount
as the user’s total. For implementation details, refer to the sample application in the SDK package.
To retrieve the current virtual currency balance for Android devices, use the following method:
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 receive the balance in the
onGetCurrencyBalanceResponse
callback and errors in
onGetCurrencyBalanceResponseFailure
. Call
getCurrencyBalance
at app startup and on resume to ensure accuracy. The spend and award callbacks also return the total balance and can be used to update your app.
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.
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 containing
currencyName
and
amount
, or results in an error if it fails.
// 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);}
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.
Checking if the user has earned currency
Notify users when they earn currency since the last balance check. Use the platform-specific instructions in the following sections to set up notifications.
Add a notification observer to detect earned currency for iOS devices:
// 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];}
To be notified whenever the user earns virtual currency (for example: 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 receive earned currency notifications in the
onEarnedCurrency(String currencyName, int amount)
callback within the
TJEarnedCurrencyListener
. For example, if the user's balance is 100 and they earn 25 from an offer, the next
You will be notified with the currency earned in the
OnEarnedCurrency
handler you specified, which will pass
currencyName
and
amount
earned parameters.
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.
Spend Tapjoy-managed currency
To spend some amount of virtual currency of a user, call the platform-specific method detailed in the following sections.
// 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]); }}];
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.
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
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.
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.
// 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);}
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.
Test Tapjoy-managed currency
To test offers in the Offerwall, add a test device to your application. This ensures that a test offer appears at the top of the Offerwall for validation.
Best Practices and additional information
Always validate
awardCurrency
and
spendCurrency
calls, and only unlock content if these calls succeed. If they fail, they might compromise the balance on the device..
Don't rely solely on locally stored currency; use Tapjoy’s servers for accuracy.
Only call spendCurrency when deducting currency for unlocking content.
Managed currency supports only one currency per app ID; use self-managed currency for multiple currencies.
Tapjoy stores the currency balance per device and app, preventing balance sharing between devices.
While Tapjoy aims for fast rewards, various factors might delay currency awards. Check balances at regular intervals after key app events and inform users of potential delays.