# Getting Started

## Overview <a href="#overview" id="overview"></a>

Welcome to HyprMX! This guide will walk you through the essential steps to integrate the HyprMX SDK into your app.

Click the links below for step-by-step setup instructions for your platform.

* [Android](/sdk-integration-guides/android-amazon)
* [iOS](/sdk-integration-guides/ios)
* [Unity](/sdk-integration-guides/unity)

Before you begin, make sure you’ve received your **Distributor ID** and **Placement Name** from the HyprMX team. If you don’t have them yet, reach out to your account manager!

## Need Help? <a href="#need-help" id="need-help"></a>

If you have any questions, your HyprMX account manager is just a message away!


# Android / Amazon

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

## SDK Integration <a href="#quickstart-integratingthesdk" id="quickstart-integratingthesdk"></a>

You can integrate the HyprMX SDK through [Gradle](https://gradle.org/) dependencies. Follow the steps below to set up the SDK.&#x20;

{% hint style="info" %}
This guide assumes you already have your Gradle-based project up and running in Android Studio.
{% endhint %}

{% hint style="info" %}
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](/sdk-integration-guides/android-amazon/migrate-to-version-6.4+).
{% endhint %}

{% stepper %}
{% step %}
Open your existing application in Android Studio.
{% endstep %}

{% step %}
Add the HyprMX SDK to your app's `build.gradle` file dependencies block:

```gradle
dependencies {
    implementation 'com.hyprmx.android:HyprMX-SDK:6.4.6'
}
```

{% endstep %}

{% step %}
[Adding Google Play Services Ads Identifier](https://developers.google.com/android/guides/setup#list-dependencies) is optional. If the dependency below is included, it is the app developer's responsibility to ensure compliance with all Google Play policies, including, but not limited to, the [Families Program](https://play.google.com/console/about/families/).

```gradle
dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}
```

{% endstep %}

{% step %}
If you are using Kotlin in your application, add the following to your `build.gradle` inside the `android` block:

```kts
kotlinOptions {
  jvmTarget = "1.8"
  freeCompilerArgs = [
      "-Xjvm-default=compatibility",
  ]
}
```

{% endstep %}
{% endstepper %}

## Initializing HyprMX <a href="#quickstart-usage" id="quickstart-usage"></a>

After you have integrated the SDK, proceed to initialize the HyprMX SDK. To initialize, follow the steps below.

{% stepper %}
{% step %}
Add the following imports to your activity, or auto-import them as you move forward with your integration:

{% tabs %}
{% tab title="Java" %}

```java
import com.hyprmx.android.sdk.core.HyprMX;
import com.hyprmx.android.sdk.core.HyprMXErrors;
import com.hyprmx.android.sdk.core.HyprMXIf;
import com.hyprmx.android.sdk.core.InitResult;
import com.hyprmx.android.sdk.placement.HyprMXPlacementExpiryListener;
import com.hyprmx.android.sdk.placement.HyprMXRewardedShowListener;
import com.hyprmx.android.sdk.placement.HyprMXShowListener;
import com.hyprmx.android.sdk.placement.Placement;
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
import com.hyprmx.android.sdk.core.HyprMX
import com.hyprmx.android.sdk.core.HyprMXErrors
import com.hyprmx.android.sdk.placement.HyprMXPlacementExpiryListener
import com.hyprmx.android.sdk.placement.HyprMXRewardedShowListener
import com.hyprmx.android.sdk.placement.HyprMXShowListener
import com.hyprmx.android.sdk.placement.Placement
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
Initialize the HyprMX SDK in your main `Activity` inside the `onCreate` method as shown below.&#x20;

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

Review the details of initialization parameters, [context](#context-required) and [distributorID](#distributorid-required).

{% tabs %}
{% tab title="Java" %}

```java
private HyprMXIf.HyprMXInitializationListener initializationListener = this;
HyprMX.INSTANCE.initialize(this, DISTRIBUTOR_ID, initializationListener);

// or
HyprMX.INSTANCE.initialize(this, DISTRIBUTOR_ID, initResult -> {
   // do something
});
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val initializationListener: HyprMXIf.HyprMXInitializationListener = this
HyprMX.initialize(this, DISTRIBUTOR_ID, initializationListener)

// or
HyprMX.initialize(this@MainActivity, DISTRIBUTOR_ID) { (isSuccess, message) ->
  // do something
}

// or
HyprMX.initialize(this@MainActivity, DISTRIBUTOR_ID) { result ->
  // do something
}
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

#### **context (required)**

Your current `context` instance.

#### **distributorID (required)**

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

If you need to call HyprMx initializer inside a [suspending function](https://kotlinlang.org/docs/composing-suspending-functions.html) you can do as below:

```kotlin
val (initSuccess, _) = HyprMX.initialize(this@MainActivity, DISTRIBUTOR_ID)
```

### Initialization Callbacks

`initializationListener` is the listener for the Initialization Status of the SDK. It will callback to `onInitialized` as below:

{% tabs %}
{% tab title="Java" %}

```java
private HyprMXIf.HyprMXInitializationListener initializationListener = new HyprMXIf.HyprMXInitializationListener() {
  @Override
  public void onInitialized(@NonNull InitResult initResult) {
    if(initResult.isSuccess()) {
      // do something
    }

    if(initResult.getMessage() != null) {
       // an error was thrown, i.e., isSuccess() == false
    }
  }
};
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val initializationListener: HyprMXIf.HyprMXInitializationListener = object : HyprMXIf.HyprMXInitializationListener {
    override fun onInitialized(result: InitResult) {
      if(result.success) {
        // do something
      }
  
      if(!result.message.isNullOrEmpty()) {
         // an error was thrown, i.e., success == false
      }
    }
}
```

{% endtab %}
{% endtabs %}

After receiving the `onInitialized` callback, you are now ready to load and display ads in your application. See our [Rewarded Ads](/sdk-integration-guides/android-amazon/ad-formats/rewarded-ads), [Interstitial Ads](/sdk-integration-guides/android-amazon/ad-formats/interstitial-ads), and [Banner/MREC Ads](/sdk-integration-guides/android-amazon/ad-formats/banner-mrec-ads) guides to add these ad types to your app.

{% hint style="info" %}
You can convert these callbacks to lambda (Java) or use a [high-order function](https://kotlinlang.org/docs/lambdas.html#higher-order-functions) on Kotlin, as shown above in the [initialization](#sample-initializer) section.
{% endhint %}

## \[Optional] Passing Alternative Identifiers

{% hint style="danger" %}
Alternative/Extended IDs are supported in HyprMX SDK 6.4+.
{% endhint %}

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)](https://unifiedid.com/)
* [ID5](https://id5.io/)
* [LiveIntent ID](https://www.liveintent.com/identity-solutions/)

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

{% tabs %}
{% tab title="Java" %}

```java
public class EIDJson {
  public static final String EXTRA_USER_EIDS_KEY = "eids";

  public static final String UID2 =
    """
    {
        "uid2": [{
            "id": "testUID2Id"
        }]
    }
    """;

  public static final String ID5 =
    """
    {
        "id5": [{
            "id": "testID5id",
            "linkType": 1,
            "abTestingControlGroup": true
        }]
    }
    """;

  public static final String LIVE_INTENT =
    """
    {
        "liveintent": [{
            "id": "testLiveintentId",
            "atype": 1
        }]
    }
    """;
}

private void setExtentedID(@NonNull String value) {
  String eidData = null;
  try {
    // Make sure that UID JSON content is a valid one
    eidData = new JSONObject(value).toString();
  } catch (Exception ex)  {
    Log.e(TAG, "Error validating EID JSON structure.");
  }

  HyprMX.INSTANCE.setUserExtras(EIDJson.EXTRA_USER_EIDS_KEY, eidData);
}

// Setting extends ID for UID2
setExtendedID(EIDJson.UID2);
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
object EIDJson {
    val EXTRA_USER_EIDS_KEY = "eids"

    val UID2 =
    """
    {
        "uid2": [{
            "id": "testUID2Id"
        }]
    }
    """

    val ID5 =
    """
    {
        "id5": [{
            "id": "testID5id",
            "linkType": 1,
            "abTestingControlGroup": true
        }]
    }
    """

    val LIVE_INTENT =
    """
    {
        "liveintent": [{
            "id": "testLiveintentId",
            "atype": 1
        }]
    }
    """
}

private fun setExtendedID(value: String) {
  // Make sure that UID JSON content is a valid one
  val eidData = try {
    JSONObject(value).toString()
  } catch (ex: Exception)  {
    Log.e(TAG, "Error validating EID JSON structure.")
  null
  }

  HyprMX.setUserExtras(EIDJson.EXTRA_USER_EIDS_KEY, eidData)
}

// Setting extends ID for UID2
setExtendedID(EIDJson.UID2)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For best results, set alternative/extended IDs before initializing HyprMX.
{% endhint %}

{% hint style="info" %}
Passing an empty string instead of json clears all alternative/extended IDs.
{% endhint %}

## Privacy Compliance

Please refer to our [Privacy](https://www.hyprmx.com/privacy-policy.html) page to learn more about your privacy compliance responsibilities and to implement the relevant privacy methods.

## License <a href="#quickstart-license" id="quickstart-license"></a>

By integrating the HyprMX SDK, you are agreeing to the [End User License Agreement](https://hyprmx.com/eula.html).


# iOS

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

{% hint style="info" %}
[Apple Privacy Manifest](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files) is included in iOS SDK 6.3.0.1+
{% endhint %}

## SDK Integration <a href="#quickstart-sdkintegration" id="quickstart-sdkintegration"></a>

The SDK can be integrated using [CocoaPods](#quickstart-cocoapods) or by [Manual Installation](#manual-installation).

{% hint style="info" %}
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](/sdk-integration-guides/ios/migrate-to-version-6.4+).
{% endhint %}

### Swift Package Manager

Swift Package Manager is a dependency manager for Swift and Objective-C Cocoa projects. To integrate the HyprMX SDK with Swift Package Manager, follow the steps below.

{% stepper %}
{% step %}
From XCode's menu bar, navigate to File / Add Package Dependencies...
{% endstep %}

{% step %}
Place the following text into the search bar located in the upper right of the dialog.

```
git@github.com:JunGroupProductions/HyprMX-SDK-SPM.git
```

{% endstep %}

{% step %}
Select the "Exact Version" option for the Dependency Rule and use the following version:

```
6.4.6
```

{% endstep %}

{% step %}
Click the "Add Package" button.
{% endstep %}
{% endstepper %}

### CocoaPods <a href="#quickstart-cocoapods" id="quickstart-cocoapods"></a>

[CocoaPods](https://cocoapods.org/) is a dependency manager for Swift and Objective-C Cocoa projects. To integrate the HyprMX SDK with CocoaPods, add the following to your Podfile:

<pre class="language-bash"><code class="lang-bash"><strong>pod 'HyprMX', '6.4.6'
</strong></code></pre>

Note: HyprMX 6.0.0+ supports Cocoapods 1.10+

{% hint style="danger" %}
We cannot distribute new SDKs via CocoaPods [starting in December 2026](https://dev.to/surhidamatya/cocoapods-is-going-read-only-what-ios-developers-need-to-know-19j8).
{% endhint %}

### Manual Installation

To manually install the framework, follow the steps below.

{% stepper %}
{% step %}
Download the SDK here and unzip the file.
{% endstep %}

{% step %}
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.

<figure><img src="/files/9jIaWJbt6IUOAq8M3PDt" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
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.

{% endstep %}

{% step %}
Set the Embed setting to "Embed & Sign".

<figure><img src="/files/ZN7mrMJYIZ40pCSqEY1W" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Xcode Project Setup

### Application Transport Security <a href="#quickstart-applicationtransportsecurityats" id="quickstart-applicationtransportsecurityats"></a>

We recommend that [ATS](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW60) (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.

```markup
<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.

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

### Configuring Privacy Controls <a href="#quickstart-configuringprivacycontrols" id="quickstart-configuringprivacycontrols"></a>

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.

```markup
<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 <a href="#quickstart-skadnetworkidentifier" id="quickstart-skadnetworkidentifier"></a>

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

```markup
<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](https://developer.apple.com/documentation/storekit/skadnetwork).

### 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:

{% tabs %}
{% tab title="Swift" %}

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

{% endtab %}

{% tab title="Objective-C" %}

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

{% endtab %}
{% endtabs %}

*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:*

{% tabs %}
{% tab title="Swift" %}

```swift
public override var supportedInterfaceOrientations: UIInterfaceOrientationMask {
    return .landscape
}

public override var preferredInterfaceOrientationForPresentation: UIInterfaceOrientation {
    return .landscapeLeft
}
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
- (UIInterfaceOrientationMask)supportedInterfaceOrientations {
    return UIInterfaceOrientationMaskLandscape;
}

- (UIInterfaceOrientation)preferredInterfaceOrientationForPresentation {
    return UIInterfaceOrientationLandscapeLeft;
}
```

{% endtab %}
{% endtabs %}

## Importing the SDK <a href="#quickstart-initializinghyprmx" id="quickstart-initializinghyprmx"></a>

To import the HyprMX Mobile SDK into your Application:

{% tabs %}
{% tab title="Swift" %}

```swift
import HyprMX
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
@import HyprMX;
```

{% endtab %}
{% endtabs %}

## Initializing HyprMX <a href="#quickstart-initializinghyprmx" id="quickstart-initializinghyprmx"></a>

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.&#x20;

### **Initialization API**

#### **Sample Initializer**&#x20;

{% tabs %}
{% tab title="Swift" %}

```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
}
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
- (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;
}
```

{% endtab %}
{% endtabs %}

#### **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 Initialization

After receiving the `initializationDidComplete` message, you are now ready to load and display ads in your application. See our [Rewarded Ads](/sdk-integration-guides/ios/ad-formats/rewarded-ads), [Interstitial Ads](/sdk-integration-guides/ios/ad-formats/interstitial-ads), and [Banner/MREC Ads](/sdk-integration-guides/ios/ad-formats/banner-mrec-ads) guides to add these ad types to your application.

## \[Optional] Passing Alternative Identifiers

{% hint style="danger" %}
Alternative/Extended IDs are supported in HyprMX SDK 6.4+.
{% endhint %}

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)](https://unifiedid.com/)
* [ID5](https://id5.io/)
* [LiveIntent ID](https://www.liveintent.com/identity-solutions/)

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

{% tabs %}
{% tab title="Swift" %}

```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")
}
```

{% endtab %}

{% tab title="Objective C" %}

```objectivec
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"];
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For best results, set alternative/extended IDs before initializing HyprMX.
{% endhint %}

{% hint style="info" %}
Passing an empty string instead of json clears all alternative/extended IDs.
{% endhint %}

## Privacy Compliance

Please refer to our [Privacy](broken://pages/qo15izO4kikKMzTBxNsr) page to learn more about your privacy compliance responsibilities and to implement the relevant privacy methods.

## License <a href="#quickstart-license" id="quickstart-license"></a>

By integrating the HyprMX SDK, you are agreeing to the [End User License Agreement](https://hyprmx.com/eula.html).


# Unity

The articles in this section are for publishers interested in using Unity adapters to serve ads from third-party mediators to support an increase in revenue and fill rate.

### Choosing Your Mediation Networks <a href="#mediation-networks" id="mediation-networks"></a>

Please select your mediator from below.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th></tr></thead><tbody><tr><td><strong>AdMob Mediation</strong></td><td><a href="/pages/ck12gaj8Frc7ZNYVr7Pj">/pages/ck12gaj8Frc7ZNYVr7Pj</a></td><td></td><td></td></tr><tr><td><strong>AppLovin MAX</strong></td><td><a href="/pages/8knJI3fCKE7oxeZ4c5Ip">/pages/8knJI3fCKE7oxeZ4c5Ip</a></td><td></td><td></td></tr><tr><td><strong>Chartboost Mediation</strong></td><td><a href="/pages/TbOW5NE8G3ZhaPpUt52F">/pages/TbOW5NE8G3ZhaPpUt52F</a></td><td></td><td></td></tr><tr><td><strong>Digital Turbine FairBid</strong></td><td><a href="/pages/VP3U0IFfYyqBbc78XxU0">/pages/VP3U0IFfYyqBbc78XxU0</a></td><td></td><td></td></tr><tr><td><strong>Unity LevelPlay</strong></td><td><a href="/pages/MEeSIzW1k7Xi9EHl1Gmv">/pages/MEeSIzW1k7Xi9EHl1Gmv</a></td><td></td><td></td></tr><tr><td><strong>X3M XMediator</strong></td><td><a href="/pages/hXZzVlCRdObRVRv2a1QA">/pages/hXZzVlCRdObRVRv2a1QA</a></td><td></td><td></td></tr></tbody></table>