Tapjoy-Managed Currency
Use Tapjoy Offerwall managed currency to store and manage user currency balances on Tapjoy's servers.
Read time 8 minutesLast updated 3 hours ago
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.
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.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.// 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]); } }];
Checking if the user has earned currency
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]; }
Spend Tapjoy Managed Currency
To spend some amount of virtual currency of a user, call the following method: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.// 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]) } }];
Award Tapjoy Managed Currency
To award some amount of virtual currency of a user, call the following method:
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.// 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]) } }];
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:
Best Practices
- 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.