Unity SDK 2
What you need
To use the Metica Unity SDK you need:
An
API key, obtainable in the Metica platformAn
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.1.0.
Supported Ad Formats
The Metica SDK supports the following ad formats:
Banner
Standard banner ads displayed at the top or bottom of the screen
MREC
Medium Rectangle ads (300x250)
Interstitial
Full-screen ads shown between content transitions
Rewarded
Video ads that reward users for watching
Unity 6 Android Build Configuration
No additional configuration is needed — Unity 6 ships with AGP 8.4.0+, Gradle 8.6+, and JDK 17 by default.
Unity 2022 Android Build Configuration
Unity 2022 ships with an older Android Gradle Plugin (AGP) and Gradle version that are incompatible with the Metica SDK's dependencies. To build for Android, you must upgrade these tools manually.
Prerequisites
JDK 17 or later installed on your machine. You can download Aws Corretto or Adoptium.
Gradle 8.6 or later. Download it here and extract it to a known location.
Step 1: Configure External Gradle
Unity 2022.3 bundles Gradle 7.5.1, which is too old. You need to point Unity to an external Gradle 8.6+ installation.
In Unity, go to Preferences > External Tools (macOS) or Edit > Preferences > External Tools (Windows)
Uncheck "Gradle Installed with Unity (recommended)"
Set the path to your Gradle 8.6 installation directory
Step 3: Configure JDK 17 for Gradle
Enable the Custom Gradle Properties Template in Project Settings > Player > Android > Publishing Settings > Build, then add the following line to Assets/Plugins/Android/gradleTemplate.properties:
Replace <PATH_TO_JDK_17> with the absolute path to your JDK 17 installation
Installation
In Unity, you need to import a custom package stored here:
In Unity Editor, click on Assets -> Import Package -> Custom Package and load the .unitypackage downloaded from our repository
Initialization
Initialize the SDK using your credentials and mediation configuration.
In MeticaInitConfig, API_KEY and APP_ID are mandatory. The USER_ID is optional, if you don't provide one (or pass an empty string), the Metica SDK will generate a unique UUID per player for you.
In MeticaMediationInfo provide the Max SDK Key.
The SDK provides two ways to initialize: a callback-based approach and an async approach. Both return a MeticaInitResponse object with the following properties:
SmartFloors.UserGroup– the experiment group assigned to the current player (holdoutortrial).SmartFloors.isForcedHoldout– a boolean indicating if the current player has been forcefully assigned to holdout, this can happen for several reasons, i.e. when there is a connection issue.UserId– the user ID for the current player. If you did not provide aUSER_IDduring initialization, this will contain the UUID that the SDK generated automatically.
Callback-based Initialization
Use MeticaSdk.Initialize with a callback to be notified when initialization completes. This approach works well in standard Unity MonoBehaviour lifecycles without requiring async/await.
Async Initialization
Alternatively, you can use the async version if your codebase uses async/await:
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.
Banner ads auto-refresh by default. To control refresh manually these are the methods available:
MREC Ads (300x250)
Medium Rectangle ads work the same way as banners but with a larger size.
MREC ads also auto-refresh by default. Use the same refresh control methods as banners:
Interstitial Ads
Full-screen ads that are shown between content transitions.
Rewarded Ads
Reward users for watching video ads.
App Open Ads (not natively supported)
The Metica SDK does not currently support the App Open ad format natively. If your application requires App Open ads, you can use the MAX SDK alongside the Metica SDK with the following considerations.
Integration Requirements
Initialization Order
Callback Restrictions
When using MAX SDK for App Open ads alongside Metica SDK, you must only register and use MAX SDK callbacks that are specifically related to App Open ads. Do not register MAX SDK callbacks for other ad types (banners, interstitials, rewarded) as these are managed by the Metica SDK.
Revenue Callback Delivery Mode
By default, OnAdRevenuePaid is delivered on Unity's main thread. During a fullscreen ad, Unity pauses the player loop. The callback is then deferred until the ad closes. If the process is killed before then, the event is lost.
This matters when you forward revenue events to analytics tools such as AppMetrica. Lost callbacks can mean lost revenue attribution.
Note: MaxSDK's default for fullscreen revenue events is native-thread delivery, for the same reason.
For interstitial and rewarded ads, you can opt into synchronous delivery on the native callback thread:
In NativeThread mode, OnAdRevenuePaid runs on a non-Unity thread as soon as the native SDK reports revenue. This bypasses the paused player loop and avoids losing the event if the process dies before the ad closes.
CallbackDelivery values
UnityMainThread
Default. Posts the callback to Unity's main thread. Delivery waits for the Unity player loop, which is paused while a fullscreen ad is displayed.
Use this if your game is currently enable InvokeEventsOnUnityMainThread in MaxSdk
NativeThread
Runs the callback synchronously on a non-Unity thread as soon as the native SDK fires the event, including while the player loop is paused. This match MaxSdk default behaviour
Notes
The setting is global and revenue-scoped.
It affects only
OnAdRevenuePaidfor interstitial and rewarded ads.Banner and MREC revenue are unaffected.
All other ad callbacks are unaffected.
You can set it before or after
Initialize.A value set before initialization is applied once the SDK is ready.
API Reference
MeticaSdk Methods
Initialization & Configuration
InitializeAsync(MeticaInitConfig, MeticaMediationInfo)
Task<MeticaInitResponse>
Initializes the SDK.
SetLogEnabled(bool)
void
Enables/disables debug logging (default: false).
MeticaSdk.Ads Methods
Banner Methods
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.
SetBannerPlacement(string adUnitId, string? placement)
Sets the placement for a banner ad. Call before LoadBanner.
SetBannerCustomData(string adUnitId, string? customData)
Sets custom data for a banner ad.
SetBannerExtraParameter(string adUnitId, string key, string? value)
Sets an extra parameter for a banner ad.
SetBannerLocalExtraParameter(string adUnitId, string key, object? value)
Sets a local extra parameter for a banner ad.
SetBannerLocalExtraParameterJson(string adUnitId, string key, string? value)
Sets a local extra parameter for a banner ad using a JSON string value.
SetBannerWidth(string adUnitId, float widthDp)
Sets the width for a banner ad in density-independent pixels.
SetBannerBackgroundColor(string adUnitId, string hexColorCode)
Sets the background color for a banner ad using a hex color code.
MREC Methods
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.
SetMrecPlacement(string adUnitId, string? placement)
Sets the placement for an MREC ad. Call before LoadMrec.
SetMrecCustomData(string adUnitId, string? customData)
Sets custom data for an MREC ad.
SetMrecExtraParameter(string adUnitId, string key, string? value)
Sets an extra parameter for an MREC ad.
SetMrecLocalExtraParameter(string adUnitId, string key, object? value)
Sets a local extra parameter for an MREC ad.
SetMrecLocalExtraParameterJson(string adUnitId, string key, string? value)
Sets a local extra parameter for an MREC ad using a JSON string value.
Interstitial Methods
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.
SetInterstitialExtraParameter(string adUnitId, string key, string? value)
void
Sets an extra parameter for an interstitial ad.
SetInterstitialLocalExtraParameter(string adUnitId, string key, object? value)
void
Sets a local extra parameter for an interstitial ad.
Rewarded Methods
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.
SetRewardedAdExtraParameter(string adUnitId, string key, string? value)
void
Sets an extra parameter for a rewarded ad.
SetRewardedAdLocalExtraParameter(string adUnitId, string key, object? value)
void
Sets a local extra parameter for a rewarded ad.
MeticaSdk.Ads.Max Methods
SetExtraParameter(string key, string? value)
void
Sets an extra parameter on the MAX SDK.
ShowMediationDebugger()
void
Shows the AppLovin MAX mediation debugger.
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
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
message
string
Error message.
adUnitId
string?
Associated ad unit identifier (nullable).
MeticaAdViewPosition Enum
Position options for banner and MREC ads:
TopCenter
Top center of the screen.
Centered
Center of the screen.
BottomCenter
Bottom center of the screen.
MeticaMediationType Enum
Supported mediation platforms:
MAX
AppLovin MAX mediation platform.
MeticaAdsCallbacks Events
Banner Callbacks
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
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
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
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
Important considerations while integrating
These are the patterns we see most often in real integrations. Most of them fail silently — no crash, just missing revenue or dropped callbacks — which is what makes them so easy to miss.
Wrapping revenue reporting in a main-thread post
When using CallbackDelivery.NativeThread, do not wrap your whole OnAdRevenuePaid handler in a main-thread dispatcher (UnityMainThreadDispatcher, SynchronizationContext.Post, coroutine queue, etc.).
During fullscreen ad display the Unity player loop is paused, so anything posted to the main thread sits unpumped until the ad closes — and is lost entirely if the user kills the app mid-ad. That defeats the reason NativeThread delivery exists in the first place.
Third-party analytics SDKs (Adjust, Firebase, AppMetrica, …) have thread-safe native tracking calls — call them directly in the callback. Marshal only the code that genuinely touches Unity back to the main thread, and put it after the reporting calls:
Rule of thumb: reporting first, directly on the native thread; Unity work last, marshalled to the main thread.
Calling Unity APIs from the native callback thread
The inverse mistake: in NativeThread mode, Unity APIs (PlayerPrefs, GameObject, Instantiate, coroutines, UI, most of Application) are main-thread-only and throw when called from the callback thread.
The SDK catches and logs handler exceptions, so the failure is silent: the exception aborts the handler, and every line after the throwing call — often the actual revenue reporting — never runs. The result is a systematic revenue undercount with nothing in your crash reporting.
Even an innocent-looking helper can be the culprit — e.g. a GetLevelCount() that reads PlayerPrefs internally. Audit the full call chain of your handler, not just the top-level code.
Comparing requested and returned ad unit IDs
Don't gate callback logic on the ad unit ID you requested:
Metica may load and show a different ad unit than the one you requested (parallel loading, failover units, SmartFloors routing), so requested and returned IDs are not guaranteed to match. An equality guard like this silently drops revenue and lifecycle events, or blocks the code path entirely.
This pattern usually comes from copying MAX integration code, where a per-ad-unit guard is idiomatic. With Metica it is a bug. If you need per-format routing, key on the ad format / callback source, not on ID equality with the requested unit.
Reporting revenue through both MAX and Metica
Metica mediates through MAX. If you keep your old MaxSdkCallbacks.*.OnAdRevenuePaidEvent analytics wiring alive alongside MeticaAdsCallbacks.*.OnAdRevenuePaid, the same impression is reported twice to your analytics (Adjust/Firebase/AppMetrica revenue inflated, impression counts doubled).
Route revenue through exactly one path per impression.
Re-initializing the SDK or re-subscribing handlers
InitializeAsync must be called exactly once per app launch. Re-running your init flow (scene reloads, retry logic, focus handlers) re-subscribes your event handlers, and every subsequent callback then fires once per subscription — duplicate revenue reports, duplicate reward grants.
Guard your init with a flag, or use -= before += when subscribing.
Initializing off the Unity main thread
MeticaSdk.InitializeAsync must be invoked on the Unity main thread. The SDK captures the SynchronizationContext at the initialize call site and uses it for main-thread callback dispatch — if you initialize from a background thread (a Task.Run, a thread-pool continuation, a native callback), main-thread-delivered callbacks are dispatched to the wrong context and can misbehave in ways that are very hard to diagnose.
Watch out for await-heavy init flows: an await before the InitializeAsync call can silently move you off the main thread depending on the awaited task's context.
Initializing inside a CMP / UMP consent callback without marshalling
A common init pattern is: run the consent flow first, then initialize Metica in the consent-completed callback. The catch: CMP/UMP callbacks frequently fire off the Unity main thread.
Combined with #6, this means chaining InitializeAsync directly inside the consent callback can initialize the SDK on a background thread. Marshal back to the Unity main thread before initializing:
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.
Last updated
Was this helpful?

