Skip to content

Unity SDK Integration Guide

Requirements

Before you Begin

  • You must have an active AdGem account
  • You must add your App to your account
  • The AdGem Unity SDK supports devices Android 9.0 and higher and iOS 15.0 and higher
  • The AdGem Unity SDK is compatible with apps built in Unity 2020 and higher
  • In order for your app to have access to AdGem's offers, you will need to ensure your app is approved in the AdGem system. App setup and approval instructions can be found HERE. Please reach out to your dedicated Publisher Support Advocate with any questions

Integration

Step 1. Install the AdGem Unity SDK

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

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

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

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 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 Offer Wall in your project:

AdGem.ShowOfferwall()

Please note there is no need to store instance of AdGem globally. The SDK will cache its instance on a 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 which 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.

Keep in mind that it is the caller’s responsibility to unregister callabcks. For example, if callbacks were registered in MonoBehavior's Start() then they must be unregistered in 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 (fthe unique identifier for a user)

You need to set the player_id (a unique id for your user) parameter for each of your individual users. 

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);

Optional Parameters

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.

Additional Options

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

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