---
description: Integration Guide.
---

# Installation and configuration the plugin

Release version **1.5.10** | Release date **06/20/2025**

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

* Use Cordova 10.1.0 and above.
* 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-cordova-demo" %}

## Installation

### General description of the installation process

To install the Cordova Plugin, you will need:

* Check out the demo application
* Install the plugin using `npm`
* Declare a variable for using the plugin.
* Check the installation correctness by initializing the plugin with debug mode enabled. Install the Plugin

### Download the plugin

1. Open the terminal in the project folder and enter the command to install the dependency

```bash
cordova plugin add cordova.plugin.madex
```

2. Declare a variable for using the plugin after the `deviceready` event is triggered.

```javascript
document.addEventListener('deviceready', onDeviceReady, false);

var Madex;

function onDeviceReady() {
    Madex = cordova.require('cordova.plugin.madex.Madex');
}    
```

### Installation check

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

### Debug mode

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

Use the `EnableDebug` method to enable debug mode.

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

### Initialization

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/).

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

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

```
SDK initialized(<Madex SDK version number>)
```

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, it is recommended to clear the `npm` cache.&#x20;

```bash
npm cache clean --force
```

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-cordova-demo).

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

## Additional actions to increase revenue

### Setting Up Apple ID

For more effective targeted advertising and increased revenue, Madex SDK 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 SDK may not be able to determine it.

If Madex SDK 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.

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

Set `Key` to `appStoreAppID`.

Replace `apple_id` with your App ID from the AppStore Developer Console. You can find it on the app page in the [developer cabinet](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></figcaption></figure>

### Apple Advertising Identifier (IDFA)

For more effective targeted advertising and increased revenue, you can gather the Apple device's advertising identifier and transmit it to the Madex SDK.

To enable the collection of IDFA, insert the following code into your application's `config.xml` file:

```xml
<?xml version='1.0' encoding='utf-8'?>
<widget id="your.app.id" version="1.0.0" xmlns:tools="http://schemas.android.com/tools" xmlns:android="http://schemas.android.com/apk/res/android" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
   <!-- ... other settings -->
   
    <platform name="ios">
        <config-file target="*-Info.plist" parent="NSUserTrackingUsageDescription">
            <string>We need this permission for better ad targetting</string>
        </config-file>
    </platform>
</widget>
```

### 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 SDK.

{% tabs %}
{% tab title="Android" %}
By default, geolocation permissions are enabled in the Android SDK.

If you prefer not to provide geolocation data, insert the following code into your application's `config.xml` file:

```xml
<?xml version='1.0' encoding='utf-8'?>
<widget id="your.app.id" version="1.0.0" xmlns:tools="http://schemas.android.com/tools" xmlns:android="http://schemas.android.com/apk/res/android" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
   <!-- ... other settings -->
   
    <platform name="android">
    
        <!-- ... other settings -->
        
        <!-- It is essential to add this line -->
        <edit-config file="app/src/main/AndroidManifest.xml" target="/manifest" mode="merge">
            <manifest xmlns:tools="http://schemas.android.com/tools" />
        </edit-config>
        
        <!-- Permission to collect approximate user geolocation -->
        <config-file target="app/src/main/AndroidManifest.xml" parent="/*">
            <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove" />
        </config-file>
        
        <!-- Permission to collect precise user geolocation -->
        <config-file target="app/src/main/AndroidManifest.xml" parent="/*">
            <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove" />
        </config-file>
    </platform>
</widget>
```
{% endtab %}

{% tab title="iOS" %}
To enable geolocation data collection on iOS, insert the following code into the `config.xml` file of your application:

```xml
<?xml version='1.0' encoding='utf-8'?>
<widget id="your.app.id" version="1.0.0" xmlns:tools="http://schemas.android.com/tools" xmlns:android="http://schemas.android.com/apk/res/android" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
   <!-- ... other settings -->
   
    <platform name="ios">
        <config-file target="*-Info.plist" parent="NSLocationWhenInUseUsageDescription">
            <string>We need this permission for better ad targetting</string>
        </config-file>
    </platform>
</widget>
```
{% endtab %}
{% endtabs %}

