Self-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. getCurrencyBalance, awardCurrency, or spendCurrency are only available for Managed Currency. Tapjoy does not provide any client-side/app-side notifications for self-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 self-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.
Note: Each platform must have its own currency, even if it is self managed.
When a user has earned currency by completing an offer, we will make an HTTP GET request to this URL. The format of the parameters will be:
<callback_url>?snuid=<user_id>¤cy=<currency>&mac_address=<mac_address> //Example http://www.sampledoman.com/payments/offers/tapjoy?&snuid=42&currency=50&mac\_address=00-16-41-34-2C-A6
The default request parameters include snuid and currency (how much currency should be added to the user’s account), and the user’s wifi mac_address (if available).
Tapjoy servers will expect either a 200 or 403 response from your server.
Your server should respond with 200 only if:
Your server should respond with 403 if:
Tapjoy will continue to retry if Tapjoy servers receive any response other then 200 or 403. (Note that it is very important NOT to actually reward the user if you are giving a non-200 response, as Tapjoy will continue to re-attempt the callback, possibly resulting in large numbers of duplicate rewards.) We’ll retry every 2 minutes for 4 days. We will treat the request as having failed if your server takes more than 5 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.
You can access your Virtual Currency Secret Key in Dashboard > Monetize > Virtual Currency > Create/Edit. 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:
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.
Note that each application should have a separate secret key. Please do not use the same secret key for all of your applications, as this might lead to a situation where rewarding a user in one application will also reward the user in the other application. Also the id above represents the request_id not currency_id.
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 as soon as the TapjoyConnect call succeeds on every app launch. Please wait for the TapjoyConnect call to succeed before setting the user ID, but make sure you set it before requesting ad content (In SDK versions 11.7+, Tapjoy implemented success/failure callbacks to our SDK. It may be advisable to build in logic that listens for these callbacks before requesting content). If set incorrectly, your users will not be rewarded and you will not get paid. The setUserID parameter should be set to a unique user ID (typically a number). For data security and GDPR compliance purposes, the setUserID parameter should not include any recognizable or identifiable information, such as a username, real name, or email address. For security and fraud detection purposes, the user ID should be constant for the lifetime of the user. (Do not, for example, use the user ID parameter to communicate information like the user’s level or score.)
Only in the off chance your game doesn’t have unique ID, then we recommend that you set it as follows:
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.
[Tapjoy setUserID:@"userID"]; // only do this call AFTER the Tapjoy Connect call succeeds
Tapjoy.setUserID(String userID); // only do this call AFTER the Tapjoy Connect call succeeds
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 you have not set the user ID the system will attempt to use the best-available device ID. In most cases this will be the Advertising ID for the device. However, depending on SDK version, device model/version, device OS version, and Google Play Services the exact ID may vary. Other possible values include the Android ID, udid, and mac_address.
There may be scenarios where no callback is preferred. In this case entering
NO_CALLBACK for the URL will avoid an unnecessary call to your servers.
Mediation is a common reason to use
NO_CALLBACK. If your mediator is handling the rewarding it is unlikely you will need a callback from Tapjoy. Instead of sending zero rewards from fixed rewarded video units, the
NO_CALLBACK can be provided for the currency callback URL which will avoid making this call.
If you are using both our Offerwall and Video products we recommend using separate currencies: one for each type of content. This allows for easier debugging in case of errors. It is also useful in case you ever switch to using mediation for Video, in which case you may no longer need a callback.
If you haven’t launched your app to actual users yet, You can switch a Tapjoy Managed currency to a Self-Managed Currency via the Edit Virtual Currency screen in the Tapjoy dashboard. Be sure to put a properly formatted URL(or "NO_CALLBACK") into the callback URL box , otherwise the change will not actually take place.
If you have a live application that has currency managed by Tapjoy, the process of switching is a bit more complex. Here are a few things to consider:
To migrate user’s balance, we recommend follow these steps: