Unity SDK 2

What you need

To use the Metica Unity SDK you need:

• An API key, obtainable in the Metica platform

• An appId, obtainable in the Metica platform.

• A Max SDK Key, obtainable from Applovin platfom

Dependencies

Import the AppLovin Unity Plugin into your project by following the guide below.

Only the Import the AppLovin MAX Unity plugin step is required, the Metica SDK handles everything else. The minimum version of MAX plugin that Metica requires is 8.2.0.

MAX | SDK integration guides | Unity | Overview | Integration | Axon by AppLovin | Support CenterAxon by AppLovin | Support Center

Installation

In Unity, you need to import a custom package stored here:

GitHub - meticalabs/metica-unity-package: Repository for Unity PackageGitHub

Before installing any new Metica .unitypackage , please remove any old Metica versions from your Assets

In Unity Editor, click on Assets -> Import Package -> Custom Package and load the .unitypackage downloaded from our repository

Do not call, reference, or initialize the Max SDK library (AppLovin MAX) directly in your code. Metica’s SDK already packages and manages the Max SDK integration internally. If you attempt to use MaxSDK directly, you may cause version conflicts, duplicate initialization, and unexpected behaviour in Metica’s ad logic.

Initialization

Initialize the SDK using your credentials and mediation configuration.

In MeticaInitConfig API_KEY and APP_ID are mandatory, instead, if you don't provide a USER_ID (or you pass an empty string) the Metica SDK will generate a unique UUID per player for you.

In MeticaMediationInfo provide the Max SDK Key.

InitializeAsync returns a MeticaInitResponse object. This object provides two important pieces of information:

• SmartFloors.UserGroup – the experiment group assigned to the current player (holdout or trial).

• SmartFloors.IsSuccess– a boolean indicating whether initialization completed successfully.

  • If this is false, the player is automatically assigned to the holdout group.

  • This flag is provided solely for analytics and logging. You do not need to implement any fallback logic, the SDK already handles holdout assignment internally.

using Metica;
using Metica.Ads;
using UnityEngine;

public class MyGameManager : MonoBehaviour
{
    void Start()
    {
        InitializeMetica();
    }

    async void InitializeMetica()
    {
        var config = new MeticaInitConfig("YOUR_API_KEY", "YOUR_APP_ID", "user-id");
        var mediationInfo = new MeticaMediationInfo(MeticaMediationType.MAX, "YOUR_MAX_SDK_KEY");

        // Set privacy preferences before initialization
        MeticaSdk.Ads.SetHasUserConsent(true);
        MeticaSdk.Ads.SetDoNotSell(false);

        // Initialize SDK
        var initResponse = await MeticaSdk.InitializeAsync(config, mediationInfo);
        Debug.Log($"Current user is part of {initResponse.SmartFloors.UserGroup}");
        //When the initialization is not successful, the player will be excluded from Metica treatment
        // and it will receive the normal treatment.
        
        // This information is useful only for your analytics
        Debug.Log($"Metica initialization completed: {initResponse.SmartFloors.IsSuccess}");
        Debug.Log("Metica SDK initialized successfully");
        // Now you can load ads
    }
}

Ad implementation

The SDK supports Banner, MREC, Interstitial and Rewarded ads. All ad operations are accessed via MeticaSdk.Ads.

Banner Ads

Standard banner ads with auto-refresh functionality.

using Metica;
using Metica.Ads;
using UnityEngine;

public class BannerExample : MonoBehaviour
{
    private const string BannerAdUnitId = "YOUR_BANNER_AD_UNIT_ID";

    void Start()
    {
        // Subscribe to callbacks
        MeticaAdsCallbacks.Banner.OnAdLoadSuccess += OnBannerLoaded;
        MeticaAdsCallbacks.Banner.OnAdLoadFailed += OnBannerLoadFailed;
        MeticaAdsCallbacks.Banner.OnAdClicked += OnBannerClicked;
        MeticaAdsCallbacks.Banner.OnAdRevenuePaid += OnBannerRevenuePaid;

        // Create and show banner
        var config = new MeticaAdViewConfiguration(MeticaAdViewPosition.BottomCenter);
        MeticaSdk.Ads.CreateBanner(BannerAdUnitId, config);
        MeticaSdk.Ads.ShowBanner(BannerAdUnitId);
    }

    void OnApplicationFocus(bool hasFocus)
    {
        if (hasFocus)
        {
            MeticaSdk.Ads.ShowBanner(BannerAdUnitId);
        }
        else
        {
            MeticaSdk.Ads.HideBanner(BannerAdUnitId);
        }
    }

    private void OnBannerLoaded(MeticaAd ad)
    {
        Debug.Log($"Banner loaded: {ad.adUnitId}");
    }

    private void OnBannerLoadFailed(MeticaAdError error)
    {
        Debug.LogError($"Banner failed to load: {error.message}");
    }

    private void OnBannerClicked(MeticaAd ad)
    {
        Debug.Log($"Banner clicked: {ad.adUnitId}");
    }

    private void OnBannerRevenuePaid(MeticaAd ad)
    {
        Debug.Log($"Banner revenue: ${ad.revenue} from {ad.networkName}");
    }
}

Banner ads auto-refresh by default. To control refresh manually these are the methods available:

MeticaSdk.Ads.StopBannerAutoRefresh(BannerAdUnitId);  // Stop auto-refresh
MeticaSdk.Ads.LoadBanner(BannerAdUnitId);              // Manually load
MeticaSdk.Ads.StartBannerAutoRefresh(BannerAdUnitId); // Re-enable auto-refresh

MREC Ads (300x250)

Medium Rectangle ads work the same way as banners but with a larger size.

using Metica;
using Metica.Ads;
using UnityEngine;

public class MrecExample : MonoBehaviour
{
    private const string MrecAdUnitId = "YOUR_MREC_AD_UNIT_ID";

    void Start()
    {
        // Subscribe to callbacks
        MeticaAdsCallbacks.Mrec.OnAdLoadSuccess += OnMrecLoaded;
        MeticaAdsCallbacks.Mrec.OnAdLoadFailed += OnMrecLoadFailed;
        MeticaAdsCallbacks.Mrec.OnAdClicked += OnMrecClicked;
        MeticaAdsCallbacks.Mrec.OnAdRevenuePaid += OnMrecRevenuePaid;

        // Create and show MREC
        var config = new MeticaAdViewConfiguration(MeticaAdViewPosition.Centered);
        MeticaSdk.Ads.CreateMrec(MrecAdUnitId, config);
        MeticaSdk.Ads.ShowMrec(MrecAdUnitId);
    }

    void OnApplicationFocus(bool hasFocus)
    {
        if (hasFocus)
        {
            MeticaSdk.Ads.ShowMrec(MrecAdUnitId);
        }
        else
        {
            MeticaSdk.Ads.HideMrec(MrecAdUnitId);
        }
    }

    private void OnMrecLoaded(MeticaAd ad)
    {
        Debug.Log($"MREC loaded: {ad.adUnitId}");
    }

    private void OnMrecLoadFailed(MeticaAdError error)
    {
        Debug.LogError($"MREC failed to load: {error.message}");
    }

    private void OnMrecClicked(MeticaAd ad)
    {
        Debug.Log($"MREC clicked: {ad.adUnitId}");
    }

    private void OnMrecRevenuePaid(MeticaAd ad)
    {
        Debug.Log($"MREC revenue: ${ad.revenue} from {ad.networkName}");
    }
}

MREC ads also auto-refresh by default. Use the same refresh control methods as banners:

MeticaSdk.Ads.StopMrecAutoRefresh(MrecAdUnitId);
MeticaSdk.Ads.LoadMrec(MrecAdUnitId);
MeticaSdk.Ads.StartMrecAutoRefresh(MrecAdUnitId);

Interstitial Ads

Full-screen ads that are shown between content transitions.

ShowInterstitial accepts optional placementId and customData parameters for analytics tracking.

using Metica;
using Metica.Ads;
using UnityEngine;

public class InterstitialExample : MonoBehaviour
{
    private const string InterstitialAdUnitId = "YOUR_INTERSTITIAL_AD_UNIT_ID";
    private int interstitialRetryAttempt = 0;

    void Start()
    {
        // Subscribe to callbacks
        MeticaAdsCallbacks.Interstitial.OnAdLoadSuccess += OnInterstitialLoaded;
        MeticaAdsCallbacks.Interstitial.OnAdLoadFailed += OnInterstitialLoadFailed;
        MeticaAdsCallbacks.Interstitial.OnAdShowSuccess += OnInterstitialShown;
        MeticaAdsCallbacks.Interstitial.OnAdShowFailed += OnInterstitialShowFailed;
        MeticaAdsCallbacks.Interstitial.OnAdHidden += OnInterstitialHidden;
        MeticaAdsCallbacks.Interstitial.OnAdClicked += OnInterstitialClicked;
        MeticaAdsCallbacks.Interstitial.OnAdRevenuePaid += OnInterstitialRevenuePaid;

        // Load interstitial
        LoadInterstitial();
    }
    
    private void LoadInterstitial()
    {
        MeticaSdk.Ads.LoadInterstitial(InterstitialAdUnitId);
    }

    public void ShowInterstitial()
    {
        if (MeticaSdk.Ads.IsInterstitialReady(InterstitialAdUnitId))
        {
            MeticaSdk.Ads.ShowInterstitial(InterstitialAdUnitId, "main_menu", "level_complete");
        }
        else
        {
            Debug.LogWarning("Interstitial not ready yet");
        }
    }

    private void OnInterstitialLoaded(MeticaAd ad)
    {
        interstitialRetryAttempt = 0;
        Debug.Log($"Interstitial loaded: {ad.adUnitId}");
    }

    private void OnInterstitialLoadFailed(MeticaAdError error)
    {    
        interstitialRetryAttempt++;
        double delay = System.Math.Pow(2, System.Math.Min(6, interstitialRetryAttempt));
        Debug.LogWarning($"Load failed: {error.message}, retrying in {delay}s");
        Invoke(nameof(LoadInterstitial), (float)delay);
    }

    private void OnInterstitialShown(MeticaAd ad)
    {
        Debug.Log($"Interstitial shown: {ad.adUnitId}");
    }

    private void OnInterstitialShowFailed(MeticaAd ad, MeticaAdError error)
    {
        Debug.LogError($"Interstitial failed to show: {error.message}");
    }

    private void OnInterstitialHidden(MeticaAd ad)
    {
        Debug.Log($"Interstitial hidden: {ad.adUnitId}");
        // Reload for next time
        LoadInterstitial();
    }

    private void OnInterstitialClicked(MeticaAd ad)
    {
        Debug.Log($"Interstitial clicked: {ad.adUnitId}");
    }

    private void OnInterstitialRevenuePaid(MeticaAd ad)
    {
        Debug.Log($"Interstitial revenue: ${ad.revenue} from {ad.networkName}");
    }
}

Rewarded Ads

Reward users for watching video ads.

ShowRewarded accepts optional placementId and customData parameters for analytics tracking.

using Metica;
using Metica.Ads;
using UnityEngine;

public class RewardedExample : MonoBehaviour
{
    private const string RewardedAdUnitId = "YOUR_REWARDED_AD_UNIT_ID";
    private int rewardedRetryAttempt = 0;

    void Start()
    {
        // Subscribe to callbacks
        MeticaAdsCallbacks.Rewarded.OnAdLoadSuccess += OnRewardedLoaded;
        MeticaAdsCallbacks.Rewarded.OnAdLoadFailed += OnRewardedLoadFailed;
        MeticaAdsCallbacks.Rewarded.OnAdShowSuccess += OnRewardedShown;
        MeticaAdsCallbacks.Rewarded.OnAdShowFailed += OnRewardedShowFailed;
        MeticaAdsCallbacks.Rewarded.OnAdHidden += OnRewardedHidden;
        MeticaAdsCallbacks.Rewarded.OnAdClicked += OnRewardedClicked;
        MeticaAdsCallbacks.Rewarded.OnAdRewarded += OnUserRewarded;
        MeticaAdsCallbacks.Rewarded.OnAdRevenuePaid += OnRewardedRevenuePaid;

        // Load rewarded ad
        LoadRewarded();
    }
    
    private void LoadRewarded()
    {
        MeticaSdk.Ads.LoadRewarded(RewardedAdUnitId);
    }

    public void ShowRewardedAd()
    {
        if (MeticaSdk.Ads.IsRewardedReady(RewardedAdUnitId))
        {
            MeticaSdk.Ads.ShowRewarded(RewardedAdUnitId, "shop", "extra_coins");
        }
        else
        {
            Debug.LogWarning("Rewarded ad not ready yet");
        }
    }

    private void OnRewardedLoaded(MeticaAd ad)
    {
        rewardedRetryAttempt = 0;
        Debug.Log($"Rewarded ad loaded: {ad.adUnitId}");
    }

    private void OnRewardedLoadFailed(MeticaAdError error)
    {
        rewardedRetryAttempt++;
        double delay = System.Math.Pow(2, System.Math.Min(6, rewardedRetryAttempt));
        Debug.LogWarning($"Rewarded failed: {error.message}, retrying in {delay}s");
        Invoke(nameof(LoadRewarded), (float)delay);
    }

    private void OnRewardedShown(MeticaAd ad)
    {
        Debug.Log($"Rewarded ad shown: {ad.adUnitId}");
    }

    private void OnRewardedShowFailed(MeticaAd ad, MeticaAdError error)
    {
        Debug.LogError($"Rewarded ad failed to show: {error.message}");
    }

    private void OnRewardedHidden(MeticaAd ad)
    {
        Debug.Log($"Rewarded ad hidden: {ad.adUnitId}");
        // Reload for next time
        LoadRewarded();
    }

    private void OnRewardedClicked(MeticaAd ad)
    {
        Debug.Log($"Rewarded ad clicked: {ad.adUnitId}");
    }

    private void OnUserRewarded(MeticaAd ad)
    {
        Debug.Log($"User earned reward from: {ad.adUnitId}");
        // Grant reward to user here
        GrantRewardToUser();
    }

    private void OnRewardedRevenuePaid(MeticaAd ad)
    {
        Debug.Log($"Rewarded ad revenue: ${ad.revenue} from {ad.networkName}");
    }

    private void GrantRewardToUser()
    {
        // Your reward logic here
        Debug.Log("Granting reward to user!");
    }
}

Advanced Features

Privacy Compliance

Configure GDPR and CCPA settings before initialization.

// GDPR - Set user consent status
MeticaSdk.Ads.SetHasUserConsent(true);

// CCPA - Set do-not-sell flag
MeticaSdk.Ads.SetDoNotSell(false);

Revenue Tracking

All ad formats provide revenue callbacks through the OnAdRevenuePaid event. The MeticaAd object contains revenue information:

MeticaAdsCallbacks.Banner.OnAdRevenuePaid += (ad) =>
{
    Debug.Log($"Revenue: ${ad.revenue:F4}");
    Debug.Log($"Network: {ad.networkName}");
    Debug.Log($"Ad Unit: {ad.adUnitId}");

    // Track revenue in your analytics
    TrackRevenue(ad.revenue, ad.networkName);
};

AppLovin MAX Functions

The SDK provides utility functions for AppLovin MAX consent management:

// Check if user has consented
bool hasConsent = MeticaSdk.Ads.Max.HasUserConsent();

// Check if consent was explicitly set
bool isConsentSet = MeticaSdk.Ads.Max.IsUserConsentSet();

// Get user's geography for consent flow
var geography = MeticaSdk.Ads.Max.GetConsentFlowUserGeography();

Debugging

To enable debug log call MeticaSdk.SetLogEnabled(true); before initialization.

API Reference

MeticaSdk Methods

Initialization & Configuration

Method	Return Type	Description
InitializeAsync(MeticaInitConfig, MeticaMediationInfo)	Task<MeticaInitResponse>	Initializes the SDK.
SetLogEnabled(bool)	void	Enables/disables debug logging (default: false).

MeticaSdk.Ads Methods

Privacy

Method	Description
SetHasUserConsent(bool)	Sets GDPR consent status. Call before initialization.
SetDoNotSell(bool)	Sets CCPA do-not-sell flag. Call before initialization.

Banner Methods

Method	Description
CreateBanner(string adUnitId, MeticaAdViewConfiguration config)	Creates a banner ad view.
ShowBanner(string adUnitId)	Shows a banner ad.
HideBanner(string adUnitId)	Hides a banner ad.
LoadBanner(string adUnitId)	Manually loads a banner ad (only when auto-refresh is disabled).
StartBannerAutoRefresh(string adUnitId)	Starts automatic banner refresh.
StopBannerAutoRefresh(string adUnitId)	Stops automatic banner refresh.
DestroyBanner(string adUnitId)	Destroys a banner ad view.

MREC Methods

Method	Description
CreateMrec(string adUnitId, MeticaAdViewConfiguration config)	Creates an MREC ad view.
ShowMrec(string adUnitId)	Shows an MREC ad.
HideMrec(string adUnitId)	Hides an MREC ad.
LoadMrec(string adUnitId)	Manually loads an MREC ad (only when auto-refresh is disabled).
StartMrecAutoRefresh(string adUnitId)	Starts automatic MREC refresh.
StopMrecAutoRefresh(string adUnitId)	Stops automatic MREC refresh.
DestroyMrec(string adUnitId)	Destroys an MREC ad view.

Interstitial Methods

Method	Return Type	Description
LoadInterstitial(string adUnitId)	void	Loads an interstitial ad.
ShowInterstitial(string adUnitId, string? placementId, string? customData)	void	Shows an interstitial ad with optional tracking parameters.
IsInterstitialReady(string adUnitId)	bool	Checks if interstitial is ready to show.

Rewarded Methods

Method	Return Type	Description
LoadRewarded(string adUnitId)	void	Loads a rewarded ad.
ShowRewarded(string adUnitId, string? placementId, string? customData)	void	Shows a rewarded ad with optional tracking parameters.
IsRewardedReady(string adUnitId)	bool	Checks if rewarded ad is ready to show.

MeticaSdk.Ads.Max Methods

Method	Return Type	Description
HasUserConsent()	bool	Returns whether user has consented.
IsUserConsentSet()	bool	Returns whether consent was explicitly set.
GetConsentFlowUserGeography()	MaxSdkBase.ConsentFlowUserGeography	Returns user's geography for consent flow.

MeticaAd Properties

Property	Type	Description
adUnitId	string	Ad unit identifier.
revenue	double?	Revenue generated by this ad impression (nullable).
networkName	string?	The ad network name (nullable).
placementTag	string?	Placement tag (nullable).
adFormat	string?	Ad format type (nullable).
creativeId	string?	Creative identifier (nullable).
latency	long?	Load latency in milliseconds (nullable).

MeticaAdError Properties

Property	Type	Description
message	string	Error message.
adUnitId	string?	Associated ad unit identifier (nullable).

MeticaAdViewPosition Enum

Position options for banner and MREC ads:

Value	Description
TopCenter	Top center of the screen.
Centered	Center of the screen.
BottomCenter	Bottom center of the screen.

MeticaMediationType Enum

Supported mediation platforms:

Value	Description
MAX	AppLovin MAX mediation platform.

MeticaAdsCallbacks Events

Banner Callbacks

Event	Type	Description
MeticaAdsCallbacks.Banner.OnAdLoadSuccess	Action<MeticaAd>	Banner ad loaded successfully.
MeticaAdsCallbacks.Banner.OnAdLoadFailed	Action<MeticaAdError>	Banner ad failed to load.
MeticaAdsCallbacks.Banner.OnAdClicked	Action<MeticaAd>	Banner ad was clicked.
MeticaAdsCallbacks.Banner.OnAdRevenuePaid	Action<MeticaAd>	Banner ad revenue was recorded.

MREC Callbacks

Event	Type	Description
MeticaAdsCallbacks.Mrec.OnAdLoadSuccess	Action<MeticaAd>	MREC ad loaded successfully.
MeticaAdsCallbacks.Mrec.OnAdLoadFailed	Action<MeticaAdError>	MREC ad failed to load.
MeticaAdsCallbacks.Mrec.OnAdClicked	Action<MeticaAd>	MREC ad was clicked.
MeticaAdsCallbacks.Mrec.OnAdRevenuePaid	Action<MeticaAd>	MREC ad revenue was recorded.

Interstitial Callbacks

Event	Type	Description
MeticaAdsCallbacks.Interstitial.OnAdLoadSuccess	Action<MeticaAd>	Interstitial ad loaded successfully.
MeticaAdsCallbacks.Interstitial.OnAdLoadFailed	Action<MeticaAdError>	Interstitial ad failed to load.
MeticaAdsCallbacks.Interstitial.OnAdShowSuccess	Action<MeticaAd>	Interstitial ad displayed successfully.
MeticaAdsCallbacks.Interstitial.OnAdShowFailed	Action<MeticaAd, MeticaAdError>	Interstitial ad failed to display.
MeticaAdsCallbacks.Interstitial.OnAdHidden	Action<MeticaAd>	Interstitial ad was dismissed.
MeticaAdsCallbacks.Interstitial.OnAdClicked	Action<MeticaAd>	Interstitial ad was clicked.
MeticaAdsCallbacks.Interstitial.OnAdRevenuePaid	Action<MeticaAd>	Interstitial ad revenue was recorded.

Rewarded Callbacks

Event	Type	Description
MeticaAdsCallbacks.Rewarded.OnAdLoadSuccess	Action<MeticaAd>	Rewarded ad loaded successfully.
MeticaAdsCallbacks.Rewarded.OnAdLoadFailed	Action<MeticaAdError>	Rewarded ad failed to load.
MeticaAdsCallbacks.Rewarded.OnAdShowSuccess	Action<MeticaAd>	Rewarded ad displayed successfully.
MeticaAdsCallbacks.Rewarded.OnAdShowFailed	Action<MeticaAd, MeticaAdError>	Rewarded ad failed to display.
MeticaAdsCallbacks.Rewarded.OnAdHidden	Action<MeticaAd>	Rewarded ad was dismissed.
MeticaAdsCallbacks.Rewarded.OnAdClicked	Action<MeticaAd>	Rewarded ad was clicked.
MeticaAdsCallbacks.Rewarded.OnAdRewarded	Action<MeticaAd>	User earned the reward.
MeticaAdsCallbacks.Rewarded.OnAdRevenuePaid	Action<MeticaAd>	Rewarded ad revenue was recorded.

Troubleshooting

Max SDK Conflict

The Metica Unity SDK already includes and manages the AppLovin MAX integration internally. Do not reference, call, or initialize MaxSdk or subscribe to MAX callbacks directly in your code, this includes any callbacks related to:

• SDK initialization

• Banner

• MREC

• Interstitial

• Rewarded

Direct usage of MAX APIs or subscribing to MAX events can cause version conflicts, duplicate initialization, callback collisions, or unexpected behavior. Instead, rely on the callbacks exposed by the Metica SDK for all ad lifecycle events.

Moloco SDK Version

Moloco’s libraries (SDK and adapters) must be kept up to date to avoid dependency and build issues when used alongside Metica’s mediation setup.

• Ensure the Moloco SDK and its adapters are at least version 4.3.0 or above.

Older Moloco versions may lead to dependency resolution issues and incompatibilities with other mediation components.