Define custom user segments and pass unique User IDs to tailor ad delivery and track user journeys across all mediation networks in Unity LevelPlay.
Read time 6 minutesLast updated 2 months ago
Set UserID
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 losses, related to the user. Use a unique identifier, with up to 64 alphanumeric characters (String format for Android; NSString format for iOS).
IronSource.Agent.setUserId(YOUR_USER_ID);
Note
You should not use IDFA or GAID as identifiers, 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 device model, device manufacturer, app version, and OS. You do not need to convey this data to us
User Properties: user data which is not collected by our SDK (for example, age, gender, or creation date) must be relayed through the API. (See a full list of supported segment properties with descriptions in the following section). Follow the instructions to send us these details so our SDK can apply the relevant ad settings to 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
Note
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
After 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:
If you are familiar with the segment that the user belongs to, enter the segment name:
IronSourceSegment segment = new IronSourceSegment ();
segment.segmentName = "nameOfSegment";
Send us the user details. ironSource 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
IronSourceSegment segment = new IronSourceSegment ();
// Set user age
segment.age = age;
// Set user gender
segment.gender = "gender";
// Set user's level
segment.level = levelnumber;
// Set user creation date
segment.userCreationDate=creationData
// Set user's total in-app purchases
segment.iapt = numberOfInAppPurchases;
// Set user's paying status, 1 is yes 0 is no
segment.isPaying = payingStatus;
In addition, you can set up to 5 custom user properties per segment:
// Set custom parameters (up to 5)
Dictionary<string,string> customParams = new Dictionary<string,string> ();
customParams.Add ("customKey", "value");
segment.customs = customParams;
Next, to serve your ad units based on segments, call the following function complete with either the segment name or user properties:
IronSource.Agent.setSegment (segment);
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 (for example:
[NSDate date]
)
Custom Parameters
key=string, value=string
- ironSource 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.
The ironSource SDK supports custom parameters for Rewarded Video. 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
Custom parameters work in conjunction with server-to-server completion callbacks only. You will receive the parameter as part of the callback string.
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 clearRewardedVideoServerParams, and then set the new value.
The API SetPauseGame is introduced into the LevelPlay class as part of the LevelPlay SDK version 8.5.0 and is relevant for iOS apps only.When setting your PauseGame status to “true”, all your Unity 3D game activities will be paused (except the ad callbacks). The game activity will be resumed automatically when the ad is closed.You should call the SetPauseGame API once in your session, before or after initializing the ironSource SDK, and as it affects all ads (Rewarded Video and Interstitial ads for Multiple AdUnit APIs) in the session.
LevelPlay.SetPauseGame(true);
You can deactivate the functionality in this session, by calling the SetPauseGame with the value false:
LevelPlay.SetPauseGame(false);
For legacy ironSource SDK (from 7.2.4 until 8.4.0), use the following API:
// Pause all game activities except ad callbacks. The game activity will be resumed automatically when the ad is closedIronSource.Agent.SetPauseGame(true);// Deactivate the functionality in this sessionIronSource.Agent.SetPauseGame(false);
Price Floor Configuration
The Floor Configuration API lets you set a price floor for a specific ad unit. By setting a price floor for each user, you can improve targeting efficiency, reduce latency, and optimize ad performance.The price floor must be assigned when creating the ad object, and it applies to all subsequent loads for that object.
Note
Min SDK 8.9.0
Property
Type
Description
Bid floor
double
The price in USD that defines the minimum eCPM applied to traditional instances and bidders.
Interstitial ads example
// Define a price floor configurationvar adConfig =newLevelPlayInterstitialAd.Config.Builder().SetBidFloor(1.23)// Set the price floor in USD.Build()// Apply the configuration to an interstitial ad unitvar interstitialAd =newLevelPlayInterstitialAd("adUnitId", adConfig);
Full interstitial implementation is available here.
Rewarded ads example
// Define a price floor configurationvar adConfig =newLevelPlayRewardedAd.Config.Builder().SetBidFloor(1.23)// Set the price floor in USD.Build()// Apply the configuration to a rewarded ad unitvar rewardedAd =newLevelPlayRewardedAd("adUnitId", adConfig);
Full rewarded ads implementation is available here.
Banner ads example
// Define a price floor configurationvar adConfig =newLevelPlayBannerAd.Config.Builder().SetBidFloor(1.23)// Set the price floor in USD.Build();// Apply the configuration to a banner ad unitvar bannerAd =newLevelPlayBannerAd("adUnitId", adConfig);
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, Rewarded Video
Show Fail: No ads to show
510
Interstitial, Rewarded Video, Banner
Load Fail: Server response failed
520
Interstitial, Rewarded Video
Show Fail: No internet connection; ShouldTrackNetworkState is enabled
Show Fail: No internet connection
524
Interstitial, Rewarded Video
Show Fail: Placement %@ has reached its limit as defined per pace
Show Fail: Placement %@ has reached its capping limit
526
Interstitial, Rewarded Video
Show Fail: Ad unit has reached its daily cap per session
604
Banner
Can’t load because the placement is capped
605
Banner
Unexpected exception while loading the banner
606
Banner
No banner fill on all the networks on the first load
1007
Interstitial, Rewarded Video
Auction Fail: Auction request did not contain all required information
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