> For the complete documentation index, see [llms.txt](https://madex.gitbook.io/madex-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://madex.gitbook.io/madex-documentation/construct3-addon/addon-installation-and-configuration.md).

# Addon installation and configuration

Integration Guide.

Release version **1.1.0** | Release date **07/07/2023**

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

* Use Construct r368.2 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-construct3-demo>" %}

## Installation

### General description of the installation process

To install the Construct3 Addon, you will need:

* Check out the demo application
* Download and import the latest version of the addon into your project.
* Check the installation correctness by initializing the SDK with debug mode enabled
* (Optional) If you use mediation (working with other ad networks through Madex), download and import the latest version of the addon for mediation. Installation and configuration of the mediation addon is described in the [corresponding section](/madex-documentation/construct3-addon/installation-and-configuration-of-madex-mediation-addon-deprecated.md).

### Download the Addon

1. Download the latest version of the addon at the [link](https://sdkpkg.sspnet.tech/construct3/madex/latest/madex.c3addon).
2. Open `Menu` -> `View` -> `Addon manager`.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FYAxTsy7KOalTZdyl1Kaa%2Fimage.png?alt=media&amp;token=02496f14-2abb-4df1-aaee-176014e10e99" alt=""><figcaption></figcaption></figure>

3. In the opened menu, click the `Install new addon...` button, select the Madex addon you downloaded in step 1.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FwzCwOfdliGBaCougx5Lj%2Fimage.png?alt=media&amp;token=9f537c93-5a25-48e3-99c3-6f96d02ab88f" alt=""><figcaption></figcaption></figure>

4. Click `Install`.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FxLsjPgcRBdhDcjXG94wm%2Fimage.png?alt=media&amp;token=6917c32c-5a88-47fe-83b9-726934e1dbd5" alt=""><figcaption></figcaption></figure>

5. Reload the Construct3 editor.\
   \
   If the Madex SDK installed correctly, it will appear in the `Addon Manager`.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FTL1CmRQ4GOUcZV3vGCQF%2Fimage.png?alt=media&amp;token=98d30816-a9b6-474e-85d7-e530737b9665" alt=""><figcaption></figcaption></figure>

6. Go to your project.
7. In your project, right-click, select `Insert new object`.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2F8CKvJZ3efSYiYG1VskRZ%2Fimage.png?alt=media&amp;token=e8524211-4a1e-46e8-aeb4-a06f64d2276f" alt=""><figcaption></figcaption></figure>

8. From the list, choose Madex, and click `Insert`.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FXZFgJW76hpG2hv1JWQcL%2Fimage.png?alt=media&amp;token=9eac8e84-0509-43ce-8ac1-728bc89655db" alt=""><figcaption></figcaption></figure>

9. Save the project.

### Installation check

To make sure that the SDK 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.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FSOz5owOnVPPpWAHt09KB%2Fimage.png?alt=media&amp;token=ba9234cd-96ed-436f-a780-30f5b40b7dab" alt=""><figcaption></figcaption></figure>

### Initialization

1. Open the event list, click `Add event`.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FBKT61fybo1vRx1noTpF2%2Fimage.png?alt=media&amp;token=a357572b-06f9-48d6-a768-6a3eb1b77f56" alt=""><figcaption></figcaption></figure>

2. Choose `System` -> `On start of layout`.

<div><figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FD9QY3aSagHA0JJz7cuzA%2Fimage.png?alt=media&amp;token=c7494ae2-e7b6-4590-b6dc-9c7809c87d5a" alt=""><figcaption></figcaption></figure> <figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FfUzQri7ZtW3rHSnXFu3O%2Fimage.png?alt=media&amp;token=248c8be1-5f13-4f68-81bd-81a692e4ee7b" alt=""><figcaption></figcaption></figure></div>

3. Click `Add Action` -> `Choose Madex` -> `Initialize`.

<div><figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FaoLq7ezrBdmthmTCMyx3%2Fimage.png?alt=media&amp;token=53860c21-e3ba-43f4-82a5-61237f3799c9" alt=""><figcaption></figcaption></figure> <figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FYZNahFqLTaKmXq2wxpJ2%2Fimage.png?alt=media&amp;token=ee0f7a8f-1b20-44eb-9dbe-80f110fa3507" alt=""><figcaption></figcaption></figure> <figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FViN1oiZ2k3DTryGAMqjU%2Fimage.png?alt=media&amp;token=457f2248-27f7-48ad-bc9c-c03c1e5cbef5" alt=""><figcaption></figcaption></figure></div>

4. Enter your `publisher_id` in quotes.\
   \
   You can copy your `publisher_id` in the "Settings" section of your Madex [personal account](https://publisher.madex.world/).

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FXYb33xZyEZ71OAVTv3vu%2Fimage.png?alt=media&amp;token=0974449e-ec24-4e40-bb51-56f1cb54f12a" alt=""><figcaption></figcaption></figure>

Run the application in the Construct3 editor and open the browser console (F12).

If the SDK is installed correctly, you will see the following message in the browser console:

```markup
Call Initialize. Launch app in any platform to see result
```

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FtHICzVHPfw1kblP4snfd%2Fimage.png?alt=media&amp;token=02b9a447-68be-43f6-9cc0-5373e84f6de0" alt=""><figcaption></figcaption></figure>

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

5. To track the add-on's initialization status, use the `OnInitializedSuccess` and `OnInitializedFailed` events.

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2FuOz9QbItFAY70Vvllh0c%2Fimage.png?alt=media&amp;token=18289aac-24f8-4f04-93d8-d1a22ab5217e" alt=""><figcaption></figcaption></figure>

Done! The plugin is installed, you can proceed to [setting up ads](/madex-documentation/construct3-addon/working-with-advertising.md).

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

### If the addon is installed incorrectly

In case of errors, it is recommended to clear the browser cache.&#x20;

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

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

## Addon Installation and Configuration for Mediation

If you use mediation (working with other ad networks through Madex), you will need to download and import the latest version of the addon for mediation. Installation and configuration of the mediation addon is described in the [corresponding section](/madex-documentation/construct3-addon/installation-and-configuration-of-madex-mediation-addon-deprecated.md).

Please do this before integrating ads into your application logic.

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

<figure><img src="https://626582791-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiiOaJhSveT4OR9bjTvw%2Fuploads%2Faxl7ratHV7GmBbhBhbkz%2Fimage.png?alt=media&amp;token=a428e9cc-9ae2-4828-8a0d-a1b41185608c" alt=""><figcaption></figcaption></figure>

Set `Key` to `appStoreAppID`.

Set `Value` to with your App ID from the AppStore developer account. 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&amp;token=48a6af1b-4e34-4bb3-87b5-1bb801ec6b64" alt=""><figcaption></figcaption></figure>

### Apple Advertising Identifier (IDFA)

{% hint style="warning" %}
To enable the collection of the Apple Advertising Identifier (IDFA), you need to export your application to a Cordova project. You can find more information [here](https://chat.openai.com/c/link).
{% endhint %}

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

{% hint style="warning" %}
To enable the collection of the Apple Advertising Identifier (IDFA), you need to export your application to a Cordova project. You can find more information [here](https://chat.openai.com/c/link).
{% endhint %}

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
<platform name="android">

    <!-- ... other settings -->
    
    <!-- This line is mandatory -->
    <edit-config file="app/src/main/AndroidManifest.xml" target="/manifest" mode="merge">
        <manifest xmlns:tools="http://schemas.android.com/tools" />
    </edit-config>
    
    <!-- Permission for collecting 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 for collecting 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>
```

{% endtab %}

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

```xml
<platform name="ios">
    <config-file target="*-Info.plist" parent="NSLocationWhenInUseUsageDescription">
        <string>We need this permission for better ad targeting</string>
    </config-file>
</platform>
```

{% endtab %}
{% endtabs %}