Can I use server-to-server (S2S) callbacks for rewarded ads?

Server-to-Server (S2S) Callbacks

Server-to-server callbacks enable you to reward users for ad views with in-game currency or other rewards. When a user successfully completes an ad view, you can configure a callback from Liftoff's servers to your own to notify you of the user's completed action.

One benefit of this approach is control. This method allows you to make changes and updates directly on the server side, so there's no need to push an update. Another benefit is security in preventing replay attacks (when a valid data transmission is maliciously or fraudulently repeated or delayed).

Implementation

  • Note for Liftoff Monetize SDK v. 6.x: Starting with SDK v. 6.1, we have moved the rewarded option to the dashboard, so that publishers can easily change the option without a code change. In your dashboard, you just need to create a placement with Rewarded Placement type.
  • Notes for Liftoff Monetize SDK v.1.0 - v.4.1:
    • For iOS, begin by setting the vunglePlayAdOptionKeyIncentivized option in your playAd object to ‘yes’. 
    • For Android, begin by setting the setIncentivizedFields option in your AdConfig object to ‘true’. 

Implementation for all Liftoff Monetize SDK Versions

When a user watches 80% or more of a rewarded ad, it is considered a completed view. Liftoff will then ping your servers with a callback URL, which looks something like this:

http://acme.com/bugzBunny/reward?amount=1&uid=%user%&etxid=%etxid%&edigest=%edigest%

We recommend using etxid and edigest, like this:

http://acme.com/bugzBunny/reward? amount=1&uid=%user%&txid=%txid%&digest=%digest%

Or use txid and digest that has been traditionally offered like this:

http://acme.com/bugzBunny/reward?amount=1&uid=%user%&txid=%txid%&digest=%digest%

Configure the callback URL in your app's Settings on the dashboard (as shown below).

20191225164338dama.png

Most publishers only use %user%, %etxid%, and %edigest% for security, but all of the following are available:

Variables

Description

%user%

The username provided to the Liftoff Monetize SDK via:

●      iOS: The VunglePlayAdOptionKeyUser key of the options dict passed to playAd()

●      Android: The Vungle.setIncentivizedUserId passed to playAd()

%udid%

A unique identifier for the device

%ifa%

●      iOS: Apple's unique identifier for the device.

●      Android: This will return the Google Advertiser ID

%etxid%

A unique transaction ID for the completed view with server timestamp; transactionID:timestamp (recommended)

%edigest%

Security token to verify that the callback came from Liftoff; refer to the Security section for details (recommended)

%txid%

A unique transaction ID for the completed view

%digest%

Security token to verify that the callback came from Liftoff; refer to the Security section for details

Note that %user% is the only variable you need to pass in. The rest will come back from Liftoff's servers if you include them in the callback URL.

Reward Configuration

Now that you can reward a user for watching an ad, what do you give them? If you're giving out gems every time, it's pretty straightforward. But what if you want to get a bit more advanced? We don't have a built-in option for reward configuration, but here's what we recommend:

Example: Coins vs. Lives

Let's say your app has rewarded ads in multiple places: both in your shop and at every third “game-over.” You want to reward the player with coins in the shop, and with a life at game-over. For each instance of playAd(), configure the user like this: 

userName123:coins or userName123:lives 

Then, when your servers receive Liftoff's callback, parse %user% for the correct reward!

Security

Authenticating Callbacks

In order to verify that callbacks you receive originated from Liftoff, select the Secret Key for Secure Callback checkbox for your application. This will generate a secret key like this:

4YjaiIualvm8/4wkMBRH8pctlqB1NyzhK3qUGUar+Zc=

20191225163949dama.png

You can use the key to verify the origin of the callback as follows:

  1. Create the raw transaction verification string by concatenating your secret key with the transaction ID, separated by a colon, like this:
    transactionString = secretKey + ":" + %txid% or %etxid%
  2. Hash the bytes of the transactionString twice using the SHA-256 algorithm.
  3. Generate the transaction verification token by hex-encoding the output bytes of two sequential rounds of SHA-256 hashing, which will look something like this:
    transactionToken = 870a0d13da1f1670b5ba35f27604018aeb804d5e6ac5c48194b2358e6748e2a8
  4. Check that the transactionToken you generated equals the one sent in the callback query string as %digest% or %edigest%

De-Duplicating Callbacks And Preventing Replay Attacks

There can be events where duplicate callbacks can reach your server due to network issues and replay attacks. To prevent a single callback from being replayed multiple times against your server, store authenticated transaction IDs and reject future callbacks with duplicate transaction IDs.

Using etxid (recommended)

etxid consists of hashed value that is unique for each advertisement event, followed by server side timestamp, therefore the entire string will be also unique.

Using txid

txid consists of hashed value of device ID, followed by device level timestamp, therefore you must incorporate the timestamp to enforce a cutoff line for rewarding.

  1. Extract the timestamp (in milliseconds) from the transaction ID like this: 
    transactionMillis = transactionId.substringAfter(":")
  2. Check that transactionMillis is later than your cutoff and that transactionId has not been encountered since your cutoff.

Sample Code

These bits of sample code will help you implement server-to-server callbacks security! We have examples for: Node.js, Java, Python, and Ruby. Note that:

  • The transaction_id can be %txid% or %etxid% (recommended).
  • For %etxid%, the verification hash should be %edigest%.
Node.jsJavaPythonRuby
var crypto = require('crypto');

function isTransactionValid(secret, transaction_id, provided_hash) {
  return isTransactionRecent(transaction_id) &&
         isTransactionNew(transaction_id)    &&
         createSecurityDigest(secret, transaction_id) === provided_hash;
}

function getTransactionTimestamp(transaction_id) {
  return parseInt(transaction_id.split(":")[1], 10) || null;
}

function isTransactionRecent(transaction_id) {
  // Does the transaction have a reasonable format?
  var tx_timestamp = getTransactionTimestamp(transaction_id);
  if (tx_timestamp === null) { return false; }

  // Is the transaction within a reasonable time range?
  var now = new Date().getTime();
  var time_diff = now - tx_timestamp;
  var hour_in_future = -1000 * 60 * 60, three_days_ago = 1000 * 60 * 60 * 24 * 3;
  return (time_diff < three_days_ago && time_diff > hour_in_future);
}

// Have we seen this transaction before?
// NOTE: To scale beyond just this one node process, you'll need to put this in some
// sort of centralized datastore. Any one that supports atomic insertions into a set
// should do. The Redis database, with its SADD command, would be a good place to start.
var known_transactions = {};
function isTransactionNew(transaction_id) {

// For %etxid%, extract unique event id from etxid, which is the string before “:”, and use it to identify unique ad events
if (known_transactions[transaction_id]) { return false; } known_transactions[transaction_id] = true; return true; } function createSecurityDigest(secret, transaction_id) { var firsthash = crypto.createHash("sha256").update(secret + ":" + transaction_id).digest("binary"); return crypto.createHash("sha256").update(firsthash,"binary").digest("hex"); }

 

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?