Self-managed currency

Set up Tapjoy Offerwall with a self-managed virtual currency by configuring reward callbacks and handling transactions on your server.

Read time 6 minutes

Last updated 5 months ago

Use self-managed currency to manage your users' virtual currency directly on your own servers. This approach provides greater control compared to Tapjoy-managed currency, but it also requires you to handle all back-end processes, including storing and updating currency balances.

Unlike Tapjoy-managed currency, self-managed currency doesn't support functions such as

getCurrencyBalance

awardCurrency

, or

spendCurrency

. Additionally, Tapjoy doesn't provide client-side or app-side notifications for self-managed currency. you're responsible for informing the app and your users when Tapjoy contacts your callback server.

Self-managed currency has the following unique requirements:

Delayed Rewards: Tapjoy aims to reward users as quickly as possible but can't guarantee instant delivery. To ensure accurate balance updates, check for changes at regular intervals, such as during app launch, resume events, level transitions, video ad completion, and before store interactions. Inform your users that completing an offer might take some time before the reward appears.
Platform-Specific Currency: Each platform (iOS, Android) requires its own distinct currency setup, even when self-managed.

Callback URL

When a user earns currency through an offer, Tapjoy sends an HTTP GET request to your specified callback URL. The request includes the following parameters:

```
snuid
```
: The user ID.
```
currency
```
: The amount of currency to add to the user's account.
```
mac_address
```
: The user's Wi-Fi MAC address (if available).

Refer to the following callback example:


  <callback_url>?snuid=<user_id>&currency=<currency>&mac_address=<mac_address>  // Example  http://www.sampledoman.com/payments/offers/tapjoy?&amp;snuid=42&amp;currency=50&amp;mac_address=00-16-41-34-2C-A6

Server response requirements

Your server must respond with one of the following HTTP status codes:

Status code	Cause
`200 OK`	The user received their currency.
`403 Forbidden`	The verifier parameter doesn't match the expected value. The snuid parameter is unknown. Any other error that prevents further retry attempts.

Tapjoy retries the request in the following situations:

If Tapjoy doesn't receive a
```
200
```
or
```
403
```
response, it retries the request every five mins for up to four days.
If your server takes longer than 5 s to respond, Tapjoy treats the request as failed and retries the request.
Responses must be UTF-8 encoded; otherwise, Tapjoy will retry even if the server returns a
```
200
```
.

Note

Don't award currency to the user if your server returns a non-200 response. Tapjoy will continue retrying, which might lead to duplicate rewards.

Fraud detection or prevention parameters

Use a virtual currency secret key to enhance security. Go to Monetize > Virtual Currency > Create/Edit in the Tapjoy Dashboard to configure your secret key. This key differs from the Application SDK Key and signs the callback.

Currencies with a virtual currency secret key have the following additional security parameters:

ID: A unique identifier for the reward request (distinct from
```
currency_id
```
)
Verifier: An MD5 hash of ID, snuid, currency, and the secret key.

Fraud scenarios to monitor

Consider the following fraud scenarios when you manage your currencies:

If you encounter a reused ID or the verifier is incorrect, the callback URL might not originate from Tapjoy and you can consider it fraudulent.
If your user IDs only contain integers, validate the snuid to prevent manipulation. For example, Tapjoy considers
```
001234
```
and
```
1234
```
as two separate user IDs. However, your back end server logic might not.

Verifier calculation

The verifier is an MD5 hash with the following format:


Digest::MD5.hexdigest("#{id}:#{snuid}:#{currency}:#{secret_key}")

Your server must recompute the verifier and returns a

403 Forbidden

response if any requests don't match. Use a unique secret key for each application to avoid cross-application reward issues.

Each application must have a separate secret key. Don't use the same secret key for all applications, as this might reward users across multiple applications simultaneously.

Improved callback URL

A more secure callback format is available through Tapjoy Support. This version uses a POST request with a JSON payload and SHA256 Hash-Based Message Authentication Code (HMAC) verification. Contact your account manager or support team to enable this feature.

When a user earns currency, Tapjoy sends a POST request to your provided URL. Tapjoy generates the verifier from the request body and your shared secret key (found in the Tapjoy Dashboard), and includes it in the request headers.

Tapjoy signs the request by using a structure similar to the following example:


{   "cp": "some_string",   "currency": {      "currency_sale": "1.0",      "id": "reward_id",      "reward": 100   },   "id": "some_id",   "offer": {      "advertiser_app_name": "a_cool_app",      "currency": {         "max_reward_value": 1360      },      "expires_at": 1768175428,      "icon_url": "some_URL/icon.jpg",      "name": "eye_catching_headline",      "task":{         "is_iap": false,         "name": "event_name"      },      "type": ""   },   "placement":{      "content_type": "offerwall",      "name": "placement_name"   },   "rev": 100,   "timestamp": 1762993750,   "user": {      "id": "user_id"   }}

Parameter

Type

Description

id

stringThe unique reward id for this request.

rev

doubleRevenue in USD Dollars earned.

cp

stringThe custom parameter passed through the SDK via the setCustomParameter method.

currency.id

stringThe unique identifier for this currency.

currency.reward

integerCurrency amount rewarded to user.

currency.currency_sale

floatCurrency sale multiplier (when applicable).

currency.max_reward_value

integerThe maximum currency the user can earn if they complete all tasks for this offer.

offer.name

stringName of the advertiser offer.

offer.type

stringThis is not currently supported.

offer.icon_url

stringIcon URL of the offer.

offer.advertiser_app_name

stringAdvertiser's app name.

offer.task.name

stringName or description of the completed task that the user receives a reward for.

offer.task.is_iap

booleantrue if the rewarded event is for an IAP event.

offer.expires_at

timestampThe timestamp (in seconds) after which the user can no longer earn rewards for this offer.

placement.name

stringThe placement associated with this conversion.

placement.content_type

stringThe type of the placement used.

user.id

stringThe user ID passed through the SDK via the setUserID method.

timestamp

timestampThe timestamp of this transaction.

Tapjoy signs the request by using the following format:


HMAC_SHA-256(<Request-Body>,<Secret-Key>)

The following example demonstrates the Tapjoy header with signature:


X-Tapjoy-Signature => 7205ccfdfa1fe28cd05a1b56a9508d898cc938aa555a6c18848097fe4ee0975b

Setting the User ID

For self-managed currency, setting a unique

user_id

before any Tapjoy interaction is important to ensure that users receive their rewards. This value becomes the snuid in the callback URL. Set the

user_id

with connect flags during the initial connection, before any content requests. If set incorrectly, your users can't receive their rewards, and you can't receive revenue.

Refer the following requirements when you set a

user_id

for your currency:

Use a unique, numeric ID (up to 190 characters).
Avoid identifiable information (for example: usernames, real names, emails) for GDPR compliance.
Keep the ID consistent for each user's lifetime to support security and fraud detection.

If unset, Tapjoy defaults to a device ID (typically the Advertising ID), which might vary based on SDK version, device, or operating system.

The following code samples demonstrate how to use the connect flag and how to call the setUserID API directly (after connection) if necessary. When calling the API directly, use the callbacks to ensure your ID sets successfully. The recommended best practice is to use the connect flag where possible.


// Recommended approach using connect flagNSDictionary *connectFlags = @{TJC_OPTION_USER_ID : @"<USER_ID_HERE>"};[Tapjoy connect:@"SDK_KEY_GOES_HERE" options:connectFlags];// Setting the user id directly[Tapjoy setUserIDWithCompletion:@"<USER_ID_HERE>" completion:^(BOOL success, NSError *error) {}];


// Recommended approach using connect flagHashtable<String, Object> connectFlags = new Hashtable<String, Object>();connectFlags.put(TapjoyConnectFlag.USER_ID, "<USER_ID_HERE>"); // Important for self-managed currencyTapjoy.connect(getApplicationContext(), "SDK_KEY_GOES_HERE", connectFlags, new TJConnectListener() {...});// Setting the user id directlyTapjoy.setUserID("<USER_ID_HERE>", new TJSetUserIDListener() {  @Override  public void onSetUserIDSuccess() {      }  @Override  public void onSetUserIDFailure(String error) {  }});


// Recommended approach using connect flagDictionary<string,string> connectFlags = new Dictionary<string,string>();connectFlags.Add("TJC_OPTION_USER_ID", "<USER_ID_HERE>");#if UNITY_ANDROID  Tapjoy.Connect("your_android_sdk_key", connectFlags);#elif UNITY_IOS  Tapjoy.Connect("your_ios_sdk_key", connectFlags);#endif// Callbacks for SetUserIDTJPlacement.OnSetUserIDSuccess += HandleOnSetUserIDSuccess;TJPlacement.OnSetUserIDFailure += HandleOnSetUserIDFailure;// Setting the user id directlyTapjoy.SetUserID("<USER_ID_HERE>")


// Recommended approach using connect flagtry {  let flags: object = { TJC_OPTION_USER_ID: '<userId>' };  await Tapjoy.connect('<sdk_key>', flags);} catch (error) {  console.log(error);}// Setting the user id directlytry {  await Tapjoy.setUserId('<userId>');} catch (error) {  console.log(error);}

You can find further examples on the Quickstart page for each platform.

Setting the user balance

Update Tapjoy with the user's current balance each time you request a placement, before loading content. This ensures accurate tracking for self-managed currency.


TJPlacement *placement = [TJPlacement placementWithName:@"placementName" delegate:nil];[placement setBalance:100 forCurrencyId:@"1234" withCompletion:^(NSError * _Nullable error) {    if (error != nil) {        //Failure        NSString *message = error.localizedDescription;    } else {        //Success    }}];


TJPlacement placement = Tapjoy.getPlacement("placement", this);placement.setCurrencyBalance("1234", 100, new TJSetCurrencyBalanceListener() {    @Override    public void onSetCurrencyBalanceSuccess() {            }    @Override    public void onSetCurrencyBalanceFailure(int code, String error) {    }});


TJPlacement placement = TJPlacement.CreatePlacement("placementName");placement.SetCurrencyBalance("[CURRENCY_ID]", 100);// Optional callbacksvoid OnEnable() {	    TJPlacement.OnSetCurrencyBalanceSuccess += HandleSetCurrencyBalanceSuccess;	    TJPlacement.OnSetCurrencyBalanceFailure += HandleSetCurrencyBalanceFailure;	}void OnDisable() {	    TJPlacement.OnSetCurrencyBalanceSuccess -= HandleSetCurrencyBalanceSuccess;	    TJPlacement.OnSetCurrencyBalanceFailure -= HandleSetCurrencyBalanceFailure;}public void HandleSetCurrencyBalanceSuccess(TJPlacement placement) {}public void HandleSetCurrencyBalanceFailure(TJPlacement placement, int code, string error){}


let placement = new TJPlacement('placementName');try {  await placement?.setCurrencyBalance('1234', 100);} catch (e: any) {  let code = e.code;  let message = e.message;}

Required amount

If you set the balance, you can also set the required amount value on a placement.


TJPlacement* placement = [TJPlacement placementWithName:@"placementName" delegate:nil];placement setRequiredAmount:100 forCurrencyId:@"1234" withCompletion:^(NSError * _Nullable error) {    if (error != nil) {        //Failure        NSString *message = error.localizedDescription;    } else {        //Success    }}


TJPlacement placement = Tapjoy.getPlacement("placement", this);placement.setCurrencyAmountRequired("1234", 100, new TJSetCurrencyAmountRequiredListener() {    @Override    public void onSetCurrencyAmountRequiredSuccess() {            }    @Override    public void onSetCurrencyAmountRequiredFailure(int code, String error) {    }});


TJPlacement placement = TJPlacement.CreatePlacement("placementName");placement.SetRequiredAmount("[CURRENCY_ID]", 200); // Optional callbacksvoid OnEnable() {	    TJPlacement.OnSetCurrencyAmountRequiredSuccess += HandleSetRequiredAmountSuccess;	    TJPlacement.OnSetCurrencyAmountRequiredFailure += HandleSetRequiredAmountFailure;}void OnDisable() {	    TJPlacement.OnSetCurrencyAmountRequiredSuccess -= HandleSetRequiredAmountSuccess;	    TJPlacement.OnSetCurrencyAmountRequiredFailure -= HandleSetRequiredAmountFailure;}public void HandleSetCurrencyBalanceSuccess(TJPlacement placement){}public void HandleSetCurrencyBalanceFailure(TJPlacement placement, int code, string error){}public void HandleSetRequiredAmountSuccess(TJPlacement placement){}public void HandleSetRequiredAmountFailure(TJPlacement placement, int code, string error){}


let placement = new TJPlacement('placementName');try {await offerwallPlacement?.setRequiredAmount(100, '100');} catch (e: any) {  let code = e.code;  let message = e.message;}

Reward Callback IP allowlisting

If your callback server restricts access, allowlist the following Tapjoy IP addresses:

Note

This list is accurate as of Sunday, May 12, 2024.

```
18.215.207.89
```
```
18.235.142.165
```
```
23.20.255.113
```
```
23.23.134.165
```
```
3.210.188.32
```
```
3.215.42.140
```
```
3.217.209.177
```
```
3.218.95.35
```
```
3.219.236.53
```
```
3.231.137.161
```

Troubleshooting

If you receive an unexpected snuid in the callback URL, ensure that you call

setUserID

on every app launch after the connect call before users access the offers.

If there's not a user ID associated with the device, Tapjoy will send a device ID as snuid in the callback URL. For example, a user might launch the app but then navigate to the Tapjoy website before your app sends the userID. To prevent this, ensure the server calls

setUserID

on every launch after the connect call.

If you haven't set the user ID, the system will attempt to use the best available device ID. Usually, this will be the Advertising ID for the device. However, depending on the SDK version, device model/version, device operating system (OS) version, and Google Play Services, the exact ID might vary. Other possible values include the Android ID, udid, and mac_address.

Documentation

Development

User Acquisition

Monetization

Industry