Offerwall Integration for Android

Get up and running with the Offerwall Ad Unit in 4 easy steps:

  1. Implement the Offerwall Listener
  2. Initialize the Offerwall Unit
  3. Present the Offerwall
  4. Reward the User
Before You Start

Make sure that you have correctly integrated the ironSource SDK into your application. Integration is outlined here.

Step 1. Implement the Offerwall Listener

The ironSource SDK fires several events to inform you of ad availability. By implementing theOfferwallListener you will receive Offerwall events.

The SDK will notify your listener of all possible events listed below:

//Import the Offerwall Listener
import com.supersonic.mediationsdk.sdk.OfferwallListener;
OfferwallListener mOfferwallListener = new OfferwallListener()
{
/**
 * Invoked when the Offerwall is prepared and ready to be shown to the user
 */ 
public void onOfferwallInitSuccess(){}
/**
 * Invoked when the Offerwall does not load
 */ 
public void onOfferwallInitFail(SupersonicError error){}
/**
 * Invoked when the Offerwall successfully loads for the user, after calling the 'showOfferwall' method
 */ 
public void onOfferwallOpened(){}
/**
 * Invoked when the method 'showOfferWall' is called and the OfferWall fails to load.  //@param supersonicError - A SupersonicError Object which represents the reason of 'showOfferwall' failure.
 */
public void onOfferwallShowFail(SupersonicError supersonicError){}
/**
  * Invoked each time the user completes an Offer.
  * Award the user with the credit amount corresponding to the value of the ‘credits’ 
  * parameter.
  * @param credits - The number of credits the user has earned.
  * @param totalCredits - The total number of credits ever earned by the user.
  * @param totalCreditsFlag - In some cases, we won’t be able to provide the exact 
  * amount of credits since the last event (specifically if the user clears 
  * the app’s data). In this case the ‘credits’ will be equal to the ‘totalCredits’, 
  * and this flag will be ‘true’.
  * @return boolean - true if you received the callback and rewarded the user, 
  * otherwise false.   
  */
public boolean onOfferwallAdCredited(int credits, int totalCredits, boolean totalCreditsFlag){}
/**
  * Invoked when the method 'getOfferWallCredits' fails to retrieve 
  * the user's credit balance info.
  * @param supersonicError - A SupersonicError object which represents the reason of 'getOffereallCredits' failure. 
  * If using client-side callbacks to reward users, it is mandatory to return true on this event
  */
public void onGetOfferwallCreditsFail(SupersonicError supersonicError){}
/**
  * Invoked when the user is about to return to the application after closing 
  * the Offerwall.
  */
public void onOfferwallClosed(){}
}
Note:
Please do not assume the callbacks are always running on the main thread. Any UI interaction or updates resulting from Supersonic callbacks need to be passed to the main thread before execution.

Step 2. Initialize the Offerwall Unit

Once the Offerwall Ad Unit is initialized, you will able to call functions on it. We recommend initializing the Offerwall on application launch.

public class YourActivity extends Activity {
  //Declare the Supersonic Mediation Agent
  private Supersonic mMediationAgent;
  
  public void onCreate(Bundle savedInstanceState) {
  
  super.onCreate(savedInstanceState);
  
  //Get the mediation publisher instance 
  mMediationAgent = SupersonicFactory.getInstance();
  
  //Set the Offerwall Listener
  mMediationAgent.setOfferwallListener(mOfferwallListener);
  
  //Set the unique id of your end user.
  String mUserId = "APPLICATION_USER_ID_HERE"; 
  //Set the Application Key - can be retrieved from Supersonic platform
  String mAppKey = "APPLICATION_APP_KEY_HERE";
  
  //You can set Optional Custom parameters which will be passed to
  your server if you use server-to-server callbacks.
  Map<String, String> owParams = new HashMap<String, String>();
  owParams.put("userType","gamer");
  SupersonicConfig.getConfigObj().setOfferwallCustomParams(owParams);
  
  //You can set optional parameters as well via the .getConfigObj
  SupersonicConfig.getConfigObj().setClientSideCallbacks(true);
  
  //Init Offerwall
  mMediationAgent.initOfferwall(this, mAppKey, mUserId);
  }
}
Note:

  1. “this” is the activity in which the Ad Unit should be presented.
  2. mAppKey is the unique ID of your Application in your ironSource account.
    ironsource-platform-app-key
  3. mUserId is the unique ID of your end user. We support NSString from 1 to 64 characters. Common practice is to use the Google Advertising ID (GAID). More information on User IDs can be found here.

Step 3. Present the Offerwall

After you receive the onOfferwallInitSuccess callback, you are ready to show the Offerwall to your users. When you want to show the Offerwall (typically done after a user clicks on some in-app button), you do so by calling the showOfferwall method on mMediationAgent:

//show offerwall when user clicks the offerwall button 
mMediationAgent.showOfferwall();

New! Placements for Offerwall

With ironSource’s Ad Placements, you can customize and optimize the Offerwall experience. This tool enables you to present the Offerwall to your users in various places, i.e. in your in-app store, between levels, in the main menu,  etc. You can use the below function to define the exact Placement to show the Offerwall. Navigate to the Ad Placement document for more details.

mMediationAgent.showOfferwall(placementName);

Step 4. Reward the User

Supersonic supports two methods to reward your users. Select one of the following:

  1. Server-Side Callbacks
  2. Client-Side Callbacks
Method 1: Server-Side Callbacks

The default setting in your ironSource account notifies you of user’s completions or rewards via the supersonicDidReceiveCredit callback within the client of your app. Alternatively, you can turn on server-to-server callbacks to receive notifications to your back-end server. Once you select server-to-server callbacks you will not receive client-side notifications.

We recommend turning on server-to-server callbacks for Offerwall instead of client-side callbacks, as the authenticity of the callback can be verified. With server-to-server callbacks, you will have better control over the rewarding process as the user navigates out of your app to complete the offer.

Note:

  • If you turn on server-to-server callbacks , remember not to reward the user more than once for the same completion.
  • We will fire a server-to-server callback to the selected location with an Event ID which is the unique identifier of the transaction. For us to know you’ve granted the user, you must respond to the callback with [EVENT_ID]:OK anywhere within the HTTP payload of the callback.
  • To utilize server-to-server callbacks, see here.

Method 2: Client-Side Callbacks

  • Proactive Polling API

You may call the function getOWCredits at any point during the user’s engagement with the app. You will then receive information on the user’s total credits and any new credits the user has earned.
See Step 1 for instructions on how to implement the protocol and receive callbacks for the following method:

mMediationAgent.getOfferwallCredits();
  • Automatic Client-Side Events

You can receive client-side events automatically within your application by registering to the Offerwall listener and setting the use of client-side callbacks. Setting automatic client-side callbacks will make sure that you’re notified about the user’s credit status at specific points in the Offerwall’s lifecycle. To do so:

Important! This code MUST be implemented before calling the initOWWithAppKey.

SupersonicConfig.getConfigObj().setClientSideCallbacks(true);

Note:
If you are using automatic client-side events, we recommend adding the proactive polling method and checking the user’s reward status on app launch, upon in-app store entry and in the case a user opened the Offerwall, ardently verifying every 5 minutes after the user closes the Offerwall to ensure you don’t miss the latest update on the user’s rewards.

First Time Integration Tip

If this is a new integration for your application, your app will by default be in ‘Test Mode‘ on your ironSource dashboard. While your app is in Test Mode, the ironSource SDK will print more logs to the console in order to provide greater visibility into the SDK processes. To test your ad inventory, set up your Test Devices. Until you turn on live ad inventory, you will receive test campaigns that don’t generate revenue. Make sure to select Go Live! on the Ad Units page when your app is ready for live ad inventory.

ironsource-go-live-with-rewarded-video

Done!
You are now all set to deliver ironSource’s Offerwall in your application.


What’s Next?
Follow our integration guides to integrate additional Ad Units: