Server-to-server callback settings

Set up server-to-server callbacks in your app to receive notifications upon ad completion, allowing you to grant rewards to users through your backend server.

Read time 5 minutes

LevelPlay reward-based ad units support server-side events to notify you of rewards that must be granted to your users after successful ad completion events.

Prerequisites
Prerequisites

Ensure that you have implemented the server-to-server callback handlers in your code.

You can receive ad completion notifications by using server-to-server callbacks. This is the recommended process if you are managing your application data by using a back-end server. We will send a callback after each ad completion to notify your server of the reward type & amount you must grant your end user.

Enable server-to-server callbacks
Enable server-to-server callbacks

  1. Sign in to your Unity LevelPlay account.
  2. In the left navigation menu, go to the Apps section.
  3. From the list of apps, select the action button next to the app that you want to enable server-to-server callback for and then select Set S2S callback.
  4. On the Create S2S reward callback page, enter the required information to enable server-to-toserver callbacks.
  5. In the Callback URL field, construct the callback for LevelPlay to send you after a user performs an ad unit completion. For example: http://www.mysite.com/granting.php?userid=\[USER\_ID\]&rewards=\[REWARDS\]&eventId=\[EVENT\_ID\]
  6. Optional: Add the private key. A private key is a string that is only known to you and LevelPlay, which adds an extra layer of protection.
  7. In the parameters section, select the dropdown menu and then select the optional parameters to include in the callback. After you select the optional parameter, they will automatically appear in the callback URL.
  8. In the Callback test section, enter the User ID and the Reward amount to test the callback. You can also complete the optional fields (Auction ID, Ad network, App key, Item name and Placement name), but they are not required to test the callback.
  9. Select Save.

Your callback will instantly be activated. You can confirm the status of the callback on the Apps page.

Mandatory parameters
Mandatory parameters

The following list details mandatory parameters that must be included in your callback string:

  • [USER_ID]: The unique identifier of a user of your application. The system uses this to know which user to reward upon successful ad completion.
  • [REWARDS]: The number of credit units rewarded to the user.
  • [EVENT_ID]: A unique identifier of the completed event, generated by ironSource, so you can verify that you have not already rewarded the user for the event.

Optional Parameters
Optional Parameters

The following list details optional parameters that you can use internally as needed:

  • [AUCTION_ID]: Unique identifier for the auction.
  • [AD_NETWORK]: Specifies the provider’s name (for example: Vungle).
  • [APP_KEY]: App Key as you see on LevelPlay pages.
  • [ITEM_NAME]: Virtual item name, in case the reward is a virtual item rather than an in-game currency.
  • [PLACEMENT_NAME]: Placement name.

Signature validation with private key
Signature validation with private key

Your signature represents a MD5 of the following:

md5(\[TIMESTAMP\]\[EVENTID\]\[USER\_ID\]\[REWARDS\]\[PRIVATE\_KEY\]).

The private key is a string known only to you and ironSource, while all other signature components are part of the URL. The private key is added for additional security because it makes the signature harder to reproduce.

  • Whenever a commission event is generated, the ironSource server will call your callback URL and provide you with the necessary information to credit the relevant user.
    • The system will keep calling this URL periodically for every commission until it receives a valid HTTP response with status 200 (OK) with the appearance of “[EVENT_ID]:OK” string somewhere in the HTTP response.
    • The following is an example of a typical response: dae8e6cf42b1357f8652ad6ecb5b24f1:OK
  • ironSource manages a policy of retries and timeouts so that a temporary failure of communication does not result in lost commission events.
    • The response must be sent within 400 milliseconds, otherwise, there will be a timeout on the callback which initials the retry mechanism.
    • A timeout will be shown on the "slow callbacks Queue", where every callback can be responded to within 20 seconds.
    • There will be 20 retires sent in the 24 hours after the original callback, and then 1 retry a day for the next 7 days.