Native API Integrations

ironSource offers the ability to utilize our Offerwall product through ‘Native’ implementations within your app!

Product Overview

This API provides access to the raw building blocks of the Offerwall to make custom constructions in your application, instead of using our finished, out-of-the-box product with its predefined ad format. This creates a unique ad experience that complements the graphics in your app.

We recommend using the Native API in the following circumstances:

  1. Custom Offerwall UI
    Ability to control a variety of colors, fonts and background of the Offerwall.
  2. Special ad appearance and design
    For example, an “App of the day” ad, presented with the app’s original look and feel will enhance user targeting and increase user engagement.
  3. Mobile web integrations
    Your app runs on mobile and thus cannot integrate the ironSource SDK.

Overview of the API Cycle

  1. Access the API to retrieve the available campaigns to serve to your users.
  2. Parse the returned data object to retrieve the data you need to construct a unique ad experience.
  3. Create the ad experience for your users by utilizing the retrieved data points.
  4. After your users complete the offer, process the completion to grant them a reward. To learn about reward notifications, read our Server-to-Server Callbacks article.

Supersonic Native API Monetization Cycle

Calling the API

To access ironSource Mobile offers, call the mobilePanel.php API. Below is the API end-point to call in its standard format:[USER_ID]&applicationKey=[APP_KEY]&deviceOs=[DEVICE_OS]&deviceIds[TYPE]=[DEVICE_ID]&isLimitAdTrackingEnabled=[true/false]&deviceOSVersion=[osVersion]
Note: Note: The Offerwall will only receive ads in the API response once it has been set to live in the ironSource platform.

The table below lists the mandatory parameters which must be passed as part of the API request.

Mandatory Parameters

Name Description Examples / Notes
applicationKey Your applications unique key from your ironSource Admin applicationKey=31kj3hkj
applicationUserId Your end-users unique identifier
[USER_ID] must be URL-encoded (for example, “” rather than “”).
format The data format of the API’s response
Our default returned format is HTML. You can add “&format=xml” or “&format=json” in order to achieve the result in XML or JSON format. To allow this usage, you should contact your Account Manager. Without the format parameter (or with&format=html value) the response will result with ironSource default HTML and CSS.
nativeAd=1 Marker to specify Native Ad Implementations
This identified returns or newer formatted response with better data values to use in your implementation. Make sure with your Account Manager that usage of xml/json is allowed, as noted in the ‘format’ parameter above.
deviceOs=[DEVICE_OS] The OS of the users Device
[DEVICE_OS] should be either “ios” or “android”
The Type of deviceID being passed from the users phone
[TYPE] should be either IFA for iOS or AID for Android.
Example – iOS: &deviceIds[IFA]=AAA-BBB-111-222-CCC
Example – Android: &deviceIds[AID]=DDD-EEE-111-222-CCC
[DEVICE_ID] The actual ID of the deviceID
[DEVICE_ID] – The device ID value. Apple support IFA while Android support AID. The IFA should be taken from ASIdentifierManager class, the AID should be taken from the AdvertisingIdClient.Info class.
The user’s ad tracking limitation state
isLimitAdTrackingEnabled=[true/false] – the limit ad tracking state should be taken from Google API AdvertisingIdClient.Info class for Android devices or ASIdentifierManager class for iOS devices.
The operating system version of the device
The OS Version should be the API version for Android, and the string version for iOS.
Example – Android: deviceOSVersion=22
Example – iOS: deviceOSVersion = 9.2
deviceModel The model of the users device deviceModel=GT-S5360

Optional Parameters

The table below lists the optional parameters which can be passed as part of the API request.

Name Description Examples \ Notes
pageSize Number of offers to serve on a single page
Example: pageSize=1 – Recommended to use with the ‘Deal of the Day’ integration
page Used to create pagination – which requires a special UI – “Next Page” page=3
The date whenthe user has created his/her account. Important for ironSource Fraud Control
Must be in the yyyy-mm-dd format.
Should be used in addition toapplicationUserCreationDateSignature
application UserCreationDateSignature
The md5 hashing of the following strings: [applicationUserId][applicationUserCreationDate][applicationPrivateKey]
Must be used with the ‘applicationUserCreationDate’
Used with applicationUserCreationDate
scope Used to present a customer support page “Missing currency” instead of Offer Wall scope=999
currencyName Specifies an alternative currency name (possibly other than what has been predefined) currencyName=Gems
language Force specific language for the static texts
Pass the standard 2 characters ISO code for languages. Please note that the offers themselves may still be presented in the relevant language for the target country.
ip Control the country (user will see offers bases on the ip address). Valid for server API integrations only.
*Contact your Account Manager if you plan to use this parameter*
Requires the use of an accessKey and secretKey parameters (their values can be found in the Setup | API form).
mobileCarrier The service carrier of the users device mobileCarrier=Vodafone
deviceOEM The manufacturer of the users device deviceOEM=samsung
location The location of the users device
the user’s location according to the device’s GPS, using the format latitude,longitude.location=8.620794,52.3724269
suppressStatistics Suppress any statistic counting for this impression
suppressStatistics=1This option can be used if you wish to test your production app/site without having any influence on the aggregated statistics
applicationUserGender Used to improve targeting applicationUserGender=male
Possible values: male; female
Default: unknown
applicationUserBirthday Used to improve targeting
Used to improve Targeting
0: Unknown
1: 13-17
2: 18-20
3: 21-24
4: 25-34
5: 35-44
6: 45-54
7: 55-64
8: 65+
Custom Parameters Used for internal segmentation
Example: Custom_Gender=Female

Parsing the Response

Once you call the API, the server will respond with all available campaigns according to the request format. For example a JSON / XML response will be as follows:


Supersonic Native API Monetization Parse response with JSON


Supersonic Native API Monetization Parse response with XML

At this stage, parse out the necessary data from the response to use in your ad unit.

We recommend utilizing the following data points to construct the ad unit:

  • Offer Name
  • Credit Amount
  • ClickURL
  • Offer Icon

The entire response includes:

Key name Description
offerId The ID of the delivered campaign
bundleId * For App-Install offers* The unique identifier of the app in the store
rewards The reward that the user will receive upon completing the offer
rewardsText The text that will state the name of the reward (Gems, etc.)
userFlow The type of the offer: Install, Sign-in etc.
callToAction The action required from the user to get rewarded
title The name of the application
creatives > creativeId Identification of the campaigns’ specific entity in SSA server (bannerID, it differs from offerID)
creatives > url The dynamic URL that redirects the user to the app
creatives > image An icon of the promoted app (114×114 or 125×125)

Custom Offerwall Example

Here is an example of a publisher who created their own Offerwall utilizing the Native API and designed their own implementation native to the look and feel of their application:

Supersonic Native API Monetization Example

‘Deal of the Day’ Example

The most highly recommended implementation of the Native API is the ‘Deal of the Day’ Ad Unit. This unit is highly effective in converting users and driving significant daily revenue. This entails promoting a single offer each day to the user in unique placements within the application. The user is highly incentivized to complete the daily special offer to take advantage of a time-sensitive opportunity. Creating this type of implementation is easy with the Native API.

To begin:

  1. Call the Native API adding in the optional ‘pageSize=1‘ parameter to the request. This will ensure you get only the top offers available returned in the response.
  2. See the below code example for how to implement this into a Native iOS/Android application.

Best practices for using the ‘Deal of the Day’ Ad Unit include utilizing the following returned keys:

Key Name Description
rewards The reward that the user will receive upon completing the offer
creative / title The name of the offer
creative / url The dynamic URL that redirects the user to the offers landing page
creative / image / url An icon of the promoted offer (114×114 or 125×125)

Code Example

public class Supersonic {
    public static class Image {
        int width;
        int height;
        String url;
    public static class Creative {
        String creativeId;
        String title;
        String description;
        String url;
        Image image;
    public static class Offer {
        int offerId;
        String bundleId;
        int rewards;
        String rewardsText;
        String disclaimer;
        Creative[] creatives;
    public static class Response {
        InnerResponse response;
    public static class InnerResponse {
        int errorCode;
        String errorMessage;
        int items;
        int total;
        Offer[] offers;
    private String buildRequestWithParamters(Context context, String applicationKey,
                                          String applicationUserId, Location location, Map<String, String> extraParameters) {
        DeviceProperties deviceProperties = DeviceProperties.getInstance(context);
        // builds the query:
        StringBuilder requestParameters = new StringBuilder();
        if (applicationUserId != null && applicationUserId.length() > 0) {
        if (applicationKey != null && applicationKey.length() > 0) {
        for (String deviceIdType : deviceProperties.getDeviceIds().keySet()) {
        // optional:
        if (deviceProperties.getDeviceCarrier() != null && deviceProperties.getDeviceCarrier().length() > 0) {
        if (location != null) {
        if (extraParameters != null && extraParameters.size() > 0) {
            for (Map.Entry<String, String> entry : extraParameters.entrySet()) {
        return requestParameters.toString().replace(" ", "%20");
    public String buildUrl(Context context, String userId, String referrer) {
        Location l = LocationUpdater.getInstance().getCurrentLocation();
        HashMap<String, String> params = new HashMap<>();
        params.put("format", "json");
        params.put("currencyName", context.getString(R.string.earn_vip_hours));
        params.put("language", Locale.getDefault().getLanguage());
        if (referrer != null) {
            params.put("custom_referrer", referrer);
        return "" + buildRequestWithParamters(context, "3906547d", userId, l, params);
    public interface AotdLoadedListener {
        public void onAotdLoaded(Offer offer);
    public void loadAppOfTheDay(final Context context, final AotdLoadedListener listener, final String referrer) {
        Me.get(new Me.MeLoadedListener() {
            public void onMeLoaded(User me) {
                String url = buildUrl(context, me.getId() + "", referrer);
                JQuery.i("AOTD: Load from " + url);
                JQuery aq = new JQuery(context);
                aq.ajax(url, String.class, new Network.GsonCallback(Response.class) {
                    public void onSuccess(Response result) {
                        if (result.response.errorCode == 0 && result.response.offers.length > 0) {
                    protected void onCheckFailed(String url, String response, AjaxStatus status) {
                        super.onCheckFailed(url, response, status);
                        JQuery.i("AOTD: Failed to load " + status.getError());
                    protected void onRequestFinished() {
    public interface AotdViewLoadedListener {
        public void onAotdViewLoaded(View view);
    public void loadAotdInto(final JaumoActivity activity, final ViewGroup parent, final AotdViewLoadedListener listener, String referrer) {
        loadAppOfTheDay(activity, new AotdLoadedListener() {
            public void onAotdLoaded(Offer offer) {
                if (offer.creatives.length > 0) {
                    final Creative c = offer.creatives[0];
                    View v = activity.getLayoutInflater().inflate(R.layout.ad_aotd, parent, false);
                    JQuery q = new JQuery(v);
          , offer.rewards);
          , offer.rewards)
                            .clicked(new View.OnClickListener() {
                                public void onClick(View v) {
        }, referrer);