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

Unity SDK Requirements

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

---

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#1.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 Offerwall 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 Offerwall Callbacks

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

var callback = AdGem.OfferwallCallback;

callback.OnLoadingStarted.AddListener(() =>
{
    // Notifies that the Offerwall loading has started
});
callback.OnLoadingFinished.AddListener(() =>
{
    // Notifies that the Offerwall has been loaded.
});
callback.OnLoadingFailed.AddListener(error =>
{
    // Notifies that the Offerwall 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 Offerwall was closed.
});

Once registered, a callback will be used to deliver Offerwall 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	255 characters (enforced — see below)
Forbidden	Emojis, special characters, uppercase letters

Keep player IDs at 255 characters or fewer

255 characters is the limit to build against. It is enforced, not advisory: a longer player ID is rejected with a validation error and the request returns no data.

Some endpoints accept up to 500 characters, but 255 is the only length that works everywhere in AdGem. Building to 500 means an ID that succeeds on a tracking click and then fails on offer retrieval or player support, so treat 255 as the contract.

If your internal identifiers can exceed 255 characters — long opaque tokens and concatenated composite keys are the usual culprits — map them to a shorter stable identifier before sending them to AdGem. The value only has to be unique and constant per player; it does not have to be your internal primary key. A hash of your internal ID is a good fit: stable and short. Note that a hash is one-way, so keep a lookup table on your side if you need to map back to the internal ID.

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, such as age, gender, placement, and custom fields.

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 server postback to your server. See Postbacks to learn more.