Server-to-Server Callback Settings

ironSource 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

  1. Log in to your ironSource account and navigate to the Monetize section in the left sidebar. Go to Settings   Ad Units.
    ironsource-platform-s2s-callbacks
  2.  Select your app and then click on the ad unit tab to enable S2S callbacks for the relevant ad unit:
    ironsource-platform-s2s-app-ad-unit
  3. Go to the Callbacks section and click on ‘Define Server to Server Callbacks‘:
    ironsource-platform-s2s-setup
  4. The below window will open and you must fill in the necessary information to enable S2S callbacks.
    1. In the Callback URL field, construct the callback for ironSource to send you after a user performs an ad unit completion, for example:
      http://www.mysite.com/granting.php?appUserId=[USER_ID]&rewards=[REWARDS]&eventId=[EVENT_ID]&itemName=[ITEM_NAME]
      Note: The values in brackets are placeholders that are replaced by actual values when ironSource sends you the callback.
      Make sure you fill in all the mandatory parameters in your callback as well as any additional optional parameters we support.
    2. Verify that the callbacks get sent correctly by entering the correct values in the Callback Test Parameters fields. Select ‘Test and Save‘.
      ironsource-platform-s2s-information
    3. If you’d like to enable negative callbacks in the case a transaction is ultimately denied by the advertiser and you want the option to revoke the reward from your user, simply select ‘+ Add a negative callback‘. Then construct the URL to which ironSource can send you the revoke notification, following this example:
      http://www.mydomain.com/revoke.php?appUserId=[USER_ID]&rewards=[REWARDS]&eventId=[EVENT_ID]
  5. The below toggle will then appear in the Callbacks section. You will be able to activate it by swiping right once the ironSource sends the test callback to your server, and is successful. If you have added a negative callback, ironSource will send you a callback for that as well.
    ironsource-platform-s2s-callbacks-toggle
    Note: In order to activate S2S callbacks, your server must receive the callback and acknowledge receipt.

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: In addition, you may also use custom parametersYou don’t need to add a placeholder for these, they will simply appear in your callback URL with the prefix custom_.

Optional – 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.

Done!
You are now ready to start using server-to-server callbacks.