Table of Contents
- 1 Callback URL
- 2 User ID
- 3 Currency Multiplier Display
- 4 Switching from Managed to Non-Managed
Non-managed currency is used when you are handling the currency of your users with your own servers. This method can give you more control with your user’s currency but it also means that you are completely responsible for the back-end work for storing and handling the currency amounts for all your users. getTapPoints, awardTapPoints, or spendTapPoints are only available for Managed Currency. Tapjoy does not provide any client-side/app-side notifications for non-managed currency: you are responsible for notifying the app and your user when we call your callback server. You MUST set up a callback server to work with Non-Managed currency.
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, you should check for an updated balance at regular intervals and after certain app events like app launch, app resume, in between levels, video ad close, 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.
Follow the instructions below to learn how to set up non-managed currency.
When a user has earned currency by completing an offer, we will make an HTTP request to this URL. The format of the parameters will be:
The default request parameters include snuid (See User ID for more details) and currency (how much currency should be added to the user’s account), the user’s wifi mac_address (if available), and display_multiplier will be based on what you pass to setCurrencyMultiplier (default is 1.000000). If the offer was completed via tapjoy.com, mac_address will be blank.
Tapjoy servers will expect either a 200 or 403 response from your server.
Your server should respond with 200 only if:
- the user has successfully been awarded their currency.
Your server should respond with 403 if:
- the verifier parameter does not match the calculated value
- the snuid parameter is unknown to your system
- if there was any other error that should not be retried.
Tapjoy will continue to retry if Tapjoy servers receive a timeout. We’ll retry every 2 minutes for 4 days. We will treat the request as having failed if your server takes more than 20 seconds to respond. NOTE: The response body of the callback URL responses needs to be in UTF-8. If they are not in UTF-8 we will retry even if you return a 200.
Optional Parameters for fraud detection/prevention:
You specify a Virtual Currency Secret Key in Dashboard -> Setting -> Content -> Virtual Currency. (This key is different from the Application SDK Key.) Use this Virtual Currency Secret Key to sign the callback:
If a secret key in the Currency is present (
secret_key=) then we will add the following parameters to the callback request:
- id – An identifier to mark the specific currency awarded which will always be unique.
- verifier – a MD5 hash of the id, snuid, currency and secret key (see below)
2 Fraud Scenarios to always look out for:
- If you see a id being reused and/or an incorrect verifier the callback URL is not coming from Tapjoy and should be considered fraudulent.
- If your user id’s contain strictly only integers we recommend that you perform a simple validation to make sure the user ID isn’t being manipulated. For example, Tapjoy considers “001234″ and “1234″ 2 separate user ID’s while your backend server logic may not.
The verifier is computed by taking the MD5 hash of the id, snuid, currency and secret key, separated by colons. In Ruby code, this would be:
Your server should recompute the verifier and reject any requests that do not match. The server should respond with a 403 Forbidden if the verifier doesn’t match.
The setUserID is the MOST IMPORTANT call that you need to make if you’re managing your own currency. The value set in setUserID is what the snuid is set to in the Callback URL. It should be called immediately after requestTapjoyConnect on the every app launch. If set incorrectly, your users will not be rewarded and you will not get paid. setUserID should be set to the user’s unique ID in your game (such as a username or email address).
Only in the off chance your game doesn’t have unique ID, then we recommend that you set it as follows:
- On iOS 6 or above, call setUserID(“vendor_id:”).
- On iOS 5 or below, call setUserID(“mac_address:
- On cellular Android devices, call setUserID(“device_id:”).
- On wifi-only Android devices (such as a Nexus 7), call setUserID(“device_id:”.)
The User ID can be up to 190 characters long. The value set in setUserID is what the snuid is set to in the Callback URL.
TROUBLESHOOTING: If you are calling setUserID and the snuid in the callback URL isn’t a value you expect, then you need to call setUserID before the user goes to the in-app offerwall or tapjoy.com to complete offers. Tapjoy will send device id as snuid in the callback URL if there is no userID associated with a device. For example, a user could launch the app but then go to tapjoy.com before your app sends us the userID. To prevent this you need to make sure setUserID is called on every launch after the connect call.
If your application uses a currency multiplier, for instance the user earns more currency as they level up, then you can use a currency multiplier to allow your users to earn more currency for each offer. Note that this only affects the display of currency earned, and not the actual amount earned, so you will have to multiply the currency from your end when you receive the callback from our servers. Note that this can not be used with Tapjoy managed currency.
// Where mult is the currency multiplier value. + (void)setCurrencyMultiplier:(float)mult;
// Where mult is the float currency multiplier value. Tapjoy.setCurrencyMultiplier(float mult)
If you have an application that has currency managed by Tapjoy, but you want to switch to managing it yourself here are a few things to consider:
- You’ll need to create a new App ID. This ensures that users who are using an old version of your App that hasn’t upgraded to the latest version won’t be affected. If you use the same App ID, all your old users won’t be rewarded for completing offers.
- You’ll need to disable any Advertising campaigns pointing to the old App ID, and recreate any Advertising campaigns to point to the new App ID.
- Switching to non-managed will require code changes in your app. You will not be able to use getTapPoints, awardTapPoints, or spendTapPoints as they’re only available for Managed Currency.
- We recommend that you contact your Account Manager before considering making the change.
To migrate user’s balance, we recommend follow these steps:
- On first launch, use the existing app id’s and call getTapPoints to retrieve the balance.
- Update your balance with the value returned by getTapPoints.
- On all subsequent launches, use the new app id.