Rewarded Video Server-side Setup

Publishers have the option to reward their users using a server-side callback to their reward server.

How Rewarded Video Server-Side Callbacks work:

Upon the completion of a rewarded video, the MoPub SDK will notify the MoPub ad server of the completed video. The MoPub Ad Server will in-turn notify the publisher’s callback endpoint. The publisher’s reward server will then provide the reward to the user.

server-side-rewarding-flow-3

Setting a rewarded video callback URL in the MoPub UI

IMPORTANT: After updating an ad unit to use server-side rewarding, MoPub will no longer provide a client-side reward callback in the SDK. If you have older versions of your app that use client-side rewarding, please create a new ad unit for server-side rewarding.

To use server-side rewards, create a new rewarded video ad unit and add a callback URL to the “Server-side Callback URL” form (highlighted in the screenshot below).

server-side-rewarding-ad-unit-form

Alternatively, a callback URL can be added to an existing ad unit that is not yet live with client-side rewarding.

Available callback macros:

Callback macros will dynamically populate with data necessary to reward the user. For the most secure results, it is highly recommended that a publisher use the %%CUSTOMER_ID%%, %%ID%% and %%VERIFIER%% macros at a minimum.

Macro
FormatDescription
%%AD_REVENUE%% double Net revenue received by publisher for serving the ad
%%ADUNITID%% string Ad Unit ID
%%ADVERTISING_ID%% string Advertising ID (IDFA/GAID) for the user’s device
%%CURRENCY_TYPE%% string Currency type selected in the ad unit page in the reward section
%%CURRENCY_VALUE%% integer Currency value entered in the ad unit page in the reward section
%%CUSTOMER_ID%% string Customer or User ID supplied in the ad request
%%ID%% string MoPub’s unique transaction ID
%%PLACEMENTID%% string App ID
%%TIMESTAMP%% long Time at which the reward was recorded on the MoPub server
%%VERIFIER%% string Security token to verify the request came from MoPub
%%CUSTOM_DATA%% string Custom data string passed via the MoPub SDK. This can be a base64 encoded JSON object with application state
%%CUSTOM_EVENT_CLASS_NAME%% string Custom Event Class name that uniquely identifies the demand source that provided the ad.

An example server-side callback URL with macros:

http://api.example.com/callback.php?customer_id=%%CUSTOMER_ID%%&id=%%ID%%&hash=%%VERIFIER%%&value=%%CURRENCY_VALUE%%&type=%%CURRENCY_TYPE%%

The URL callback after being populated with data from the MoPub Ad Server:

http://api.example.com/callback.php?customer_id=3453523454&id=70bae1905f7844a3a012a5f4173021db&hash=28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10&value=20&type=Coins

Configuring the Callback Server

The callback server must return a 200 HTTP response status code when it successfully applies the reward.

If the callback server returns a 500 HTTP response status code, MoPub will continually call the server at increasing intervals until the server returns a 200 HTTP code or the maximum retry limit of 14 is reached. The maximum retry limit is 2 hours. MoPub will stop the retries if the server returns a 200 HTTP response status code.

HTTP Response CodeDescriptionWhen to Use
200 Successful Request Return this response code when for a successful callback to the publisher server
500 Internal Server Error Return this response code when a publisher server error occurs

If any other HTTP response status code is used, MoPub will log the response and not attempt to retry.

To ensure that the reward server receives a callback, the MoPub server may retry if it detects a failure to connect. Because of this, there is a small possibility that the publisher server might receive a callback from the same callback URL twice for the same rewarded video. MoPub recommends that the publisher stores the hash ID (the value from the %%VERIFIER%% macro) and make sure the publisher only give a customer one reward for each unique ID.

How to verify the %%VERIFIER%% Hash

To secure the callback ping to the publisher reward server, the %%VERIFIER%% macro must be present in the callback URL.

The %%VERIFIER%% is a SHA256 hash generated from the callback’s parameter values and uses a Secret Key as a salt.

The Callback Secret Key can found in the MoPub UI Account Settings page.

server-side-rewarding-secret-key-1

On the publisher’s reward server, the Callback Secret Key is used to regenerate the SHA256 hash from the callback’s received parameter values. If the hash generated on the publisher server matches the one received from the MoPub Ad Server, the publisher can verify the reward callback has been received from MoPub’s Ad Server and can proceed with rewarding the user.

How to generate the hash on the reward server:

  1. Parse the callback url and retrieve the query parameters
  2. Drop the verifier key and value from the array of parameters
  3. Sort the query parameters alphabetically
  4. Concatenate the values in that alphabetical order
  5. Hash the concatenated string using a HMAC SHA256 hash algorithm and the Callback Secret Key

Example:

  1. Callback URL: http://api.example.com/callback.php?customer_id=3453523454&id=70bae1905f7844a3a012a5f4173021db&hash=28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10&value=20&type=Coins
  2. Verifier Hash: hash=28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10
  3. Alphabetical array of query parameters (excluding the verifier)
    • customer_id=3453523454
    • id=70bae1905f7844a3a012a5f4173021db
    • type=Coins
    • value=20
  4. Concatenated String: 345352345470bae1905f7844a3a012a5f4173021dbCoins20
  5. HMAC SHA256 the concatenated string and the Secret Key: 7dbcfd2a42134f47bfb72daa02f85ec9
    • The result: 28f3b28b09b2578db06ee371990b5a02882523eba954d5a1b57afe2c7e7d3f10
    • The result matches the hash passed in the request

After generating the hash, compare the received hash with the generated hash. They should equal each other.

Once verified, the publisher server must return a 200 response code to MoPub and proceed with rewarding the user.

Updated: October 2017