Advanced Settings

Set UserID

If you’re using server-to-server callbacks to reward your users with ironSource 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 a format of 64 characters NSString. 

[IronSource setUserId:YOUR_USERID];
IronSource.setUserId(userID)
Note:  You should not use IDFA 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 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, OS, etc. You do not need to convey this data to us
  • User Properties: user data which is not collected by our SDK, 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 these details so our SDK can apply the relevant ad settings to the segments you defined on the ironSource platform
  • Custom Segments: you can create a custom segment with predefined conditions without conveying user details to our servers and tailor ad settings for that user segment on the ironSource platform
Dynamic Segmentation If you’re using ironSource SDK 7.2.0+, you can use ISSegment 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 ironSource segmentation here.   

Pass User Properties

Once you’ve defined segments on the ironSource platform, you should inform our servers of the user’s particulars.

First, init the segment:

ISSegment *segment = [[ISSegment alloc]init];
let segment: ISSegment = ISSegment()

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:
    [segment setSegmentName:YOUR_SEGMENT_NAME];
    segment.segmentName = "YOUR_SEGMENT_NAME"
  2. 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. See table below for descriptions.
    // Set user age
    [segment setAge:USER_AGE]; 
    // Set user gender
    [segment setGender:USER_GENDER];
    // Set user level
    [segment setLevel:USER_LEVEL];
    // Set user's paying status
    [segment setPaying:USER_PAYING];
    // Set user's total in-app purchase history
    [segment setIapTotal:YOUR_IAP_TOTAL];
    // Set user creation date
    [segment setUserCreationDate:YOUR_DATE];
    // Set user age
    segment.age = USER_AGE
    // Set user gender
    segment.gender = ISGender.IRONSOURCE_USER_FEMALE
    // Set user's total in-app purchases
    segment.iapTotal = USER_IAP_TOTAL
    // Set user's level
    segment.level = USER_LEVEL
    // Set user's paying status
    segment.paying = USER_PAYING_STATUS
    // Set user creation date
    segment.userCreationDate = NSDate() as Date!

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

    [segment setCustomValue:YOUR_CUSTOM_VALUE forKey:YOUR_CUSTOM_KEY];
    segment.setCustomValue("CUSTOM_VALUE", forKey: "CUSTOM_KEY")

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

    [IronSource setSegment:YOUR_SEGMENT];
    IronSource.setSegment(YOUR_SEGMENT);

Supported Segment Properties

Segment Properties Type Limitation Description
segmentName String
  • alphanumeric
  • up to 32 letters
The given name of the segment in your ironSource account
Age Int 1-99 The user’s age
Gender enum IRONSOURCE_USER_MALE or IRONSOURCE_USER_FEMALE The user’s gender
Paying Boolean Yes or No
  • 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 NSDate Cannot be smaller than 0 The date the user installed the app
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

Obtain the User’s Segment Name

  1. Adopt this interface in your class to conform to the Segment Name protocol and enable the receipt of the segment name ISSegmentDelegate
  2. Register to the following delegate to receive the segment name that your user belongs to. The SDK will then notify your delegate of the event.
    [IronSource setSegmentDelegate:self];
    IronSource.setSegmentDelegate(self)
  3. (void)didReceiveSegement:(NSString *)segment
    func didReceiveSegement(_ segment: String!)

Custom Parameters for iOS

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 Unity LevelPlay.

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

  • Custom Parameters can be set several times per session.
  • To reset the value, use clearRewardedVideoServerParameters, and then set the new value.
[IronSource setRewardedVideoServerParameters:(NSDictionary *)parameters];
[IronSource clearRewardedVideoServerParameters];


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 version for this feature is 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 configuration
LPMInterstitialAdConfig *adConfig = [[[LPMInterstitialAdConfigBuilder new] setBidFloor: 1.23] build]; // Set the price floor in USD
// Apply the configuration to an interstitial ad unit
LPMInterstitialAd *interstitialAd = [[LPMInterstitialAd alloc] initWithAdUnitId:@"adUnitId" config:adConfig];
// Define a price floor configuration
let adConfig = LPMInterstitialAdConfigBuilder()
 .set(bidFloor: 1.23) // Set the price floor in USD
 .build()
// Apply the configuration to an interstitial ad unit
let interstitialAd = LPMInterstitialAd(adUnitId: "adUnitId", config: adConfig)

Full interstitial implementation is available here.

Rewarded ads example

// Define a price floor configuration
LPMRewardedAdConfig *adConfig = [[[LPMRewardedAdConfigBuilder new] setBidFloor: 1.23] build]; // Set the price floor in USD
// Apply the configuration to a rewarded ad unit
LPMRewardedAd *rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId" config:adConfig];
// Define a price floor configuration
val adConfig = LevelPlayRewardedAd.Config.Builder()
 .setBidFloor(1.23) // Set the price floor in USD
 .build()
// Apply the configuration to a rewarded ad unit
val rewardedAd = LevelPlayRewardedAd("adUnitId", adConfig)

Full rewarded ads implementation is available here.

// Define a price floor configuration
LPMBannerAdViewConfig *adConfig = [[[LPMBannerAdViewConfigBuilder new] setBidFloor: 1.23] build]; // Set the price floor in USD
// Apply the configuration to a banner ad unit
LPMBannerAdView *bannerAd = [[LPMBannerAdView alloc] initWithAdUnitId:@"adUnitId" config:adConfig];
// Define a price floor configuration
let adConfig = LPMBannerAdViewConfigBuilder()
 .set(bidFloor: 1.23) // Set the price floor in USD
 .build()
// Apply the configuration to a banner ad unit
let bannerAd = LPMBannerAdView(adUnitId: "adUnitId", adConfig)

Full banner ads implementation is available here.

ironSource SDK Error Codes

ironSource provides an error feedback mechanism to provide an 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
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
524 Interstitial Show Fail: Placement %@ has reached its limit as defined per pace
Show Fail: Placement %@ has reached its capping limit
Rewarded Video
526 Interstitial Show Fail: Ad unit has reached its daily cap per session
Rewarded Video
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 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