> 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/ios-sdk.md).

# iOS SDK

Integrate Metica SmartFloors into an iOS game that monetizes through AppLovin MAX

The Metica iOS SDK sits on top of AppLovin MAX. Your game loads and shows ads through `MeticaSdk.Ads`, the SDK initializes and manages MAX internally, and SmartFloors optimizes the ad units each player is served. The game 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
* A `Max SDK Key`, obtainable from the AppLovin platform

### Requirements

| Requirement          | Value                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| iOS                  | 15.0 or newer                                                                                          |
| Swift                | 5.5 or newer, Swift only (no Objective-C API)                                                          |
| Xcode                | 16.2 or newer                                                                                          |
| AppLovin MAX iOS SDK | 13.0.1 or newer, added to your app as its own Swift package                                            |
| Distribution         | Swift Package Manager, binary XCFramework from `https://github.com/meticalabs/metica-ios-sdk-releases` |

### Supported ad formats

| Format           | `MeticaAdFormatType` | Description                                       |
| ---------------- | -------------------- | ------------------------------------------------- |
| **Banner**       | `.BANNER`            | Adaptive banner ads                               |
| **MREC**         | `.MREC`              | Medium Rectangle ads (300x250)                    |
| **Interstitial** | `.INTER`             | Full-screen ads shown between content transitions |
| **Rewarded**     | `.REWARDED`          | Video ads that reward users for watching          |

### Integration steps

{% stepper %}
{% step %}

#### Add the AppLovin MAX package

In Xcode, add `https://github.com/AppLovin/AppLovin-MAX-Swift-Package` (13.0.1 or newer) to your app. Only the package is needed. The Metica SDK initializes MAX for you.
{% endstep %}

{% step %}

#### Add the Metica package

Add `https://github.com/meticalabs/metica-ios-sdk-releases` with the version rule "Up to next major" from `2.5.5`, link the `MeticaSDK` product, and `import MeticaSDK` where you use it.

{% embed url="<https://github.com/meticalabs/metica-ios-sdk-releases>" %}

{% hint style="danger" %}
Do not call, reference or initialize the AppLovin SDK directly and do not register MAX delegates. The Metica SDK manages the MAX integration internally. Doing it yourself causes duplicate initialization and callback collisions.
{% endhint %}
{% endstep %}

{% step %}

#### Initialize the SDK

Call `MeticaSdk.initialize` exactly once per app session, on the main actor, before any ad call. Set privacy flags first if you have them. See [Initialization](https://docs.metica.com/api/ios-sdk/initialization.md).
{% endstep %}

{% step %}

#### Implement the ad formats you use

[Banner ads](https://docs.metica.com/api/ios-sdk/banner-ads.md), [MREC ads](https://docs.metica.com/api/ios-sdk/mrec-ads.md), [Interstitial ads](https://docs.metica.com/api/ios-sdk/interstitial-ads.md) and [Rewarded ads](https://docs.metica.com/api/ios-sdk/rewarded-ads.md). All ad operations go through `MeticaSdk.Ads` and events arrive on the callback protocols you pass in.
{% endstep %}

{% step %}

#### Forward revenue from one place

Read [Revenue tracking](https://docs.metica.com/api/ios-sdk/revenue-tracking.md) before wiring `onAdRevenuePaid` to your analytics SDK.
{% 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 entry in [Troubleshooting](https://docs.metica.com/api/ios-sdk/troubleshooting.md).

1. Call `MeticaSdk.initialize` exactly once per app session, on the main actor, before any ad call.
2. Do not initialize the AppLovin SDK or register MAX delegates yourself. The Metica SDK does it.
3. Access the SDK through `MeticaSdk.Ads`, `MeticaSdk.privacySettings` and `MeticaSdk.applovinFunctions`. Each is a `Result`, so unwrap it with `get()`.
4. Load and show every banner, MREC, interstitial and rewarded ad through `MeticaSdk.Ads` and handle events through the Metica callback protocols.
5. 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.
6. 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.
7. Report revenue to your analytics tools from `onAdRevenuePaid` only, never from MAX delegates as well.
8. Treat `smartFloors.userGroup` and `smartFloors.isForcedHoldout` as analytics data. Do not branch your ad logic on them.
9. Call `destroy()` on banner and MREC views you no longer show.

### Reference

* [API reference](https://docs.metica.com/api/ios-sdk/api-reference.md) for every method, type and callback
* [Troubleshooting](https://docs.metica.com/api/ios-sdk/troubleshooting.md) for the mistakes we see most often in real integrations
* [Release notes](https://github.com/meticalabs/metica-ios-sdk-releases/tags) 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/ios-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/ios-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.
