iOS Setup Guide

The HyprMX SDK is designed to present rewarded, interstitial, and banner/MREC ads in your application. To integrate the SDK, follow the steps below.

Apple Privacy Manifest is included in iOS SDK 6.3.0.1+

SDK Integration

The SDK can be integrated using CocoaPods or by Manual Installation.

If your app is integrated with HyprMX SDK 6.x and you need help with migrating to 6.4+, please follow the steps in the migration guide.

CocoaPods

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. To integrate the HyprMX SDK with CocoaPods, add the following to your Podfile:

pod 'HyprMX', '6.4.1'

Note: HyprMX 6.0.0+ supports Cocoapods 1.10+

Manual Installation

To manually install the framework, follow the steps below.

1. Download the SDK here and unzip the file.

2. Drag and drop the HyprMX.xcframework (available in the zip) into your Xcode project. Make sure that the files are copied and verify the target membership.

Add HyprMX SDK to your Xcode Project

3. Select your Project File and the Target. In the "General" tab, drag the HyprMX.xcframework from the File Explorer into the "Frameworks, Libraries, and Embedded Content" section.

4. Set the Embed setting to "Embed & Sign".

Xcode Project Setup

Application Transport Security

We recommend that ATS (App Transport Security) settings are turned off as Apple has put on hold their efforts to enforce the policy. In order to do so, add the App Transport Security dictionary key below to your Info.plist.

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>   

If you prefer to enable ATS, you must add the below App Transport Security dictionary keys to your Info.plist to ensure that HyprMX operates properly.

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoadsForMedia</key>
    <true/>
    <key>NSAllowsArbitraryLoadsInWebContent</key>
    <true/>
</dict> 

Configuring Privacy Controls

iOS requires that the use of a user's camera, photo library, IDFA, etc. be declared by advertisers in the plist. Add all of the following entries to your app's plist.

<key>NSCameraUsageDescription</key>
    <string>${PRODUCT_NAME} requests write access to the Camera</string>
<key>NSPhotoLibraryAddUsageDescription</key>
    <string>${PRODUCT_NAME} requests write access to the Photo Library</string> 
<key>NSUserTrackingUsageDescription</key>
    <string>${PRODUCT_NAME} would like to show you personalized ads</string>

SKAdNetwork Identifier

HyprMX SDK 5.4.0+ supports Apple's new SKAdNetwork for Attribution. To add the HyprMX SKAdNetwork ID to your info.plist:

<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>nu4557a4je.skadnetwork</string>
    </dict>
    ...
</array>

Note: SKAdNetwork IDs are case sensitive. For more information about SKAdNetwork please refer to Apple's documentation.

Orientation

HyprMX recommends your app support all orientations globally to maximize ad fill, as HyprMX ads may be shown in any orientation, and our view controller needs your app to support that behavior. You can configure this by selecting all possible orientations under the General tab of your Xcode target, or by configuring the supportedInterfaceOrientations in your App Delegate:

Swift

func application(_ application: UIApplication, 
                supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
    return .all
}

Objective-C

- (UIInterfaceOrientationMask)application:(UIApplication *)application 
  supportedInterfaceOrientationsForWindow:(UIWindow *)window {
    return UIInterfaceOrientationMaskAll;
}

Please note, this setup does not require that your app's interface support all orientations. You just have to configure your view controllers' orientation settings:

Swift

public override var supportedInterfaceOrientations: UIInterfaceOrientationMask {
    return .landscape
}

public override var preferredInterfaceOrientationForPresentation: UIInterfaceOrientation {
    return .landscapeLeft
}

Objective-C

- (UIInterfaceOrientationMask)supportedInterfaceOrientations {
    return UIInterfaceOrientationMaskLandscape;
}

- (UIInterfaceOrientation)preferredInterfaceOrientationForPresentation {
    return UIInterfaceOrientationLandscapeLeft;
}

Importing the SDK

To import the HyprMX Mobile SDK into your Application:

Swift

import HyprMX

Objective-C

@import HyprMX;

Initializing HyprMX

After you have integrated the SDK, proceed to initialize the HyprMX SDK. To initialize, see details below. As a best practice, initialize HyprMX as soon as possible (i.e. when your application is loading) so we can begin preloading ads.

Initialization API

Sample Initializer

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let distributorId = "Your Distributor ID"
 
    Task {
        let completed = await HyprMX.initialize(distributor: distributorId)
        switch completed {
            case .success:
                handleSuccess()
            case .failure(let error):
                print(error)
                handleFailure()
        }
    }

    return true
}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  NSString *distributorId = @"Your Distributor ID";

  [HyprMX initWithDistributorId:distributorId
                     completion: ^(BOOL success, NSError * _Nullable error) {
      if (success) {
          handleSuccess();
      } else {
          NSLog(@"%@", [error description]);
          handleFailure();
      }
  }];

  return YES;
}

distributorID (required)

The value for distributorId is assigned to your application by HyprMX. If you have not received this ID, please reach out to your HyprMX account manager.

After receiving the initializationDidComplete message, you are now ready to load and display ads in your application. See our Rewarded Ads, Interstitial Ads, and Banner/MREC Ads guides to add these ad types to your application.

After Initialization

After receiving a successful result from initialize, you are now ready to load and display ads in your application. See our Rewarded Ads, Interstitial Ads, and Banner/MREC Ads guides to add these ad types to your application.

[Optional] Passing Alternative Identifiers

Alternative/Extended IDs are supported in HyprMX SDK 6.4+.

HyprMX SDK supports the following alternative IDs or extended IDs (EID) to help improve monetization. If applicable, you are responsible for tokenizing IDs before passing them to HyprMX SDK.

• Unified ID 2.0 (UID2)

• ID5

• LiveIntent ID

The following code snippet shows how to pass the IDs to HyprMX. Any optional fields supplied should be of the correct type.

Swift

let uid2 = [
    [
        "id": "testUID2Id"
    ]
]

let id5 = [
    [
        "id": "testID5Id",
        "linkType": 2, // Optional. Only integer values 0..3 are allowed.
        "abTestingControlGroup": true // Optional
    ]
]

let liveintent = [
    [
        "id": "testLiveintentId",
        "atype": 1 // Optional. Only integer values 1, 2, 3, or 500+ allowed
    ]
]

let eids = [
    "uid2": uid2, // Optional
    "id5": id5, // Optional
    "liveintent": liveintent // Optional
]

if let eidData = try? JSONSerialization.data(withJSONObject: eids) {
    HyprMX.setUserExtras(String(data: eidData, encoding: .utf8) ?? "", for: "eids")
}

Objective C

NSArray *uid2 = @[
    @{
        @"id": @"testUID2Id"
    }
];

NSArray *id5 = @[
    @{
        @"id": @"testID5Id",
        @"linkType": @2, // Optional. Only integer values 0..3 are allowed.
        @"abTestingControlGroup": @true // Optional
    }
];

NSArray *liveintent = @[
    @{
        @"id": @"testLiveintentId",
        @"atype": @1 // Optional. Only integer values 1, 2, 3, or 500+ allowed
    }
];

NSDictionary *eids = @{
    @"uid2": uid2,
    @"id5": id5,
    @"liveintent": liveintent
};
    
NSData *eidData = [NSJSONSerialization dataWithJSONObject:eids options:0 error:nil];
if (eidData) {
    NSString *eidJsonString = [[NSString alloc] initWithData:eidData encoding:NSUTF8StringEncoding];
    if (eidJsonString) {
        [HyprMX setUserExtras:eidJsonString for:@"eids"];
    }
}

For best results, set alternative/extended IDs before initializing HyprMX.

Passing an empty string instead of json clears all alternative/extended IDs.

Privacy Compliance

Please refer to our Privacy page to learn more about your privacy compliance responsibilities and to implement the relevant privacy methods.

License

By integrating the HyprMX SDK, you are agreeing to the End User License Agreement.