Configure Mediation

Test Mode πŸ”—

Test Mode allows you to test your partner integrations and get their test ads. To enable, add the environment variable HELIUM_TEST_MODE in your app’s scheme. Remember to remove or set the method to off before releasing your app.

Privacy Methods πŸ”—

The following privacy methods are used to set different privacy settings:

COPPA πŸ”—

setSubjectToCoppa πŸ”—

  • Helium.shared().setSubjectToCoppa(true)
    // or
    Helium.shared().setSubjectToCoppa(false)
    
  • [[Helium sharedHelium] setSubjectToCoppa:YES];
    // or
    [[Helium sharedHelium] setSubjectToCoppa:NO];
    
  • By sending setSubjectToCoppa(true)/setSubjectToCoppa (YES) you indicate that you want your content treated as child-directed for purposes of COPPA. We will take steps to disable interest-based advertising for such ad requests.
  • By sending setSubjectToCoppa(false)/setSubjectToCoppa (NO), you indicate that you don’t want your content treated as child-directed for purposes of COPPA. You represent and warrant that your applications and services are not directed towards children and that you will not provide any information to Mediation from a user under the age of 13.

GDPR πŸ”—

setSubjectToGDPR πŸ”—

  • Helium.shared().setSubjectToGDPR(true)
    // or
    Helium.shared().setSubjectToGDPR(false)
    
  • [[Helium sharedHelium] setSubjectToGDPR:YES];
    // or
    [[Helium sharedHelium] setSubjectToGDPR:NO];
    
  • By sending setSubjectToGDPR(true)/setSubjectToGDPR (YES), you indicate that GDPR is applied to this user from your application.
  • By sending setSubjectToGDPR(false)/setSubjectToGDPR (NO), you indicate that GDPR is not applied to this user from your application.

setUserHasGivenConsent πŸ”—

  • Helium.shared().setUserHasGivenConsent(true)
    // or
    Helium.shared().setUserHasGivenConsent(false)
    
  • [[Helium sharedHelium] setUserHasGivenConsent:YES];
    // or
    [[Helium sharedHelium] setUserHasGivenConsent:NO];
    
  • By sending setUserHasGivenConsent(true)/setUserHasGivenConsent (YES), you indicate that this user from your application has given consent to share personal data for behavior-targeted advertising.
  • By sending setUserHasGivenConsent(false)/setUserHasGivenConsent (NO), you indicate that this user from your application has not given consent to use its personal data for behavior-targeted advertising, so only contextual advertising is allowed.

CCPA πŸ”—

setCCPAConsent πŸ”—

  • Helium.shared().setCCPAConsent(true)
    // or
    Helium.shared().setCCPAConsent(false)
    
  • [[Helium sharedHelium] setCCPAConsent:YES];
    // or
    [[Helium sharedHelium] setCCPAConsent:NO];
    
  • By sending setCCPAConsent(true)/setCCPAConsent (YES), you indicate that this user from your application has given consent to share personal data for behavior-targeted advertising under CCPA regulation.
  • By sending setCCPAConsent(false)/setCCPAConsent (NO), you indicate that this user from your application has not given consent to allow sharing personal data for behavior-targeted advertising under CCPA regulation.

Keywords πŸ”—

As of Mediation 2.9.0, the Mediation SDKs introduce keywords: key-value pairs to enable real-time targeting of line items.

Set Keywords πŸ”—

To set keywords, you will need to first create a Mediation ad object, then use the setKeyword method to add key-value keywords pair.

  • let interstitial = Helium.shared().interstitialAdProvider(with: self, andPlacementName: "placement")
    let rewarded = Helium.shared().rewardedAdProvider(with: self, andPlacementName: "placement")
    let banner = Helium.shared().bannerProvider(with: self, andPlacementName: "placement", andSize: .standard)
    
    // Setting Keyword
    // (The set method returns a boolean whether or not if the keyword has been successfully set)
    let success = interstitial?.keywords?.set(keyword: "i12_keyword1", value: "i12_value1") ?? false
    if (!success) {
        // Failed to set keyword
    }
    let success = rewarded?.keywords?.set(keyword: "rwd_keyword1", value: "rwd_value1") ?? false
    if (!success) {
        // Failed to set keyword
    }
    let success = banner?.keywords?.set(keyword: "bnr_keyword1", value: "bnr_value1") ?? false
    if (!success) {
        // Failed to set keyword
    }
    
  • // Create a Mediation Ad object.
    id<HeliumInterstitialAd> interstitial = [Helium.sharedHelium interstitialAdProviderWithDelegate:self andPlacementName:@"placement"];
    id<HeliumRewardedAd> rewarded =
    [Helium.sharedHelium rewardedAdProviderWithDelegate:self andPlacementName:@"placement"];
    HeliumBannerView *banner =
    [Helium.sharedHelium bannerProviderWithDelegate:self andPlacementName:@"placement" andSize:CHBHBannerSize_Standard];
    // Setting Keyword
    // (The set method returns a boolean whether or not if the keyword has been successfully set)
    BOOL success = [interstitial.keywords setKeyword:@"i12_keyword1" value:@"i12_value1"];
    if (success == NO) {
    // Failed to set keyword
    }
    BOOL success = [rewarded.keywords setKeyword:@"rwd_keyword1" value:@"rwd_value1"];
    if (success == NO) {
    // Failed to set keyword
    }
    BOOL success = [banner.keywords setKeyword:@"bnr_keyword1" value:@"bnr_value1"];
    if (success == NO) {
    // Failed to set keyword
    }
    

Remove Keywords πŸ”—

To remove keywords, simply use the removeKeyword method and pass the key you would like to remove.

  • // Remove Custom Keyword (The remove method returns the value of the key removed)
    let removedi12KeywordValue = interstitial?.keywords?.remove(keyword:"i12_keyword1");
    let removedRewardedKeywordValue = interstitial?.keywords?.remove(keyword: "rwd_keyword1");
    let removedBannerKeywordValue = interstitial?.keywords?.remove(keyword: "bnr_keyword1");
    
  • // Remove Custom Keyword (The remove method returns the value of the key removed)
    NSString *removedi12KeywordValue = [interstitial.keywords removeKeyword:@"i12_keyword1"];
    NSString *removedRewardedKeywordValue = [rewarded.keywords removeKeyword:@"rwd_keyword1"];
    NSString *removedBannerKeywordValue = [banner.keywords removeKeyword:@"bnr_keyword1"];
    

Impression Level Revenue Data (ILRD) πŸ”—

Impression Level Revenue Data (ILRD) is data we collect on the server side and store in our database today. This feature allows publishers access to this data.

An ILRD event occurs every time an impression is tracked. The fields that a publisher is interested in are broken down as follows:

ILRD Key Value ILRD Description
"ad_revenue" Double Double-precision floating point
"currency_type" String Always USD
"country" String Three-letter country code ISO_3166-1_alpha-3 (ex.: USA)
"impression_id" String ID
"line_item_name" String Mediation line item name
"line_item_id" String Mediation line item id
"network_name" String Network Name
"network_placement_id" String Partner placement name
"network_type" String Either bidding or mediation
"placement_name" String Mediation placement name
"placement_type" String Ad type:
- interstitial
- rewarded</br>- banner
"precision" String One of the following:
- estimated
- exact
- publisher_defined
- undisclosed

Bid Specific ILRD πŸ”—

{
 "network_name": "adcolony",
 "network_type": "bidding",
 "precision": "exact",
 "ad_revenue": 0.02375,
 "network_placement_id": "vz6a00690d16ec4b5ba9"
}

Ad Response ILRD πŸ”—

{
 "impression_id": "2a3a70a8d161ce2942d73436123e7fba04983bd1",
 "currency_type": "USD",
 "country": "USA",
 "placement_name": "ACRewarded",
 "placement_type": "rewarded"
 }

Combined ILRD πŸ”—

{
 "ad_revenue": 0.055,
 "currency_type": "USD",
 "country": "USA",
 "impression_id": "ae112f3dccf90c705f2d3b1324605e9d16687725",
 "line_item_name": "helium_rv_T1_tapjoy_high",
 "line_item_id": "33f6b0ca-1b3c-4e69-80dd-b57db13db159",
 "network_name": "tapjoy",
 "network_placement_id": "tapjoy_RV_0_25",
 "network_type": "mediation",
 "placement_name": "heliumTapjoyTest",
 "placement_type": "rewarded",
 "precision": "publisher_defined"
}

Publishers will have two ways of receiving this data:

  1. On iOS, we provide a global notification that gives publishers access to ILRD data on each impression event shown in real time.
  2. For API access, we will provide an ILRD reporting API where publishers can request a custom report (CSV) of all their ILRD data filtered by appId, min_date, max_date.

Publishers will use ILRD data in several ways:

  • They can listen to the data via SDK notifications in real time and ship it to their own servers, or to other MMPs such as AppsFlyer & Adjust.
  • They can manually request a report via the API endpoint and analyze it whenever they wish to do so.

Rewarded Callbacks πŸ”—

Setting the User ID and Custom Data through the SDK

Setting User Identifier πŸ”—

The user identifier property is found on the Helium object. This property may be set anytime after SDK initialization.

  • Helium.shared().userIdentifier = "user"
    
  • Helium.sharedHelium.userIdentifier = @"user";
    

Setting Custom Data πŸ”—

The custom data property is found on the HeliumRewardedAd instance, and has a maximum character limit of 1000 characters. In the event that the limit is exceeded, the customData property will be set to nil.

Custom data may be set at any time before calling showAdWithViewController:.

It is recommended to base 64 encode the custom data!

  • let rewardedAd = Helium.shared().rewardedAdProvider(with: self, andPlacementName: "placement")
    // load ad
    let customData = "custom data".data(using: .utf8)
    let base64CustomData = customData?.base64EncodedString()
    rewardedAd?.customData = base64CustomData
    // show ad
    
  • id<HeliumRewardedAd> rewardedAd = [Helium.sharedHelium rewardedAdProviderWithDelegate:self andPlacementName:@"placement"];
    // load ad
    NSData *customData = [@"custom data" dataUsingEncoding:NSUTF8StringEncoding];
    NSString *base64CustomData = [customData base64EncodedStringWithOptions:0];
    rewardedAd.customData = base64CustomData;
    // show ad
    

See: Mediation SDK: Manage Placement’s Rewarded Callbacks for configuration setup

Implementation πŸ”—

The iOS SDK will provide a new NSNotification event that will be broadcast to all listeners via NSNotificationCenter.

The HeliumImpressionData class will be specified as follows:

public class HeliumImpressionData: NSObject {
  // The placement associated with Impression Level Revenue Data.
  let placement: String

  // The Impression Level Revenue Data JSON.
  let jsonData: [String : Any]
}

Usage Example

NotificationCenter.default.addObserver(
    self,
    selector: #selector(didReceiveILRDNotification),
    name: .heliumDidReceiveILRD,
    object: nil
)

@objc func didReceiveILRDNotification(notification: Notification) {
    // Extract the ILRD payload.
    guard let ilrd = notification.object as? HeliumImpressionData else {
        return
    }

    // Placement name
    let placement = ilrd.placement

    // JSON
    let json = ilrd.jsonData
}

Last modified November 27, 2023