---
description: Integration Guide.
---

# Installing and configuring the plugin

Release version **1.4.4** | Release date **08/05/2025**

{% hint style="info" %}
Minimum requirements:

* Use Unity 2018.3+ version.
* Use Android API level 22 (Android OS 5.1) and above.
* Use iOS 13.0 and above.
* Use Xcode 13 and above.
{% endhint %}

## Demo application

Use our demo application as an example.

{% embed url="https://github.com/MadexTech/madex-unity-demo" %}

## Installation

### General description of the installation process

To install the Unity Plugin, you will need:

* Check out the demo application
* Download and import the latest version of the plugin into your project.
* Configure `External Dependency Manager`
* Check the installation correctness by initializing the plugin with debug mode enabled

### Download the Plugin

1. Download the latest version of the plugin at the [link](https://sdkpkg.sspnet.tech/unity/madex/latest/madex-unity-plugin.unitypackage).
2.  Import the plugin into your project using the `Custom Package` option.\
    \
    The plugin includes the `External Dependency Manager`.\
    You may not import it if it has already been installed in the project.\
    \


    <figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FhwYkCWP77xBWJRrR3vZG%2Fimage.png?alt=media&#x26;token=80dd61c7-a2c8-4e05-8090-3555407bff3f" alt=""><figcaption></figcaption></figure>

### Configure External Dependency Manager

**External Dependency Manager** is a plugin for resolving dependency conflicts

To resolve dependency conflicts in your application, follow these steps:

1. Navigate to `Build Settings` → `Android` → `Player Settings` → `Publishing settings`
2.  For `Unity 2018.4` - `Unity 2019.2`: add the `Custom Gradle Template` flag\
    For `Unity 2019.3` or newer: add the `Custom Main Gradle Template` flag\


    <figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FEwbDGl9R8MBFmBAxMvRj%2Fimage.png?alt=media&#x26;token=62295e64-6529-4a33-9859-f794d3a76f52" alt=""><figcaption></figcaption></figure>


3. Go to `External Dependency Manager` → `Android Resolver` → `Settings`
4. Enable the `Patch mainTemplate.gradle` setting
5.  Enable the `Use Jetifier` setting



    <figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FqPO94Zt0xpuiIDgRzXbF%2Fimage.png?alt=media&#x26;token=c2a0bf1f-1b63-49c5-8e18-e8e7d22ba30c" alt=""><figcaption></figcaption></figure>


6. Select the `Force Resolve` option in `External Dependency Manager` → `Android Resolver` → `Force Resolve`
7. If the dependencies are installed successfully, you will see the `Resolution Succeeded` alert

### Code obfuscation

If code obfuscation is enabled in your application, then add the following text to the end of the file `proguard-rules.pro`:

```processing
-keep class sspnet.tech.**.* { *; }
```

### Add the Applovin SDK key

If you are using an adapter for Applovin, then follow these steps for the platform you are working with// Some code

{% tabs %}
{% tab title="Android" %}
If you are using an adapter for Applovin, then add the following `<meta-data>` element to your `AndroidManifest.xml` inside the  `<application>` element:

```gradle
<meta-data android:name="applovin.sdk.key"
           android:value="APPLOVIN_SDK_KEY"/>
```

You can copy your `APPLOVIN_SDK_KEY` in the "Keys" section of your Applovin[ personal account](https://dash.applovin.com/o/account?r=2#keys).
{% endtab %}

{% tab title="iOS" %}
Add the following key to `Info.plist`:

```html
<key>AppLovinSdkKey</key>
<string>APPLOVIN_SDK_KEY</string>
```

You can copy your `APPLOVIN_SDK_KEY` in the "Keys" section of your Applovin [personal account](https://dash.applovin.com/o/account?r=2#keys).
{% endtab %}
{% endtabs %}

### Installation check

To make sure that the plugin is installed correctly, you will need to enable debug mode and initialize the plugin.

### Debug mode

In debug mode the plugin logs errors and events. It is disabled by default.

Use the `EnableDebug` method to enable debug mode.

```csharp
Madex.enableDebug(true);
```

### Initialization

1. Inherit the class that will work with the SDK from the interface for tracking SDK initialization.

```java
class YourClassName : IInitializationListener {    
    public void OnInitializeSuccess()
    {
        // Called when the SDK is installed correctly
    }
    
    public void OnInitializeFailed(AdException error)
    {
        // Called when an error occurred during SDK installation
        // Using AdException error, you can get detailed information about the error
    }
}
```

1. Use the code below to initialize the plugin in your project.\
   You can copy your `publisher_id` in the "Settings" section of your Madex [personal account](https://publisher.madex.world/).

```csharp
Madex.initialize("publisher_id");
```

If the plugin is installed correctly, you will see the following message in the console.

```markup
Call to Initialize on not supported platform. To test advertising, install your application on the Android/iOS device.
```

This message indicates that the plugin is installed correctly, but ad display is only possible after building the application for Android/iOS.



Done! The plugin is installed, you can proceed to [setting up ads](working-with-advertising).

We recommend that you don't disable debug mode until you finish working with ads.

### If the plugin is installed incorrectly

In case of errors, we recommend clearing the `External Dependency Manager` cache and selecting `Force Resolve` in `External Dependency Manager` → `Android Resolver`.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FSmzhatE0mZHm8NrVSEMn%2Fimage.png?alt=media&#x26;token=15dc7e77-2d2c-4790-ae6b-8e0727d2f29a" alt=""><figcaption><p>Clearing the External Dependency Manager cache on Mac OS</p></figcaption></figure>

If this doesn't help, try installing the plugin in a clean project. If the plugin is installed correctly, try to debug errors in your project.

We also recommend to take a look at the installation and initialization in the [demo application](https://github.com/MadexTech/madex-unity-demo).

If you are unable to install the plugin correctly and the above steps didn't lead to successful initialization, please contact support.

## Connecting external ad networks to the project

If you are using Madex mediation (working with other ad networks through our plugin):

1. Import the file into the project received from the Madex account manager (drag and drop the file into the project or use the `Custom Package` option)
2. Select the `Force Resolve` option in `External Dependency Manager` → `Android Resolver` → `Force Resolve`

## Updating the Plugin and Managing Adapters for Other Ad Networks

{% hint style="warning" %}
Check for an update before building the app.
{% endhint %}

The Madex Unity Plugin provides a convenient interface for updating the plugin and managing ad networks. In the Dependency Manager window, you can update the plugin to the latest version and choose the ad networks you want to use.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FmCjXJwNmT8n7HcW56WTG%2Fimage.png?alt=media&#x26;token=9bd4e42f-1fb7-4af5-8db8-27d4514ae911" alt=""><figcaption></figcaption></figure>

## Additional actions to increase revenue

### Setting Up Apple ID

For more effective targeted advertising and increased revenue, Madex Unity Plugin collects and transmits user [App ID](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/) data - a unique numerical application identifier from the Apple AppStore.

It is determined automatically, but in some cases, Madex Unity Plugin may not be able to determine it.

If Madex Unity Plugin did not determine your App ID, you will see the following message in the console.

```
AppStore ID is nil. You must set AppStore ID manually.
```

In this case, you need to set the ID manually.

To set up Apple ID, use the `setCustomParams` method.

```
Madex.setCustomParams("appStoreAppID", "apple_id")
```

Replace `apple_id` with your App ID from the AppStore developer account. You can find it on the app page in the [developer account](https://appstoreconnect.apple.com/).

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2F3d8NCA9Hhb1P8wy8kSy1%2Fimage.png?alt=media&#x26;token=48a6af1b-4e34-4bb3-87b5-1bb801ec6b64" alt=""><figcaption><p>Using an Apple ID in the AppStore Connect</p></figcaption></figure>

### Apple Advertising Identifier (IDFA)

For more effective targeted advertising and increased revenue, you can collect the Apple device advertising identifier and pass it to Madex Unity Plugin.

To enable IDFA collection, check the following checkboxes in the plugin setting:

`NSUserTrackingUsageDescription` - Permission to collect the advertising identifier (Advertising Identifier IDFA).

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2F9CPGpqtP3k6k9j5nhyAp%2Fimage.png?alt=media&#x26;token=ac1db629-cade-43b2-8d6c-9968ffad79c8" alt=""><figcaption></figcaption></figure>

### Geolocation data collection

To make targeted ads work more effectively and increase revenue, you can collect in app data about a user's exact and/or approximate geolocation, and feed it into the Madex Unity Plugin.

{% tabs %}
{% tab title="Android" %}
To enable geolocation data collection on Android, check the following checkboxes in the plugin settings:

`ACCESS_COARSE_LOCATION` - Permission to collect approximate user geolocation.

`ACCESS_FINE_LOCATION` - Permission to collect precise user geolocation.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FO2oeIiWTDDfHu6ccyTQj%2Fimage.png?alt=media&#x26;token=2cb1d7fa-b78e-48dc-8728-7014d3ba3f91" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="iOS" %}
To enable geolocation data collection on iOS, check the following checkboxes in the plugin settings:

`NSLocationWhenInUseUsageDescription` -  Permission to collect user geolocation

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2F35wc8IaWcUg0PqQyWG0X%2Fimage.png?alt=media&#x26;token=980ad03a-ddcd-4459-8c31-9e7b0e4e89a7" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## Other plugin settings

### User Consent Screen

In order to comply with the requirements of the app store and the laws governing the collection, processing and use of user's personal data, it is required to obtain his consent to the above actions.

Usually, the user's consent is obtained on a special screen when the application is first launched — consent-screen.

The Madex Unity Plugin implements such a screen, you can add and configure it using the Content Manager library.

You can find out more about its installation and configuration in the corresponding section.

{% content-ref url="user-consent-screen" %}
[user-consent-screen](user-consent-screen)
{% endcontent-ref %}

### Possible errors&#x20;

#### Library not loaded: @rpath/MadexSDK.framework/MadexSDK&#x20;

The error occurs due to the peculiarities of xcframework linking in Unity. In order to fix the error, you need to download `MadexPostProcessBuildiOS.cs` from this [link](https://sdkpkg.sspnet.tech/unity/madex/utils/MadexPostProcessBuildiOS.cs) and place it in the `scripts` folder or in another folder for your scripts.
