HyprMX Mobile SDK AdMob Adapter Overview

Introduction

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

Upgrade Instructions 5.0+ to 5.4.5.0

NOTE: This adapter no longer supports the AdMob Rewarded Video Ads (Legacy API). If you are using this Rewarded Video API, please update per the AdMob Rewarded Ads Guide.

CocoaPods Integration

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

pod 'HyprMX-AdMob', '5.4.5.0'

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

Please refer to AdMob's Release Notes for the required minimum CocoaPods version required by the Google-Mobile-Ads-SDK Pod.

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.

  • Add the HyprMX.xcframework to the project. Make sure to copy and verify target membership.

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

  • Add the AdMob-Adapter folder to the project. Make sure to copy and verify target membership.

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

  • Add or confirm that info.plist contains the required Privacy Keys. For more information, see the Configuring Privacy Controls section below.

  • Optional: Set user consent, as shown below.

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.

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

Initial Setup Instructions

This guide assumes you already have the AdMob iOS SDK integrated into your Xcode project.

CocoaPods Integration

  • Install / update CocoaPods to version 1.9.3 or newer.

  • Add the following to your Podfile:

pod 'HyprMX-AdMob', '5.4.5.0'

Manual Integration

Add HyprMX SDK to your Xcode Project

  • Add the HyprMX.xcframework to the project. Make sure to copy and verify target membership. Set the HyprMX.xcframework to Embed and Sign.

  • Add the AdMob-Adapter folder to the project. Make sure to copy and verify target membership.

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

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 AdMob Dashboard Using Custom Events

  1. Create your Mediation Group on the AdMob Dashboard.

  2. In the Ad Sources, select Add Custom Event.

  3. In the popup, enter a unique label such as "HyprMX Placement1" in the label field and set the default eCPM (e.g. $15.00).

  4. Click Continue.

  5. Set the adapter classname:

    AdMob Ad Format

    Class Name

    Rewarded Ads (New API)

    HYPRAdMobRewardedAdapter

    Interstitial

    HYPRAdMobVideoAdapter

  6. In the parameter field, enter the distributor ID and placement name assigned to you by your HyprMX account manager.

    { "distributorID": "YOUR_DISTRIBUTOR_ID", "placementName": "HyprMX Placement1" }
  7. Click 'Done'.

Optional: User ID & User Consent

Define HyprMXAdNetworkExtras

We recommend you instantiate an instance of HyprMXAdNetworkExtras and store it as a property:

#import "HyprMXAdNetworkExtras.h"
@property (strong, nonatomic) HyprMXAdNetworkExtras *hyprMXExtras;
- (HyprMXAdNetworkExtras *)hyprMXExtras {
if (!_hyprMXExtras) {
_hyprMXExtras = [[HyprMXAdNetworkExtras alloc] init];
}
return _hyprMXExtras;
}

Add a User ID

If your app relies on server-to-server callbacks and requires you to set a static user ID that is publisher-defined for Rewarded Video, pass the user ID by registering a HyprMXAdNetworkExtras object to your GADRequest as shown below. Please contact your HyprMX account services representative if you would like to implement a postback.

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

_hyprMXExtras.userId = your_user_id;

Replace your_user_id with your user ID.

Add User Consent State

HyprMX allows you to set the user's consent status for jurisdictions that require passing consent using the +setConsentStatus: API. Options are CONSENT_STATUS_UNKNOWN, CONSENT_GIVEN, or CONSENT_DECLINED, depending on the user's consent collected by your application.

_hyprMXExtras.consentStatus = <HyprConsentStatus>;

Replace <HyprConsentStatus> with the appropriate consent state.

Rewarded Ads

For rewarded ad requests, register the hyprMXExtras property on your GADRequest:

GADRequest *request = [GADRequest request];
[request registerAdNetworkExtras:self.hyprMXExtras];

Interstitial Ads

For interstitial ad requests, you will need to instantiate a GADCustomEventExtras object and set a custom event extras dictionary using the method setExtras: forLabel:.

The HyprMXAdNetworkExtras object has a helper method customEventExtrasDictionary, to create the dictionary from your HyprMXAdNetworkExtras property.

The label argument should use the same label as the label you set for the Custom Event on the dashboard. setExtras: forLabel: will need to be called for each Interstitial Custom Event set in the dashboard.

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:[self.hyprExtras customEventExtrasDictionary] forLabel:@"HyprMX Placement1"];
[extras setExtras:[self.hyprExtras customEventExtrasDictionary] forLabel:@"HyprMX Placement2"];
[request registerAdNetworkExtras:extras];

License

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