This HyprMX SDK is designed to present interstitial and rewarded advertisements in your application.

SDK Integration

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

CocoaPods

To integrate the HyprMX SDK with CocoaPods, add the following to your Podfile:

pod 'HyprMX', '5.4.5'

Note: HyprMX 5.4.0+ supports Cocoapods 1.10+

Manual Installation

Add HyprMX SDK to your Xcode Project

To manually add HyprMX.xcframework to your Xcode project:

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

• 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.

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

Application Transport Security

Apple has put on hold their efforts to enforce ATS (App Transport Security) settings, so many developers are simply turning it off. 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 three App Transport Security dictionary keys below to your Info.plist to ensure that HyprMX operates properly.

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

Configuring Privacy Controls

iOS requires that the use of a user's camera, calendar, 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>NSCalendarsUsageDescription</key>
    <string>${PRODUCT_NAME} requests access to the Calendar</string>
<key>NSPhotoLibraryUsageDescription</key>
    <string>${PRODUCT_NAME} requests access to the Photo Library</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 Id's are case sensitive. For more information about SKAdNetwork please refer to Apple's documentation.

Initializing HyprMX

Note: All calls to HyprMX must be done from the main thread.

First, import the HyprMX Mobile SDK.

@import HyprMX;

import HyprMX

To get initialization callbacks, you need to implement the HyprMXInitializationDelegate.

@implementation YourHyprInitializationDelegateImplementation 
- (void)initializationDidComplete {
}
​
- (void)initializationFailed {
}
@end

class YourHyprInitializationDelegateImplementation: <superclass>, HyprMXInitializationDelegate {
    func initializationDidComplete() {
    }
    func initializationFailed() {
    }
}

HyprMX holds a weak reference to the initialization delegate, so you must be sure to retain the delegate.

Initialize HyprMX as done below. As a best practice, initialize HyprMX as soon as possible (i.e. when your application is loading) so we can begin preloading ads.

The initializer includes a consentStatus parameter for jurisdictions that require passing consent that takes a HyprConsentStatus value (CONSENT_STATUS_UNKNOWN, CONSENT_GIVEN, or CONSENT_DECLINED) depending on the user consent collected by your app.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  self.hyprDelegate = [YourHyprInitializationDelegateImplementation new];
  NSString *distributorId = @"Your Distributor ID";
  NSString *userId = @"Your User's ID";
​
  [HyprMX initializeWithDistributorId:distributorId
                               userId:userId
						consentStatus: // If you don't have consent status for the user, set this to CONSENT_STATUS_UNKNOWN
               initializationDelegate:self.hyprDelegate];
​
  return YES;
}

lazy var hyprDelegate = YourHyprInitializationDelegateImplementation()
 
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let distributorId = "Your Distributor ID"
    let userId = "Your User's ID"
 
    HyprMX.initialize(withDistributorId: distributorId,
                      userId: userId,
                      consentStatus: <HyprConsentStatus>, // If you don't have consent status for the user, set this to CONSENT_STATUS_UNKNOWN
                      initializationDelegate: hyprDelegate)
    return true
}

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

The user ID is a unique identifier supplied by your application and must be static for each user across sessions. Your user ID should not contain any personally identifiable information such as an email address, screen name, or Apple's Advertising Identifier (IDFA). If you don't have a static identifier, you can use the code snippet below for generating a unique user ID using NSProcessInfo. To change the user ID, you must re-initialize HyprMX.

NSString *userIdStorageKey = @"hyprMarketplaceUserId";
NSString *userId = [[NSUserDefaults standardUserDefaults] objectForKey:userIdStorageKey];
if (!userId) {
    userId = [[NSProcessInfo processInfo] globallyUniqueString];
    [[NSUserDefaults standardUserDefaults] setObject:userId forKey:userIdStorageKey];
    [[NSUserDefaults standardUserDefaults] synchronize];
}
// initialize HyprMX with userId

let userIdStorageKey = "hyprMarketplaceUserId"
var userId = ""
if let storedUserId = UserDefaults.standard.object(forKey: userIdStorageKey) as? String {
    userId = storedUserId
} else {
    userId = ProcessInfo.processInfo.globallyUniqueString
    UserDefaults.standard.set(userId, forKey: userIdStorageKey)
}

HyprMX also provides a separate setter for consent status. Use this when a user's consent status changes.

[HyprMX setConsentStatus:<HyprConsentStatus>]; 

HyprMX.setConsentStatus(<HyprConsentStatus>)

After receiving the initializationDidComplete message, you are ready to show ads.

Loading and Displaying Advertisements

Placements are objects that allow you to show rewarded and interstitial advertisements. To show an advertisement, use the getPlacement api to retrieve a placement from HyprMX, then set a placementDelegate.

Please reach out to your account manager with what placements you'd like to use in your app and whether they will be rewarded or interstitial. In return, they will provide the names of the new placements. The example below will assume that your account manager has created a "REWARDED", "INTERSTITIAL, and "STORE" placement.

HyprMXPlacement *interstitialPlacement = [HyprMX getPlacement:@"INTERSTITIAL"];
interstitialPlacement.placementDelegate = self;
​
HyprMXPlacement *rewardedPlacement = [HyprMX getPlacement:@"REWARDED"];
rewardedPlacement.placementDelegate = self;
​
HyprMXPlacement *storePlacement = [HyprMX getPlacement:@"STORE"];
storePlacement.placementDelegate = self;

let interstitialPlacement = HyprMX.getPlacement("INTERSTITIAL")
interstitialPlacement.placementDelegate = self
​
let rewardedPlacement = HyprMX.getPlacement("REWARDED")
rewardedPlacement.placementDelegate = self
​
let storePlacement = HyprMX.getPlacement("STORE")
storePlacement.placementDelegate = self

To check for availability, run the following, which calls back to your delegate with adAvailableForPlacement:/adAvailable(for placement:) or adNotAvailableForPlacement:/adNotAvailable(for placement:).

[interstitialPlacement loadAd];
[rewardedPlacement loadAd];
[storePlacement loadAd];

interstitialPlacement.loadAd()
rewardedPlacement.loadAd()
storePlacement.loadAd()

Implement the HyprMXPlacementDelegate.

/** Called in response to loadAd when there is an ad to show */
- (void)adAvailableForPlacement:(HyprMXPlacement *)placement {
}
​
/** Called in response to loadAd when there's no ad to show */
- (void)adNotAvailableForPlacement:(HyprMXPlacement *)placement {
}
​
/** Called when ad loaded is no longer available for this placement */
- (void)adExpiredForPlacement:(HyprMXPlacement *)placement {
}
​
/** Called upon conclusion of any ad presentation attempt */
- (void)adDidCloseForPlacement:(HyprMXPlacement *)placement didFinishAd:(BOOL)finished {
}
​
/** Called when user has earned a reward. */
- (void)adDidRewardForPlacement:(HyprMXPlacement *)placement rewardName:(NSString *)rewardName rewardValue:(NSInteger)rewardValue {
}
​
/** Called immediately before attempting to present an ad. */
- (void)adWillStartForPlacement:(HyprMXPlacement *)placement {
}
​
/** Called when an error occurs during ad presentation. */
- (void)adDisplayErrorForPlacement:(HyprMXPlacement *)placement error:(HyprMXError)hyprMXError {
}

/** Called in response to loadAd when there is an ad to show */
func adAvailable(for placement: HyprMXPlacement!) {
}
​
/** Called in response to loadAd when there's no ad to show */
func adNotAvailable(for placement: HyprMXPlacement!) {
}
​
/** Called when ad loaded is no longer available for this placement */
func adExpired(for placement: HyprMXPlacement!) {
}
​
/** Called upon conclusion of any ad presentation attempt */
func adDidClose(for placement: HyprMXPlacement!, didFinishAd finished: Bool) {
}
​
/** Called when user has earned a reward. */
func adDidReward(for placement: HyprMXPlacement!, rewardName: String!, rewardValue: Int) {
}
​
/** Called immediately before attempting to present an ad. */
func adWillStart(for placement: HyprMXPlacement!) {
}
​
/** Called when an error occurs during ad presentation. */
func adDisplayError(for placement: HyprMXPlacement!, error hyprMXError: HyprMXError) {
}

NOTE: HyprMX holds a weak reference to the placement delegate, so you must be sure to retain the delegate.

When you're ready to show an advertisement you can use the following code snippet. Before calling showAd on a placement you should confirm the ad state is still valid.

When an ad is displaying, it is important to disable all in-game music and sounds so they do not interfere with the advertisements. You can disable them when you get the adWillStartForPlacement:/adWillStart(for placement:) callback and re-enable when you get the adDidCloseForPlacement:/adDidClose(for placement:).

You can call showAdFromViewController: and supply a UIViewController for HyprMX to present from, or pass nil and HyprMX will present from the keyWindow. If your App supports multi-window, it is recommended to provide a viewController to present from.

if ([interstitialPlacement isAdAvailable]) {
  [interstitialPlacement showAdFromViewController:self];
}
 
if ([rewardedPlacement isAdAvailable]) {
  [rewardedPlacement showAdFromViewController:self];
}
​
// Show Ad without providing a UIViewController
if ([storePlacement isAdAvailable]) {
  [storePlacement showAdFromViewController:nil];
}

if interstitialPlacement.isAdAvailable() {
  interstitialPlacement.showAd(from: self)
}
 
if rewardedPlacement.isAdAvailable() {
  rewardedPlacement.showAd(from: self)
}
 
// Show Ad without providing a UIViewController
if storePlacement.isAdAvailable() {
  storePlacement.showAd(from: nil)
}

showAdFromViewController:will begin the presentation of an ad.

The placement will call adWillStartForPlacement:/adWillStart(for placement:) immediately before attempting to show an ad, and call adDidCloseForPlacement:/adDidClose(for placement:) when the ad is closed.

• If there is no ad to display or an error occurs during presentation, adDisplayErrorForPlacement:error:/adDisplayError(for placement:, error hyprMXError:) will be called with an error description, then adDidCloseForPlacement:/adDidClose(for placement:) will be called.

When a user successfully completes a rewarded advertisement you will receive a callback to adDidRewardForPlacement:rewardName:rewardValue:/adDidReward(for placement:, rewardName:, rewardValue:)with the reward name and value.

If you'd like, we can send server-to-server calls when ads are completed. Contact your account manager at HyprMX for more details.

That's it! You're up and running with the latest version of the HyprMX SDK.