Installation and configuration the plugin

Integration Guide.

Release version 1.5.1 | Release date 03/20/2025

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.

Demo application

Use our demo application as an example.

GitHub - MadexTech/madex-cordova-demoGitHub

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

 cordova plugin add @madex-dev/cordova.plugin.madex

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

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.

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.

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.

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.

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.

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

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.

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

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 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>

iOS

To enable geolocation data collection on iOS, insert the following code into the config.xml file of your application:

<?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>