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. 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. 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. Your application must acknowledge receiving the commission event by sending an HTTP response with a status of 200 (OK), where the
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). Commission Event Callback
Description
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.
[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
“[EVENT_ID]:OK”
<xml> <status>dae8e6cf42b1357f8652ad6ecb5b24f1:OK</status> </xml>
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 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 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.Sample Commission Event Callback Code – PHP
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
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
To authenticate the commission event callback you can:
md5([TIMESTAMP][EVENT_ID][USER_ID] [REWARDS][PRIVATE_KEY]), and verify that the result is identical to the signature parameter value.