Unity SDK Integration Guide

v1.6.14Unity 2020.3+

Requirements

Before You Begin

Account Requirements:

• You have an active AdGem Account
• You have added your App to your Account

App Approval:

• Your app has been approved in the AdGem system

Important

By default, your app will not have access to AdGem's offers until you complete the initial integration steps and your app is approved. Contact your dedicated Publisher Support Advocate with any questions about the approval process.

:::

Platform Requirements

iOS SDK Requirements

• iOS 15.8 or higher
• Swift 5 or Objective-C
• Xcode 11 or higher

Android SDK Requirements

• Android API level 28 (Android 9.0) or higher
• Target SDK 34 or higher
• Android Studio with Gradle support

Unity SDK Requirements

• Unity 2020.3 or higher
• iOS or Android build target configured
• For iOS: Xcode 11+
• For Android: Android Studio with Gradle

Web Offerwall Requirements

• Modern web browser with JavaScript enabled
• HTTPS-enabled website (recommended for production)
• Server-side postback endpoint

Platform Support

• Android: 9.0 and higher
• iOS: 15.0 and higher
• Unity: 2020 and higher

---

Integration

Step 0. Create an App Property in the AdGem Publisher Dashboard

Step 0: Create an App Property in AdGem

Before AdGem can populate offers, you need to create an App Property in the AdGem Dashboard.

1. Create a Publisher Account in the AdGem Publisher Dashboard
2. Register your App Property in Properties & Apps

Need Help?

Contact your dedicated Publisher Support Advocate if you have any questions about setting up your App Property.

Step 1. Install the AdGem Unity SDK

Install the AdGem Unity SDK package via the Unity Package Manager using a Git URL:

https://github.com/AdGem/adgem-sdk-unity-package.git#v1.6.14

In the Editor, you can access the Package Manager window through the Window > Package Manager menu.

External Dependencies

In order to resolve native Android/iOS dependencies of the AdGem Unity SDK, use the External Dependency Manager for Unity.

Step 2. Configure the AdGem SDK

Set your AdGem App ID from the AdGem publisher dashboard in Window > AdGem settings menu.

Step 3. Use the AdGem Class

All communication with the SDK happens via the AdGem class.

Use the AdGem class to show the Offer Wall in your project:

AdGem.ShowOfferwall()

note

There is no need to store an instance of AdGem globally. The SDK will cache its instance on the first call and will always return the same one for all subsequent calls to AdGem.

Step 4. Register the AdGem Offer Wall Callbacks

The AdGem SDK provides callbacks that notify when offer wall internal state changes. These may be registered through the instance of AdGem.OfferwallCallback.

var callback = AdGem.OfferwallCallback;

callback.OnLoadingStarted.AddListener(() =>
{
    // Notifies that the offer wall loading has started
});
callback.OnLoadingFinished.AddListener(() =>
{
    // Notifies that the offer wall has been loaded.
});
callback.OnLoadingFailed.AddListener(error =>
{
    // Notifies that the offer wall has failed to load.
});
callback.OnRewardReceived.AddListener(amount =>
{
    // Notifies that the user has completed an action and should be rewarded with a specified virtual currency amount.
});
callback.OnClosed.AddListener(() =>
{
    // Notifies that the offer wall was closed.
});

Once registered, a callback will be used to deliver offer wall updates.

Important

It is the caller's responsibility to unregister callbacks. For example, if callbacks were registered in MonoBehaviour's Start() then they must be unregistered in the corresponding OnDestroy() call.

public class AdGemDemoController : MonoBehaviour
{
    private void Start()
    {
        ...
        var callbackDelegate = AdGem.OfferwallCallback;
        callbackDelegate.OnLoadingStarted.AddListener(OnOfferwallLoadingStarted);
        callbackDelegate.OnLoadingFinished.AddListener(OnOfferwallLoadingFinished);
        callbackDelegate.OnLoadingFailed.AddListener(OnOfferwallLoadingFailed);
        callbackDelegate.OnRewardReceived.AddListener(OnOfferwallRewardReceived);
        callbackDelegate.OnClosed.AddListener(OnOfferwallClosed);
        ...
    }

    private void OnDestroy()
    {
        ...
        var callbackDelegate = AdGem.OfferwallCallback;
        callbackDelegate.OnLoadingStarted.RemoveListener(OnOfferwallLoadingStarted);
        callbackDelegate.OnLoadingFinished.RemoveListener(OnOfferwallLoadingFinished);
        callbackDelegate.OnLoadingFailed.RemoveListener(OnOfferwallLoadingFailed);
        callbackDelegate.OnRewardReceived.RemoveListener(OnOfferwallRewardReceived);
        callbackDelegate.OnClosed.RemoveListener(OnOfferwallClosed);
        ...
    }
}

Step 5. Set the Player ID

Setting the Player ID

IMPORTANT: The Player ID is Required

The player_id parameter must be set with a unique identifier for each user in your application. This identifies the player so that virtual currency can be attributed to their account via the postback request. The player ID must remain constant for each unique player to:

• Prevent players from completing an offer more than once
• Ensure players receive their rewards correctly

Missing Player ID

Tracking URL clicks that do not contain a player_id value will be redirected to a 404 error page.

Player ID Structure Requirements

Requirement	Details
Case	Letters must be lowercase
Characters	Alphanumeric characters, hyphens, and underscores only
Max Length	256 characters
Forbidden	Emojis, special characters, uppercase letters

Good Examples:

• abc-123-efg-456
• user_12345
• player-a1b2c3d4

Bad Examples:

• aBc-123-Efg-456 (contains uppercase)
• player@123! (contains special characters)
• user-😀 (contains emoji)

var metadata = new PlayerMetadata("playerID-123")
{
    gender = PlayerMetadata.Gender.MALE,
    age = Random.Range(12, 87),
    placement = Random.Range(1, 1195),
    createdAt = DateTime.Now,
    isPayer = true,
    iapTotalUsd = Random.Range(1.99f, 1267)
};

AdGem.SetPlayerMetaData(metadata);

---

Additional Information

Optional Parameters

note

All parameter names and their values are case-sensitive.

You can optimize your revenue potential by segmenting your users using the optional parameters available in the Unity SDK. Please visit Optional Parameters to learn more.

Debug Logging

You can enable verbose logging by setting the Is Debug flag to true in Window > AdGem settings menu. By default, verbose logging is disabled.

Postback Setup

If you have opted for a "Server Postback", on each successful offer completion by a user AdGem will send a GET request to your server. Please visit our guide on Server Postback Setup to learn more.

---

Updated on June 7, 2024