> For the complete documentation index, see [llms.txt](https://docs.metica.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metica.com/api/android-sdk.md).

# Android SDK

Integrate Metica SmartFloors into an Android app that monetizes through AppLovin MAX

The Metica Android SDK sits on top of AppLovin MAX. Your app loads and shows ads through `MeticaSdk.Ads`, the SDK initializes MAX and drives the ad lifecycle internally, and SmartFloors optimizes the ad units each user is served. The app flow and the supported ad formats stay the same.

### What you need

* An `API key`, obtainable in the Metica platform
* An `appId`, obtainable in the Metica platform
* An AppLovin `SDK Key` from the [AppLovin dashboard](https://dash.applovin.com/o/account?r=3#keys)

### Requirements

| Requirement          | Value                                                              |
| -------------------- | ------------------------------------------------------------------ |
| Android              | API 21 (Android 5.0) or higher                                     |
| AppLovin Android SDK | `com.applovin:applovin-sdk` 13.0.1 or higher, declared by your app |
| Kotlin               | 2.0 or higher, if your app code is Kotlin                          |
| Java                 | 11 or higher                                                       |

### Supported ad formats

| Format       | `MeticaAdFormatType` | Dimensions        |
| ------------ | -------------------- | ----------------- |
| Interstitial | `INTER`              | Full-screen       |
| Rewarded     | `REWARD`             | Full-screen video |
| Banner       | `BANNER`             | Adaptive          |
| MREC         | `MREC`               | 300x250           |

### Integration steps

{% stepper %}
{% step %}

#### Add the dependencies

The SDK is distributed through [Maven Central](https://central.sonatype.com/artifact/com.metica/metica-sdk/versions). It compiles against the AppLovin SDK but does not pull it in, so your app declares both.

{% code title="build.gradle.kts" %}

```kotlin
dependencies {
    implementation("com.metica:metica-sdk:<version>")
    implementation("com.applovin:applovin-sdk:<13.0.1 or newer>")
}
```

{% endcode %}

Make sure you have Maven Central in your repositories:

{% code title="repositories" %}

```kotlin
repositories {
    mavenCentral()
}
```

{% endcode %}

Keep your existing AppLovin mediation adapters. The Metica SDK uses them through MAX.
{% endstep %}

{% step %}

#### Set privacy settings

Set GDPR consent and the CCPA do-not-sell flag before initialization. See [Initialization](https://docs.metica.com/api/android-sdk/initialization.md).
{% endstep %}

{% step %}

#### Initialize the SDK

Call `MeticaSdk.initialize` once at application startup, before any ad call. See [Initialization](https://docs.metica.com/api/android-sdk/initialization.md).
{% endstep %}

{% step %}

#### Implement the ad formats you use

[Interstitial ads](https://docs.metica.com/api/android-sdk/interstitial-ads.md), [Rewarded ads](https://docs.metica.com/api/android-sdk/rewarded-ads.md), [Banner ads](https://docs.metica.com/api/android-sdk/banner-ads.md) and [MREC ads](https://docs.metica.com/api/android-sdk/mrec-ads.md). All ad operations go through `MeticaSdk.Ads`.
{% endstep %}

{% step %}

#### Wire up revenue tracking

Report revenue from `onAdRevenuePaid` and pick the delivery thread. See [Revenue tracking](https://docs.metica.com/api/android-sdk/revenue-tracking.md).
{% endstep %}

{% step %}

#### Verify the integration

Run the [SmartFloors Integration Test](https://docs.metica.com/uiguide/sdk-integration-test.md) and follow [Get started with SmartFloors](https://docs.metica.com/api/verify-smartfloor-integration.md) to submit a build for verification.
{% endstep %}
{% endstepper %}

### Integration rules

These rules apply to every integration. Each one has a matching check in the [Troubleshooting](https://docs.metica.com/api/android-sdk/troubleshooting.md) page.

1. Call `MeticaSdk.initialize` exactly once per app session, before any ad call.
2. Do not call, reference or initialize the AppLovin SDK directly and do not register AppLovin listeners. The Metica SDK manages MAX internally.
3. Load and show every interstitial, rewarded, banner and MREC ad through `MeticaSdk.Ads`.
4. Pass your game's own AppLovin MAX ad unit IDs, the ones it used before Metica, the same ID for every player. Never pass the ad units Metica created for your app.
5. Do not gate callback logic on the ad unit ID you requested. For interstitial and rewarded ads, Metica may load and show a different ad unit than the one requested.
6. Report revenue to your analytics tools from `onAdRevenuePaid` only, never from AppLovin callbacks as well.
7. Treat `smartFloors.userGroup` and `smartFloors.isForcedHoldout` as analytics data. Do not branch your ad logic on them.
8. Pass the current `Activity` when showing fullscreen ads, never the application context.

### Reference

* [API reference](https://docs.metica.com/api/android-sdk/api-reference.md) for every method, type and callback
* [Troubleshooting](https://docs.metica.com/api/android-sdk/troubleshooting.md) for best practices, thread safety and the mistakes we see most often
* [Complete example](https://docs.metica.com/api/android-sdk/complete-example.md) for one activity that initializes the SDK and shows every format
* [Release notes](https://github.com/meticalabs/metica-android-sdk/releases) for every SDK version

### Using these docs with AI tools

Every page of this site is available as Markdown by appending `.md` to its URL, for example `https://docs.metica.com/api/android-sdk.md`. An index of all pages is at [docs.metica.com/llms.txt](https://docs.metica.com/llms.txt) and the full content in one file at [docs.metica.com/llms-full.txt](https://docs.metica.com/llms-full.txt). Point your coding agent at these when you want it to answer questions about the SDK.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.metica.com/api/android-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
