Android SDK

Metica Ads SDK - Native Android Integration Guide

https://github.com/meticalabs/metica-android-sdk

Overview

The Metica Ads SDK supports native Android applications, offering seamless integration for monetizing your apps with ads. This guide will help you integrate the SDK into your native Android application.

Prerequisites

• Android API level 21 or higher

• Kotlin or Java development

• Valid Metica API credentials (API key, App ID)

• AppLovin MaxSdk dependency version 13.0.0 or higher

Installation

To add the Metica Ads SDK, include the following dependency in your build.gradle.kts file:

dependencies {
    implementation("com.metica:metica-sdk:+")
}

---

Initialization

⚠️ CRITICAL REQUIREMENT: You must initialize the AppLovin SDK after the Metica SDK initialization succeeds and before invoking any ad methods to ensure proper ad loading.

Initialize the SDK Place the SDK initialization code in your Application class or main Activity:

import com.metica.Metica
import com.metica.MeticaInitCallback
import com.metica.MeticaInitConfig

class MainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Metica.initialize(
            config = MeticaInitConfig(
                apiKey = "your-api-key",
                appId = "your-app-id",
                userId = "unique-user-id"
            ),
            context = this,
            callback = object : MeticaInitCallback {
                override fun onInitialized(adsEnabled: Boolean) {
                    // Important: Initialize AppLovin SDK after successful Metica initialization
                    if (adsEnabled) {
                        // Proceed with loading ads
                    } else {
                        useRegularAdFlow()
                    }
                }

                override fun onFailed(reason: String) {
                    Log.e("MeticaAds", "Initialization failed: $reason")
                }
            }
        )
    }
}

---

Interstitial Ads

Load Interstitial Ad

private fun loadInterstitialAd() {
    MeticaAds.loadInterstitial(object : MeticaAdsLoadCallback {
        override fun onAdLoadSuccess(meticaAd: MeticaAd) {
            Log.d("MeticaAds", "Interstitial ad loaded successfully")
            // Ad is ready to show
        }

        override fun onAdLoadFailed(error: String) {
            Log.e("MeticaAds", "Failed to load interstitial ad: $error")
        }
    })
}

Show Interstitial Ad

private fun showInterstitialAd() {
    if (MeticaAds.isInterstitialReady()) {
        MeticaAds.showInterstitial(this, object : MeticaAdsShowCallback {
            override fun onAdShowSuccess(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Interstitial ad shown")
            }

            override fun onAdShowFailed(meticaAd: MeticaAd, error: String) {
                Log.e("MeticaAds", "Failed to show interstitial ad: $error")
            }

            override fun onAdHidden(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Interstitial ad hidden")
                // Continue with game flow
            }

            override fun onAdClicked(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Interstitial ad clicked")
            }

            override fun onAdRevenuePaid(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Revenue: ${meticaAd.revenue}")
            }
        })
    }
}

---

Rewarded Ads

Load Rewarded Ad

private fun loadRewardedAd() {
    MeticaAds.loadRewarded(object : MeticaAdsLoadCallback {
        override fun onAdLoadSuccess(meticaAd: MeticaAd) {
            Log.d("MeticaAds", "Rewarded ad loaded successfully")
            // Enable reward button in UI
        }

        override fun onAdLoadFailed(error: String) {
            Log.e("MeticaAds", "Failed to load rewarded ad: $error")
        }
    })
}

Show Rewarded Ad

private fun showRewardedAd() {
    if (MeticaAds.isRewardedReady()) {
        MeticaAds.showRewarded(this, object : MeticaAdsShowCallback {
            override fun onAdShowSuccess(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Rewarded ad shown")
            }

            override fun onAdShowFailed(meticaAd: MeticaAd, error: String) {
                Log.e("MeticaAds", "Failed to show rewarded ad: $error")
            }

            override fun onAdRewarded(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "User earned reward!")
                // Grant reward to user (coins, lives, etc.)
                grantReward()
            }

            override fun onAdHidden(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Rewarded ad hidden")
            }

            override fun onAdClicked(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Rewarded ad clicked")
            }

            override fun onAdRevenuePaid(meticaAd: MeticaAd) {
                Log.d("MeticaAds", "Revenue: ${meticaAd.revenue}")
            }
        })
    }
}

---

API Reference

Core Classes

Metica

Main entry point for SDK initialization.

• initialize(context, config, callback) - Initialize the SDK

MeticaInitConfig

Configuration for SDK initialization.

data class MeticaInitConfig(
    val apiKey: String,    // Your Metica API key
    val appId: String,     // Your Metica app ID  
    val userId: String     // Unique user identifier
)

MeticaAds

Main class for ad operations.

• loadInterstitial(callback) - Load an interstitial ad

• showInterstitial(activity, callback) - Show an interstitial ad

• isInterstitialReady() - Check if interstitial ad is ready\

• loadRewarded(callback) - Load a rewarded ad

• showRewarded(activity, callback) - Show a rewarded ad

• isRewardedReady() - Check if rewarded ad is ready

MeticaAd

interface MeticaAd {
    val adUnitId: String        // Ad unit identifier
    val revenue: Double         // Revenue in USD
    val networkName: String?    // Ad network name
    val placementTag: String?   // Placement identifier
    val adFormat: String        // Ad format type
    val creativeId: String?     // Creative identifier
    val latency: Long          // Request latency in ms
}

Callbacks

MeticaInitCallback

interface MeticaInitCallback {
    fun onInitialized(adsEnabled: Boolean)  // SDK ready, adsEnabled indicates if user can see Metica ads
    fun onFailed(reason: String)            // Initialization failed
}

MeticaAdsLoadCallback

interface MeticaAdsLoadCallback {
    fun onAdLoadSuccess(meticaAd: MeticaAd)  // Ad loaded successfully
    fun onAdLoadFailed(error: String)        // Ad load failed
}

MeticaAdsShowCallback

interface MeticaAdsShowCallback {
    fun onAdShowSuccess(meticaAd: MeticaAd)           // Ad displayed
    fun onAdShowFailed(meticaAd: MeticaAd, error: String)  // Show failed
    fun onAdHidden(meticaAd: MeticaAd)                // Ad dismissed
    fun onAdClicked(meticaAd: MeticaAd)               // Ad clicked
    fun onAdRevenuePaid(meticaAd: MeticaAd)           // Revenue confirmed
    fun onAdRewarded(meticaAd: MeticaAd)              // Reward earned (rewarded ads only)
}

---

Best practices

Thread Safety

All SDK methods are thread-safe and callbacks are delivered on the calling thread.

Activity Parameter

Always pass the current Activity to show methods. The activity must be active when showing ads.

Logging

Enable debug logging during development:

import com.metica.ads.util.MeticaLogger

// Enable in debug builds only
if (BuildConfig.DEBUG) {
    MeticaLogger.enableLogs = true
}