HyprMX Mobile SDK MoPub Adapter Overview

Introduction

HyprMX iOS MoPub Adapter allows you to integrate HyprMX in your MoPub rewarded and interstitial waterfalls.

This adapter is compatible with MoPub v5.13.1 and up.

Upgrade Instructions 5.0+ to 6.0.0.0

The HyprMX MoPub adapter requires MoPub version 5.13.1 or greater. Ensure the MoPub dependency has been updated in your project.

If you have installed MoPub using CocoaPods, you can update your Podfile to:

pod 'mopub-ios-sdk', '>= 5.13.1'

CocoaPods Integration

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

pod 'HyprMX-MoPub', '6.0.0.0'

The HyprMX-MoPub Pod requires CocoaPods version 1.10 or newer installed in your development environment.

Manual SDK Installation

Add HyprMX SDK to your Xcode Project

  • Remove HyprMX.framework and all HyprMX adapter files from your project.

  • Find your target's Build Phases tab and open Link Binary with Libraries. If it exists, remove HyprMX.framework from this list.

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

  • Find your target's General tab, open Frameworks, Libraries, and Embedded Content and set the HyprMX.xcframework to Embed & Sign.

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

iOS 14 Plist Updates

iOS 14 introduced the AppTrackingTransparency framework to allow users control over the use of their Advertising Identifier.

The HyprMX 5.4.0+ SDK requires the NSUserTrackingUsageDescription Plist Key to determine the authorization state.

<key>NSUserTrackingUsageDescription</key>
<string>${PRODUCT_NAME} would like to show you personalized ads</string>

The HyprMX 5.4.0+ SDK 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.

For more information, see the SKAdNetwork and Configuring Privacy Controls sections below.

Pre-Initialization

To enable Pre-Initialization of HyprMX, add the following to your MPMoPubConfiguration, before you initialize MoPub with the configuration object.

Swift
Objective-C
Swift
let configuration: MPMoPubConfiguration = MPMoPubConfiguration.init(adUnitIdForAppInitialization: "YOUR_AD_UNIT")
if let hyprMXAdapterConfigurationClass: MPAdapterConfiguration.Type = NSClassFromString("HyprMXAdapterConfiguration") as? MPAdapterConfiguration.Type {
configuration.additionalNetworks = [hyprMXAdapterConfigurationClass]
let hyprMXConfiguration: Dictionary = ["distributorId": "YOUR_DISTRIBUTOR_ID", "userId": "YOUR_USER_ID"];
configuration.mediatedNetworkConfigurations = ["HyprMXAdapterConfiguration": hyprMXConfiguration]
}
Objective-C
MPMoPubConfiguration *configuration = [[MPMoPubConfiguration alloc] initWithAdUnitIdForAppInitialization:@"YOUR_AD_UNIT"];
configuration.additionalNetworks = @[NSClassFromString(@"HyprMXAdapterConfiguration")];
NSDictionary *hyprMXConfiguration = @{@"distributorId": @"YOUR_DISTRIBUTOR_ID", @"userId": @"YOUR_USER_ID"};
configuration.mediatedNetworkConfigurations = @{@"HyprMXAdapterConfiguration" : hyprMXConfiguration}.mutableCopy;

Removed - HyprMXGlobalMediationSettings

The deprecated HyprMXGlobalMediationSettings have been removed from the adapter in this release. If your project used HyprMXGlobalMediationSettings to set a custom User ID, please remove the use of the HyprMXGlobalMediationSettings object, and set your user ID using the Pre-Initialization instructions above.

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

Initial Setup Instructions

CocoaPods Integration

  • Install / update CocoaPods to version 1.10.0 or newer.

  • Add the following to your Podfile:

pod 'HyprMX-MoPub', '6.0.0.0'

Manual Integration

Add HyprMX and Adapter to your Xcode Project

This guide assumes you already have the MoPub iOS SDK integrated into 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.

  • Set the HyprMX.xcframework to Embed & Sign.

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

App Transport Security

  • Ensure that your ATS (App Transport Security) settings are as described by MoPub.

Pre-Initialization + Optional User ID

To enable Pre-Initialization of HyprMX, add the following to your MPMoPubConfiguration, before you initialize MoPub with the configuration object.

You will need to provide your Distributor ID with the key 'distributorId' in your mediatedNetworkConfigurations.

Swift
Objective-C
Swift
let configuration: MPMoPubConfiguration = MPMoPubConfiguration.init(adUnitIdForAppInitialization: "YOUR_AD_UNIT")
if let hyprMXAdapterConfigurationClass: MPAdapterConfiguration.Type = NSClassFromString("HyprMXAdapterConfiguration") as? MPAdapterConfiguration.Type {
configuration.additionalNetworks = [hyprMXAdapterConfigurationClass]
let hyprMXConfiguration: Dictionary<String, String> = ["distributorId": "YOUR_DISTRIBUTOR_ID"];
configuration.mediatedNetworkConfigurations = ["HyprMXAdapterConfiguration": hyprMXConfiguration]
}
Objective-C
MPMoPubConfiguration *configuration = [[MPMoPubConfiguration alloc] initWithAdUnitIdForAppInitialization:@"YOUR_AD_UNIT"];
configuration.additionalNetworks = @[NSClassFromString(@"HyprMXAdapterConfiguration")];
NSDictionary *hyprMXConfiguration = @{@"distributorId": @"YOUR_DISTRIBUTOR_ID"};
configuration.mediatedNetworkConfigurations = @{@"HyprMXAdapterConfiguration" : hyprMXConfiguration}.mutableCopy;

If your app relies on server-to-server callbacks and requires you to set a static user ID that is publisher-defined, pass the user ID with the key 'userId' in your mediatedNetworkConfigurations.

Swift
Objective-C
Swift
let configuration: MPMoPubConfiguration = MPMoPubConfiguration.init(adUnitIdForAppInitialization: "YOUR_AD_UNIT")
if let hyprMXAdapterConfigurationClass: MPAdapterConfiguration.Type = NSClassFromString("HyprMXAdapterConfiguration") as? MPAdapterConfiguration.Type {
configuration.additionalNetworks = [hyprMXAdapterConfigurationClass]
let hyprMXConfiguration: Dictionary = ["distributorId": "YOUR_DISTRIBUTOR_ID", "userId": "YOUR_USER_ID"];
configuration.mediatedNetworkConfigurations = ["HyprMXAdapterConfiguration": hyprMXConfiguration]
}
Objective-C
MPMoPubConfiguration *configuration = [[MPMoPubConfiguration alloc] initWithAdUnitIdForAppInitialization:@"YOUR_AD_UNIT"];
configuration.additionalNetworks = @[NSClassFromString(@"HyprMXAdapterConfiguration")];
NSDictionary *hyprMXConfiguration = @{@"distributorId": @"YOUR_DISTRIBUTOR_ID", @"userId": @"YOUR_USER_ID"};
configuration.mediatedNetworkConfigurations = @{@"HyprMXAdapterConfiguration" : hyprMXConfiguration}.mutableCopy;

The userId is a unique identifier supplied by your application and must be static for each user across sessions. Your userId should not contain any personally identifiable information such as an email address, screen name, or Apple's Advertising Identifier (IDFA).

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>

Note: Photo Usage and the Photo Add Usage keys are required by the framework to ensure all rich media advertisements are supported.

SKAdNetwork Identifier

The HyprMX 5.4.0+ SDK 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.

Integrating HyprMX On The MoPub Dashboard Using Custom Events

You will create a custom native network campaign in the MoPub UI. When setting up your line item, select 'Network' for the 'Type' field and then select 'Custom Native Network' for the 'Network' field. Further instructions for adding a network account can be found here.

In the Custom Event Data section add the snippet below using the distributor ID and placement name assigned to you by your HyprMX account manager. :

{ "distributorID": "YOUR_DISTRIBUTOR_ID", "placementName": "REWARDED" }

For Rewarded Video, paste the following class name as the Custom Event Class:

HyprMXRewardedVideoCustomEvent

For Interstitial Video, paste the following class name as the Custom Event Class:

HyprMXInterstitialCustomEvent

For Banner Ads, paste the following class name as the Custom Event Class:

HyprMXBannerCustomEvent

License

By downloading this SDK, you are agreeing to the LICENSE included with the SDK zip.