Unity SDK 2.x

GitHub - meticalabs/metica-unity-sdkGitHub

🚧 v2.x — Release Candidate (Beta) Status: Beta / Release Candidate — feature-complete and intended to be the next production line, but still in beta. Safe for early adopters and testing. APIs may change before GA. Use in production only if you can accept possible, limited API changes.

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.

Installation

In Unity, open the Package Manager (Window > Package Manager) and click on the '+' button in the top left corner. Select "Add package from git URL..." and enter the following:

https://github.com/meticalabs/metica-unity-sdk.git

Do not call, reference, or initialize the MaxSDK library (AppLovin MAX) directly in your code. Metica’s SDK already packages and manages the MaxSDK 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.

using System.Threading.Tasks;
using Metica;
using Metica.Ads;
using UnityEngine;


public class MeticaBootstrap : MonoBehaviour
{
    async void Start()
    {
        MeticaSdk.Ads.SetHasUserConsent(true);
        MeticaSdk.Ads.SetDoNotSell(false);
        
        // MeticaSdk.SetLogEnabled(true); Enable for debugging
        
	var config = new MeticaInitConfig(<API_KEY>, <APP_ID>, <USER_ID>); // if USER_ID is an empty string the SDK will generate a UUID for you
        var mediationInfo = new MeticaMediationInfo(MeticaMediationInfo.MeticaMediationType.MAX, <MAX_SDK_KEY>);
        await Initialize(config, mediationInfo);
    }
}

Ad implementation

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

During initialization the SDK returns SmartFloors allocation information, this value is provided for telemetry and debugging purposes so you can see how the server configured the client. You do not need to change your ad-loading code based on SmartFloors, the SDK handles ad selection and routing automatically.

Always pass explicit ad unit IDs to fullscreen ad calls (LoadInterstitial, ShowInterstitial, LoadRewarded, etc.). These ad unit IDs are used by the SDK for normal operation and as the client-side fallback if remote configuration or initialization is unavailable. If initialization fails or remote configuration is not returned, the SDK will fall back to the client-provided ad unit IDs, you do not need to write special-case logic for this in your app.

In short: you can (and should) log the SmartFloors response for analytics, but you don’t need to act on it. The SDK will manage ad behavior, selection and fallbacks for you.

    /// <summary>
    /// Complete initialization flow for MeticaAds
    /// This method demonstrates the proper order and setup required for ad functionality
    /// Call this method early in your app lifecycle, typically in Start() or Awake()
    /// </summary>
    public async Task Initialize(MeticaInitConfig config, MeticaMediationInfo mediationInfo)
    {
        var result = await MeticaSdk.InitializeAsync(config, mediationInfo);
        Debug.Log($"Current user is part of {result.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: {result.SmartFloors.IsSuccess}");
          
        InitializeBannerAds();
        InitializeInterstitialAds();
        InitializeRewardedAds();
    }

Banner Ads

private const string BannerAdUnitId = "your_banner_ad_unit_id";


private void InitializeBanner()
{
    MeticaAdsCallbacks.Banner.OnAdLoadSuccess += OnBannerLoaded;
    MeticaAdsCallbacks.Banner.OnAdLoadFailed += OnBannerLoadFailed;
    
    MeticaSdk.Ads.CreateBanner(BannerAdUnitId, MeticaBannerPosition.Bottom);
}


private void OnBannerLoaded(MeticaAd ad) => Debug.Log($"Banner loaded: {ad.adUnitId}");
private void OnBannerLoadFailed(MeticaAdError error) => Debug.LogError($"Banner failed: {error.message}");

Interstitial Ads

private const string InterstitialAdUnitId = "your_interstitial_ad_unit_id";
private int interstitialRetryAttempt = 0;


private void InitializeInterstitial()
{
    MeticaAdsCallbacks.Interstitial.OnAdLoadSuccess += OnInterstitialLoaded;
    MeticaAdsCallbacks.Interstitial.OnAdLoadFailed += OnInterstitialLoadFailed;
    MeticaAdsCallbacks.Interstitial.OnAdHidden += OnInterstitialHidden;
    
    LoadInterstitial();
}


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


private void ShowInterstitial()
{
    if (MeticaSdk.Ads.IsInterstitialReady(InterstitialAdUnitId))
    MeticaSdk.Ads.ShowInterstitial(InterstitialAdUnitId);
}


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 OnInterstitialHidden(MeticaAd ad)
{
    // Preload next ad
    LoadInterstitial();
}

Rewarded Ads

private const string RewardedAdUnitId = "your_rewarded_ad_unit_id";
private int rewardedRetryAttempt = 0;


private void InitializeRewarded()
{
    MeticaAdsCallbacks.Rewarded.OnAdLoadSuccess += OnRewardedLoaded;
    MeticaAdsCallbacks.Rewarded.OnAdLoadFailed += OnRewardedFailed;
    MeticaAdsCallbacks.Rewarded.OnAdRewarded += OnRewardEarned;
    
    LoadRewarded();
}


private void LoadRewarded()
{
    MeticaSdk.Ads.LoadRewarded(RewardedAdUnitId);
}


private void ShowRewarded()
{
    if (MeticaSdk.Ads.IsRewardedReady(RewardedAdUnitId))
    MeticaSdk.Ads.ShowRewarded(RewardedAdUnitId);
}


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


private void OnRewardedFailed(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 OnRewardEarned(MeticaAd ad)
{
    Debug.Log("User earned reward");
    // Grant reward logic here
}

Metica SDK - Ad Callbacks Documentation

The Metica Unity SDK provides a comprehensive set of callbacks to track the lifecycle of your ads. All callbacks are accessed through the static MeticaAdsCallbacks class, organized by ad format.

Banner Ads

  public static event Action<MeticaAd> OnAdLoadSuccess;        // Fired when a banner ad successfully loads and is ready to display
  public static event Action<MeticaAdError> OnAdLoadFailed;    // Fired when a banner ad fails to load, includes error details
  public static event Action<MeticaAd> OnAdClicked;            // Fired when a user clicks on the banner ad
  public static event Action<MeticaAd> OnAdRevenuePaid;        // Fired when the banner ad generates revenue (impression tracked)

Interstitial Ads

  public static event Action<MeticaAd> OnAdLoadSuccess;              // Fired when an interstitial ad successfully loads and is ready to show
  public static event Action<MeticaAdError> OnAdLoadFailed;          // Fired when an interstitial ad fails to load, includes error details
  public static event Action<MeticaAd> OnAdShowSuccess;              // Fired when an interstitial ad is successfully displayed to the user
  public static event Action<MeticaAd, MeticaAdError> OnAdShowFailed; // Fired when an interstitial ad fails to display, includes ad info and error details
  public static event Action<MeticaAd> OnAdHidden;                   // Fired when the user closes the interstitial ad
  public static event Action<MeticaAd> OnAdClicked;                  // Fired when a user clicks on the interstitial ad
  public static event Action<MeticaAd> OnAdRevenuePaid;              // Fired when the interstitial ad generates revenue

Rewarded Ads

  public static event Action<MeticaAd> OnAdLoadSuccess;              // Fired when a rewarded ad successfully loads and is ready to show
  public static event Action<MeticaAdError> OnAdLoadFailed;          // Fired when a rewarded ad fails to load, includes error details
  public static event Action<MeticaAd> OnAdShowSuccess;              // Fired when a rewarded ad is successfully displayed to the user
  public static event Action<MeticaAd, MeticaAdError> OnAdShowFailed; // Fired when a rewarded ad fails to display, includes ad info and error details
  public static event Action<MeticaAd> OnAdHidden;                   // Fired when the user closes the rewarded ad
  public static event Action<MeticaAd> OnAdClicked;                  // Fired when a user clicks on the rewarded ad
  public static event Action<MeticaAd> OnAdRewarded;                 // Fired when the user completes the rewarded ad and should receive their reward
  public static event Action<MeticaAd> OnAdRevenuePaid;              // Fired when the rewarded ad generates revenue

Key Points

• All callbacks include either a MeticaAd object (containing ad metadata) or MeticaAdError (containing error information)

• OnAdShowFailed callbacks receive both the ad and error as parameters

• Subscribe to callbacks before loading ads to ensure you don't miss any events