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

Integrating the SDK

The following section details how to use the Android HyprMX SDK. This guide assumes you already have your Gradle-based project up and running in Android Studio.

1. Open your existing application in Android Studio.

2. Add the following repo to your top-level build.gradle dependencies:

allprojects {
    repositories {
        maven { url "https://hyprmx.jfrog.io/artifactory/hyprmx" }
    }
}

3. Add the HyprMX SDK to your app's build.gradle file dependencies block:

dependencies {
    implementation 'com.hyprmx.android:HyprMX-SDK:5.1.2'
}

4. Add Google Play Services Ads Identifier (recommended) to your app's build.gradle file dependencies block:

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

5. If you are using Kotlin in your application, add the following to your build.gradle inside the android block:

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

AndroidManifest

Permissions

In order to maximize fill rates, we recommend adding the following permissions:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.VIBRATE" />

Usage

Initialization

First, add the following imports to your activity:

import com.hyprmx.android.sdk.core.HyprMX;
import com.hyprmx.android.sdk.core.HyprMXIf;
import com.hyprmx.android.sdk.core.HyprMXErrors;
import com.hyprmx.android.sdk.core.HyprMXState;
import com.hyprmx.android.sdk.placement.Placement;
import com.hyprmx.android.sdk.placement.PlacementListener;
import com.hyprmx.android.sdk.placement.RewardedPlacementListener; 

Initialize the HyprMX SDK in your main Activity inside the onCreate method as shown 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 ConsentStatus value (CONSENT_STATUS_UNKNOWN, CONSENT_GIVEN, or CONSENT_DECLINED) depending on the user consent collected by your app.

String distributorID = "Your Distributor ID";
String userID = "Your User's ID";
ConsentStatus consentStatus = ConsentStatus.CONSENT_STATUS_UNKNOWN; // If you don't have consent status for the user, set this to CONSENT_STATUS_UNKNOWN
HyprMXIf.HyprMXInitializationListener initializationListener;
HyprMX.INSTANCE.initialize(this, distributorID, userID, consentStatus, initializationListener);

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.

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, Android ID (AID), or Google Advertising ID (GAID). If you don’t already have a static user identifier, you can use the code below to generate one.

SharedPreferences sharedPreferences = getSharedPreferences("hyprmx_prefs", Context.MODE_PRIVATE);
String userID = sharedPreferences.getString("hyprUserId", null);
if (userID == null) {
    userID = UUID.randomUUID().toString();
    sharedPreferences.edit().putString("hyprUserId", userID).apply();
}

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

HyprMX.INSTANCE.setConsentStatus(consentStatus);

initializationListener

initalizationListener is the listener for Initialization Status of the SDK. It will callback to initializationComplete or initializationFailed as below:

HyprMXIf.HyprMXInitializationListener initializationListener = new HyprMXIf.HyprMXInitializationListener() {
    @Override
    public void initializationComplete() {}
​
    @Override
    public void initializationFailed() {}
};

Check Ad Availability

Once initlistener.initializationComplete() is called, you can start checking for ad availability. Placements are objects that allow you to show both rewarded and interstitial advertisements. To load an advertisement, get the placement from HyprMX, set a placementListener, and call loadAd().

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" placement for rewarded and an “INTERSTITIAL” placement for interstitial.

// interstitial placement
Placement interstitialPlacement = HyprMX.INSTANCE.getPlacement("INTERSTITIAL");
interstitialPlacement.setPlacementListener(placementListener).loadAd();
​
// rewarded placement
Placement rewardedPlacement = HyprMX.INSTANCE.getPlacement("REWARDED");
rewardedPlacement.setPlacementListener(rewardPlacementListener).loadAd();

For interstitial placement, implement PlacementListener:

PlacementListener placementListener = new PlacementListener() {
    @Override
    public void onAdStarted(Placement placement) {
        // Called when an ad is shown for the given placement.
    }
​
    @Override
    public void onAdClosed(Placement placement, boolean finished) {
        // Called when an ad is closed. Your application should resume here.
    }
​
    @Override
    public void onAdDisplayError(Placement placement, HyprMXErrors hyprMXError) {
        // Called when there was an error displaying the ad.
    }
​
    @Override
    public void onAdAvailable(Placement placement) {
        // Called when an ad is available for the given placement.
    }
​
    @Override
    public void onAdNotAvailable(Placement placement) {
        // Called when no ad is available for the given placement.
    }
​
	@Override
    public void onAdExpired(Placement placement) {
        // Called when an ad is no longer available for the given placement.
    }
};

For rewarded placement, implement RewardedPlacementListener. RewardedPlacementListener includes all the callbacks from PlacementListener and one additional callback as below:

RewardedPlacementListener rewardedPlacementListener = new RewardedPlacementListener() {
​
    ... // same callbacks from PlacementListener
​
    @Override
    public void onAdRewarded(Placement placement, String rewardName, int rewardValue) {
        // Called when the user should be rewarded for the given rewarded placement.
    }
};

Display Ad

Once you've received the onAdAvailable callback on the placement, you can show the ad as follows:

// interstitial placement
if (interstitialPlacement.isAdAvailable()) {
    interstitialPlacement.showAd();
}
​
// rewarded placement
if (rewardedPlacement.isAdAvailable()) {
    rewardedPlacement.showAd();
}

NOTE: When an ad is displaying, it is important to disable all in-game music and sounds so they do not interfere with the advertisements.

The placement will call onAdStarted() immediately before attempting to show an ad, and call onAdClosed() when the ad is closed. If there is no ad to display or an error occurs during the presentation, onAdDisplayError() will be called with an error description, then onAdClosed() will be called.

When a user successfully completes a rewarded advertisement you will receive a callback to onAdRewarded() with the reward name and value.

Server to server callbacks

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

License

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