Advanced Settings

Set UserID

If you’re serving the offerwall ad unit or using server-to-server callbacks to reward your users with ironSource rewarded ad units, 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)

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

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

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

Implementation Code

Rewarded Video

[IronSource setRewardedVideoServerParameters:(NSDictionary *)parameters];
[IronSource clearRewardedVideoServerParameters];

Offerwall

NSMutableDictionary * owDic = [[NSMutableDictionary alloc] init];
owDic[@"ip"] = @"1.0.0.9";
[ISConfigurations configurations].offerwallCustomParameters = owDic;

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:

NSMutableDictionary * owDic = [[NSMutableDictionary alloc] init];
owDic[@"ip"] = @"1.0.0.9";
[ISConfigurations configurations].offerwallCustomParameters = owDic;

You will receive a corresponding callback as exemplified below:

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:

Create a waterfall configuration

The WaterfallConfiguration class represents a configuration object for customizing or filtering a waterfall. 
In order to create a waterfall configuration, define a WaterallConfigurationBuilder:

// define a WaterallConfigurationBuilder
ISWaterfallConfigurationBuilder *builder = [ISWaterfallConfiguration builder];
// Build the WaterfallConfiguration and add data to constrain or control a waterfall
[builder setCeiling:@ceiling];
[builder setFloor:@floor];
ISWaterfallConfiguration *configuration = [builder build];
//set a configuration for an ad unit
[IronSource setWaterfallConfiguration:configuration forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];

// Build the WaterfallConfiguration and add data to constrain or control a waterfall
let configuration = ISWaterfallConfiguration.builder()
    .setCeiling(10.05)
    .setFloor(1.01)
    .build()
//set a configuration for an ad unit
IronSource.setWaterfallConfiguration(configuration, for: ISAdUnit.is_AD_UNIT_REWARDED_VIDEO())

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 ISWaterfallConfiguration.clear() function.

ISWaterfallConfiguration *clearConfiguration = [ISWaterfallConfiguration clear];
[IronSource setWaterfallConfiguration:clearConfiguration forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];

let clearConfiguration = ISWaterfallConfiguration.clear();
IronSource.setWaterfallConfiguration(clearConfiguration, for: ISAdUnit.is_AD_UNIT_REWARDED_VIDEO());

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.

...
[IronSource setWaterfallConfiguration:configuration forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];
ISWaterfallConfigurationBuilder *builder2 = [ISWaterfallConfiguration builder];
[builder2 setCeiling:@ceiling];
[builder2 setFloor:@floor];
ISWaterfallConfiguration *configuration2 = [builder build];
[IronSource setWaterfallConfiguration:configuration2 forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];

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: