Advanced Settings

Set User ID

If you’re using server-to-server callbacks to reward your users with ironSource SDK rewarded ad units, or using Ad Quality user journey, you must define a unique identifier for each user (“UserID”), using the setUserID method.

Set the UserID before the init request, to make sure you avoid any data loses, related to the user. Use a unique identifier, with up to 64 alphanumeric characters.

IronSource.setUserId("UserID");
Note: You should not use GAID/AAID as an identifier, in order to ensure UserID is available and unique for all users.

Define Segments

You can now easily tailor the way you serve your ads to fit a specific audience! You’ll need to inform our servers of the users’ details so the SDK will know to serve ads according to the segment the user belongs to.

ironSource SDK supports three methods to convey data to our servers to outline the user segment, namely:

  • Device Properties: the ironSource SDK collects certain standard parameters that pertain to the users’ device automatically such as location, device model, device manufacturer, app version, OS, etc. You do not need to convey this data to us.
  • User Properties: comprehensive user data such as age, gender, creation date, etc. (see full list of supported segment properties with descriptions below) must be relayed through the API. Follow the instructions to send us your user’s details so our SDK can categorize your different users based on the segments you defined on the LevelPlay platform.
  • Custom Segments: you can create a custom segment without conveying user details to our servers and tailor ad settings for that user segment.
Dynamic Segmentation If you’re using ironSource SDK 7.2.0+, you can use IronSourceSegment API to change your segmentation during the session.
This will affect the next loaded ad, and can be called before loading each ad unit, to dynamically affect the waterfall . You can learn more about LevelPlay segmentation here.   

Pass User Properties

Once you’ve defined segments on the LevelPlay platform, you’ll need to inform our servers of the user’s particulars.

Define what properties to send to our servers on which to base the segments. You can transmit this information through one of the following methods:

  1. If you are familiar with the segment that the user belongs to, enter the segment name:
    mIronSegment.setSegmentName(name);
  2. Send us the user details. ironSource SDK provides a range of standard user properties that you can set to attribute a user to a segment in the API.  Scroll down for a table of the support user segment properties.
    // Create segment object
    mIronSegment = IronSourceSegment();
    // Set user age
    mIronSegment.setAge(age);
    // Set user gender
    mIronSegment.setGender(gender);
    // Set user's level
    mIronSegment.setLevel(level);
    // Set user creation date
    mIronSegment.setUserCreationDate(date);
    // Set user's total in-app purchases
    mIronSegment.setIAPTotal(iapt);
    // Set user's paying status
    mIronSegment.setIsPaying(isPaying);
    

    In addition, you can set up to 5 custom user properties per segment:

    // Set custom parameters (up to 5)
    mIronSegment.setCustom(key,value);
    

    Next, to serve your ad units based on segments to tailor the user’s ad experience, call the following function complete with either the segment name or user properties:

    IronSource.setSegment(mIronSegment);
    

Supported User Segment Properties

Segment Properties Type Limitation Description
segmentName String
  • alphanumeric
  • up to 32 letters
The given name of the segment in your LevelPlay account
Age Int 1-99 The user’s age
Gender String female or male The user’s gender
Paying Boolean True or False
  • True if the user has spent any money on in-app purchases
  • False if the user has not spent any money on in-app purchases
iap_total Double 1-999999.99 The total amount of money that the user has spent on in-app purchases
userCreationDate Long Cannot be smaller than 0 The date the user installed the app in milliseconds
Custom Parameters key=string, value=string
  • ironSource SDK supports up to 5 custom parameters
  • alphanumeric
  • up to 32 letters
Any additional data you’d like to dispatch to our server


Register to the following callback to receive the segment name that your user belongs to. If the callback string (segment name) returns empty, there were no correlating segments found for the user in the ironSource Segment module.

SegmentListener onSegmentReceived(String segment){}

Custom Parameters 

The ironSource SDK supports custom parameters for Rewarded Video and Offerwall. You can pass custom parameters upon the initialization of the ad unit and receive the parameters upon a user’s completion event.
You can now pass custom parameters for all mediation networks on the LevelPlay mediation platform.

Note:
  1. Custom parameters work in conjunction with server-to-server completion callbacks only. You will receive the parameter as part of the callback string.
  2. You may insert more than one custom parameter in the init request. 

Implementation Code

Rewarded Video

Note:
  • Custom Parameters can be set several times per session.
  • To reset the value, use clearRewardedVideoServerParameters, and then set the new value.
IronSource.setRewardedVideoServerParameters(Map<String, String> params);
IronSource.clearRewardedVideoServerParameters();

Offerwall

Note:
  • Custom Parameters should be called before calling showOfferwall.
Map<String, String> owParams = new HashMap<String,String>();
owParams.put("ip", "123.4.56.78");
SupersonicConfig.getConfigObj().setOfferwallCustomParams(owParams);

Implementation Example

For example, if you’d like to receive the IP of a user who engaged with the Offerwall, you can add this as an additional parameter in the completion callback:

Map<String, String> owParams = new HashMap<String,String>();
owParams.put("ip", "123.4.56.78");
SupersonicConfig.getConfigObj().setOfferwallCustomParams(owParams);

You will then receive a corresponding callback as exemplified below:

http://www.mydomain.com/rewardsCallback?appUserId=[USER_ID]&rewards=[REWARDS]&eventId=[EVENT_ID]&itemName=[ITEM_NAME]&custom_ip=1.0.0.9 

Price limitations using waterfall configuration (beta)

Set Waterfall Configuration is an API that can be used to dynamically set limits for the waterfall: price ceiling and price floor. You can use it to set limits and dynamically affect the WF returned per user, resulting in reduced load times and latency. 

Limits include, and can be any combination of these parameters:

Properties Type Description
ceiling double The price in USD, which defines the maximal eCPM applies to traditional instances
floor double The price in USD, which defines the minimal eCPM applies to traditional instances and bidders

Create a waterfall configuration

The WaterfallConfiguration class represents a configuration object for customizing or filtering a waterfall. Implement the following to create a waterfall configuration:

// define a WaterfallConfigurationBuilder
WaterfallConfiguration.WaterfallConfigurationBuilder builder = WaterfallConfiguration.builder();
// Build the WaterfallConfiguration and add data to constrain or control a waterfall
WaterfallConfiguration waterfallConfiguration = builder
  .setFloor(floor)
  .setCeiling(ceiling)
  .build();
// set a configuration for an ad unit
IronSource.setWaterfallConfiguration(waterfallconfiguration, IronSource.AD_UNIT.AdUnitName);

Clearing a Waterfall Configuration

It is possible to change the waterfall configuration during the session. To clear the configuration for a given ad unit, use the `empty` WaterfallConfiguration function:

IronSource.setWaterfallConfiguration(WaterfallConfiguration.empty(), IronSource.AD_UNIT.AdUnitName);

Overwriting a Waterfall Configuration

A built WaterfallConfiguration is immutable. You must create a new Waterfall Configuration to change the existing configuration from a previous one. One may also inline the builder and set definitions in keeping with the builder pattern.

...
setWaterfallConfiguration(waterfallconfiguration, IronSource.AD_UNIT.AdUnitName);
WaterfallConfiguration waterfallConfiguration2 = WaterfallConfiguration.builder()
  .setFloor(floor)
  .setCeiling(ceiling)
  .build();
IronSource.setWaterfallConfiguration(waterfallConfiguration2, IronSource.AD_UNIT.AdUnitName);

ironSource SDK Error Codes

ironSource provides an error feedback mechanism to provide explanation for any failure in the SDK integration. You will receive these errors when something went wrong or an aspect of the integration wasn’t completed correctly.

The ironSource Error object contains an error code and message. These are all the possible errors and their message based on their functions:

Error Codes Ad Unit Description
508 N/A • Init failure of the mediation/Network
• Calling a Demand Only API in non Demand Only mode
• Calling a non Demand Only API in Demand Only mode
509 Interstitial Show Fail: No ads to show
Rewarded Video
Offerwall
510 Interstitial Load Fail: Server response failed
Rewarded Video
Banner
520 Interstitial Show Fail: No internet connection; 
ShouldTrackNetworkState is enabled
Rewarded Video Show Fail: No internet connection
Offerwall
524 Interstitial Show Fail: Placement %@ has reached its limit as defined per pace
Show Fail: Placement %@ has reached its capping limit
Rewarded Video
Offerwall
526 Interstitial Show Fail: Ad unit has reached its daily cap per session
Rewarded Video
1007 Interstitial Auction Fail: Auction request did not contain all required information
Rewarded Video
1022 Rewarded Video Show Fail: Cannot show an RV while another RV is showing
1023 Rewarded Video Show Fail: Show RV called when there are no available ads to show
1035 Interstitial Empty Waterfall
1036 Interstitial Show Fail: Cannot show an interstitial while another interstitial is showing
1037 Interstitial Load Fail: Cannot load an interstitial while another interstitial is showing
1039 Interstitial Exception while calling show interstitial