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.

  • 3. On the Create S2S reward callback page fill in the necessary information to enable server-to-toserver callbacks.

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

  • 4. 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. 


  • 6. 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 (Application ID, Ad provider, 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. [ITEM_NAME] – Virtual item name, in the case the reward is a virtual item rather than an in-game currency.
  2. [APPLICATION_KEY] – ApplicationKey.
  3. [PLACEMENT_NAME] – Placement name.
  4. [AD_PROVIDER] – Relevant for Mediation integrations, and specifies the provider’s name (e.g Vungle).
  5. [DELIVERY_TYPE] – This parameter specifies the ad unit from which the completion was reported. Possible values are Offerwall or Rewarded Video.
  6. [MULTI_CREDIT_PROMO_MULTIPLIER] – For Offerwall only, this parameter specifies if this offer was delivered during a “multi credit promotion” and what the promotion value was. In the case of a 2X promotion, this parameter will return “2”. In the case of a 2.5X promotion, this parameter will return “2.5”. In the case where there was no promotion active, this parameter will return “1”.

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. If your expected acknowledgement response is not sent, ironSource continues to call the commission event callback with the same details, for up to 48 hours. A response time of more than 1 second is also considered a failure. Unverified or failed callbacks will not be compensated by ironSource.