Contact usContact us

Server-to-Server Callback Settings

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.

Note: You can also use client-side events to grant rewards to users after successful ad completion events.

⚡ Before you start

Make sure you have implemented the server-to-server callback handlers in your code, as described here.

You can receive ad completion notifications via server-to-server callbacks. This is the recommended process if you are managing your application data via 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 on the ironSource Platform

  • Log in to your Unity LevelPlat account and navigate to the Apps section in the left sidebar.
  •  From the list of apps, click the action button of the app that you want to enable server-to-server callback for and select Set S2S callback.

  • On the Create S2S reward callback page fill in the necessary information to enable server-to-toserver callbacks.
    • 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]

See the section below for which parameters are mandatory for server-to-server callbacks.

  • Next, add the private key (optional). A private key is a string that is only known by you and LevelPlay, which adds an extra layer of protection.5. In the parameters section, click on the dropdown menu and select the optional parameters you want to include in the callback. Once you select the optional parameter, they will automatically appear in the callback URL. 
  • In the Callback test section, enter the User ID and the Reward amount to test the callback. You also have the option to enter the optional fields (Auction ID, Ad network, App key, Item name and Placement name) but are not required to test the callback. 


Note: In order to activate S2S callbacks, your server must receive the callback and acknowledge receipt.

  • Click Save and your callback will instantly be activated. You can confirm the status of the callback on the Apps page. We recommend testing the callback before saving. 

Mandatory Parameters

Mandatory parameters that must be included in your callback string:

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

Optional Parameters

Optional parameters that may be used if needed, for your own internal use:

  1. [AUCTION_ID] – Unique identifier for the auction.
  2. [AD_NETWORK] – specifies the provider’s name (e.g Vungle).
  3. [APP_KEY] – App Key as you see on LevelPlay pages.
  4. [ITEM_NAME] – Virtual item name, in the case the reward is a virtual item rather than an in-game currency.
  5. [PLACEMENT_NAME] – Placement name.

Note: You may also use custom parameters. You don’t need to add a placeholder for these; they will simply appear in your callback URL with the prefix custom_.
 

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 by you and ironSource, while all other signature components are part of the URL.  The private key is thus added for additional security as it makes the signature harder to reproduce. If you’d like to use this extra layer of security, enter a private key to be sent along with the callback URL.

Important!
  • Whenever a commission event is generated, the ironSource server will call your callback URL and provide you with the necessary information in order to credit the relevant user. We will keep calling this URL periodically for every commission until we receive a valid HTTP response with status 200 (OK) with the appearance of “[EVENT_ID]:OK” string somewhere in the HTTP response.
    This is an example of a typical response: <status> dae8e6cf42b1357f8652ad6ecb5b24f1:OK</status>
  • ironSource manages a policy of retries and timeouts so that a temporary failure of communication does not result in lost commission events. The response has to be sent within 400 milliseconds, otherwise, there will be a timeout on the callback which initials the retry mechanism. This 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.