Documentation

Support

Offerwall

Get started with Monetization

Get started with User Acquisition

Unity SDK integration

Offerwall

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 minutesLast updated a day 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, etc.) 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>// Examplehttp://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
    .

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

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

Reward Callback IP allowlisting

If your callback server restricts access, allowlist the following Tapjoy IP addresses: 
  • 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.