Tapjoy-managed currency

Use Tapjoy Offerwall managed currency to store and manage user currency balances on Tapjoy's servers.

Read time 6 minutes

Last updated 6 months 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.


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

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 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.

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

getCurrencyBalance()

call triggers

onEarnedCurrency

with an amount of 25.


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

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

onSpendCurrencyResponseFailure(String error)

method.


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

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.


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.


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

Award Tapjoy-managed currency

Warning

To use this feature with new apps, contact your account manager for approval.

To award virtual currency to a user, use the platform-specific method detailed in the following sections.


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

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.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.


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

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.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Grow

Unity Ads Android SDK

Unity Ads iOS SDK

LevelPlay SDK

Grow

Tapjoy-managed currency

Get currency balance

Retrieve currency balances

Checking if the user has earned currency

Spend Tapjoy-managed currency

Award Tapjoy-managed currency

Test Tapjoy-managed currency

Best Practices and additional information