Handling Server-to-Server Callback Events

Commission Event Description

A commission event occurs once a user has completed an ad offer. In the case of Rewarded Video and Offerwall, this means that the user should be rewarded with virtual currency or items. ironSource calls the commission event callback (as defined in the Callback URL parameter in the application settings) with details about the reward.

Note: In the case of Rewarded Video and Offerwall, you must implement the commission event callback so that your code awards the correct amount to the correct user. In the case of Interstitial, the event only informs you that the user has completed an offer (no reward is involved).

The following sections describe the syntax of the commission event callback, provide a code sample, and describe how to authenticate, manage and test the event callback.

Note: In the case of the RewardedVideo product, a client-side event is also sent when a user completes an ad offer (sees a RewardedVideoDidReceiveCredit for iOS or onRVAdCredited for Android), in addition to the server-side commission event callback being called. In the case of OfferWall, the client-side event ssaOfferWallDidReceiveCredit (for iOS) or onOWAdCredited (for Android) is called.
We recommend using the server-side event to trigger the user reward, as the authenticity of the callback can be verified (see Authenticating the Commission Event Callback). Make sure not to reward the user twice for the same event when handling the ssaRewardedVideoDidReceiveCredit (iOS) oronRVAdCredited(Android).
If you do not operate a back-end data server for your application and wish to rely solely on client-side events, you can disable the server-to-server callback system.

Commission Event Callback

Description

The commission event callback is called when a user has completed an ad offer and should be rewarded with credit or virtual items. You are responsible for implementing the code to handle this event.

Parameters

Name Type Description
[USER_ID] String The unique identifier of the user to be rewarded. This is sent by the calling app when initializing the ironSource product.
Note: Note: The URL-encoded form is passed (for example, “123%40abc.com” rather than “123@abc.com”).
[REWARDS] Int The number of credit units to be awarded to the user.
[EVENT_ID] String A unique identifier of the callback event, generated by ironSource server, and composed of alphanumeric characters
[ITEM_NAME] String The name of the virtual item to be awarded (if the virtual item option is used).
Timestamp String A string representation of the exact date and time at which this callback was called, in the following format: YYYYMMDDHHMM (e.g. “201001021455” stands for January 2, 2010 14:55).
signature String An MD5 hash string to be used for authentication (see Authenticating the Commission Event Callback). This key is generated based on the following formula: md5([TIMESTAMP][EVENT_ID][USER_ID]
[REWARDS][PRIVATE_KEY]).
The [USER_ID] element is the URL-decoded value of the userID (for example, “123@abc.com” rather than “123%40abc.com”).
The [PRIVATE_KEY] element is the value you defined in the Private Key setting.

Response

Your application must acknowledge receiving the commission event by sending an HTTP response with a status of 200 (OK), where the “[EVENT_ID]:OK”string appears anywhere in the response.

<xml>
<status>dae8e6cf42b1357f8652ad6ecb5b24f1:OK</status>
</xml>

Note: It is important to send a response with the correct syntax, so that ironSource does not continue to send retries of the callback.

Sample Commission Event Callback Code – PHP

The following PHP code sample demonstrates a typical commission event callback handler. All you need to do after copying the code is to implement the alreadyProcessed()anddoProcessEvent() functions and set the  [YOUR_PRIVATE_KEY]   string to the correct value.

// get the variables
$userId = $_GET['applicationUserId'];
$eventId = $_GET['eventId'];
$rewards = $_GET['rewards'];
$signature = $_GET['signature'];
$timestamp = $_GET['timestamp'];
$privateKey = ‘[YOUR_PRIVATE_KEY]’;
// validate the call using the signature
if (md5($timestamp.$eventId.$userId.$rewards.$privateKey) != $signature)
{
   echo "Signature doesn’t match parameters";
   return;
}
// check that we haven't processed the same event before
if (!alreadyProcessed($eventId)){
   // grant the rewards
   doProcessEvent($eventId, $userId, $rewards);
}
// return ok
echo $eventId.":OK";

Sample Commission Event Callback Code – Java

The following Java code sample demonstrates a typical commission event callback handler. All you need to do after copying the code is to implement the getPostParameter() andalreadyProcessed()  methods and set the  [myPrivateKey] string to the correct value.

import java.security.*;
import java.math.BigInteger;
public class HelloWorld {
     public static void main(String []args) {
        
        validateSuperSonicCallback();
     }
     
    public static String getPostParameter(String param){
         // TODO : your app implementaion for get post parmas
        return "";
     }
	 
	  public static boolean alreadyProcessed(String eventId){
         // TODO 
        return true;
     }
     public static boolean validateSuperSonicCallback() {
         
         String applicationUserId = getPostParameter("applicationUserId");
         String eventId = getPostParameter("eventId");
         String signature = getPostParameter("signature");
         String userId = getPostParameter("userId");
         String rewards = getPostParameter("rewards");
         String timestamp = getPostParameter("timestamp");
         String privateKey = "myPrivateKey" ;// enter your private key
         String mySignature = "";
        try {
            String message = timestamp + eventId + userId + rewards +privateKey;
            MessageDigest md = MessageDigest.getInstance("MD5"); 
            md.update(message.getBytes());
            BigInteger hash = new BigInteger(1, md.digest());
            String result = hash.toString(16);
            while(result.length() < 32) {
                result = "0" + result;
            }
                        System.out.println(result); // Display the string.
        } catch (NoSuchAlgorithmException e){
        }
        if (mySignature!=signature){
	     return false;
	}else{
	     return !alreadyProcessed(eventId);
    }
     
  }
}

Authenticating The Commission Event Callback

In order to protect your code from unauthorized access, we recommend performing some simple tests on the commission event callback signature and source, to verify that the call was made by ironSource.
To authenticate the commission event callback you can:

  1. Generate the MD5 hash value from the call’s parameters, according to this formula: md5([TIMESTAMP][EVENT_ID][USER_ID] [REWARDS][PRIVATE_KEY]), and verify that the result is identical to the signature parameter value.
  2. Verify that the call originates from one of these IP addresses:
    1. 79.125.5.179
    2. 79.125.26.193
    3. 79.125.117.130
    4. 176.34.224.39
    5. 176.34.224.41
    6. 176.34.224.49
    7. 34.194.180.125
    8. 34.196.56.165
    9. 34.196.251.81
    10. 34.196.253.23
    11. 54.88.253.218
    12. 54.209.185.78