1.1 Integrating Maven Artifact in Your Project

This detailed guide is designed to walk you through the steps of adding the NIMMSTA Maven dependency to your project, ensuring a seamless integration process.

Essential Prerequisites

• This integration works with native Kotlin / Java Android Projects. For Xamarin or .NET MAUI, please consider using a websocket integration.
• Android SDK Requirements: The baseline SDK level required for Android devices is 21. However, for optimal performance and compatibility, an SDK level of 26 or above is recommended.
• Access to NIMMSTA Maven Repository: It's crucial that you have the necessary credentials for the NIMMSTA Maven Repository. These credentials are key to accessing and integrating the Maven dependency.
• Latest Firmware Bundle: To ensure compatibility and the latest features, download and install the newest firmware bundle available at the NIMMSTA B2B Portal.
• Gradle Compatibility: Your project should be using Gradle version 7.0 or above. This version ensures better performance and more features that are compatible with the NIMMSTA Maven dependency.
• Kotlin Compatibility: Your project should be using Kotlin version 1.8 or above.

Gaining Access to the NIMMSTA Maven Repository

In order to download the necessary artifacts from the NIMMSTA Repository, specific access credentials are required. These credentials can typically be obtained through direct communication with your service partner or a representative at NIMMSTA. This step is crucial as it provides the authentication required to securely access and download the Maven artifacts needed for your project.

Starting with Kotlin Gradle Plugin

The first step in your setup should be the addition of the Kotlin Gradle Plugin. This plugin is essential for integrating Kotlin code and modules effectively in your project. It provides necessary tools and features to compile, test, and debug your Kotlin code within the project environment. Make sure to verify the compatibility of the Kotlin Gradle Plugin version with your current Gradle setup to ensure a smooth integration process.

build.gradle (Root Folder)build.gradle.kts (Root Folder)

buildscript {

    /* ... */

    repositories {
        /* ... */
    }

    dependencies {
        /* ... */

        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.22" // You can use the latest version
    }
}

buildscript {

    /* ... */

    repositories {
        /* ... */
    }

    dependencies {
        /* ... */

        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.22") // You can use the latest version
    }
}

Configuring Repository Settings

The following step involves adding the NIMMSTA Maven Repository to your project's settings. This is a crucial step for ensuring that your project can access and utilize the NIMMSTA Maven dependency effectively.

Adding the NIMMSTA Maven Repository

1. Repository Configuration: Integrate the NIMMSTA Maven Repository into your project's repository settings. This involves specifying the repository URL and ensuring that it's correctly configured within your project's build system.

2. Authentication with Credentials: Utilize your NIMMSTA access credentials during this step. These credentials are essential for authenticating your access to the repository. They ensure secure and authorized communication between your project and the NIMMSTA Maven Repository, allowing for the download and integration of necessary dependencies.

settings.gradlesettings.gradle.kts

repositories {
    /* ... */
    google()
    mavenCentral()
    maven {
        url 'https://maven.nimmsta.com/repository/nimmsta-core-release/'
        credentials {
            username = "yourusername"
            password = "yourpassword"
        }
        authentication {
            basic(BasicAuthentication)
        }
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}
/* ... */

repositories {
    /* ... */
    google()
    mavenCentral()
    maven {
        url = uri("https://maven.nimmsta.com/repository/nimmsta-core-release/")
        credentials {
            username = "yourusername"
            password = "yourpassword"
        }
        metadataSources {
            mavenPom()
            artifact()
        }
    }
}
/* ... */

Integrating Android Maven Dependency

Once the repository configuration is complete, the next step involves incorporating the Maven artifact into your project's build system. This integration is vital for the proper functioning of the project with the NIMMSTA dependency.

Inclusion of Maven Artifact

• Artifact Implementation: Add the specified Maven artifact to your project's build system. This step is crucial for the artifact to be recognized and used within your project's environment.

• Kotlin Plugin Integration: Ensure that the Kotlin plugin is integrated into your build system. This is important regardless of whether your project is based on Kotlin or Java. The Kotlin plugin plays a key role in dependency management, helping the system to identify and select the appropriate artifacts for your project.

Warning

Important Note for Java Users: The Kotlin plugin is necessary even if your application is developed in Java. This plugin is crucial for managing dependencies effectively in your build system, ensuring compatibility and optimal functioning of the NIMMSTA Maven artifact.

Note

Update Notifications in IDE: If your Integrated Development Environment (IDE) suggests that a newer version of the 'shared-android' project is available, consider updating to the latest version. Staying up-to-date with these versions ensures that your project benefits from the latest features, improvements, and bug fixes. It's always recommended to use the most recent stable version available for better performance and enhanced security.

yourapp/build.gradleyourapp/build.gradle.kts

plugins {
    /* ... */
    id 'kotlin-android'
}

dependencies {
    /* ... */
    api("com.nimmsta.core:shared-android:7.0.+@aar") {
        transitive = true
        changing = true
    }
}

plugins {
    /* ... */
    id("kotlin-android")
}

dependencies {
    api("com.nimmsta.core:shared-android:7.0.+@aar") {
        isTransitive = true
        isChanging = true
    }
}

Android Packaging Options

In order to avoid issues during the application packaging process, it's essential to implement specific packaging options. This step addresses a particular dependency that requires special consideration in the packaging phase.

yourapp/build.gradleyourapp/build.gradle.kts

android {
    /* ... */
    packagingOptions {
        exclude 'META-INF/*.kotlin_module'
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }

    /* needed in case of build errors depending on Android Target */
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

android {
    /* ... */
    packagingOptions {
        exclude("META-INF/*.kotlin_module")
        exclude("META-INF/DEPENDENCIES")
        exclude("META-INF/INDEX.LIST")
        exclude("META-INF/io.netty.versions.properties")
    }
    /* needed in case of build errors depending on Android Target */
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

Enabling Android X

To use the UI of our activities, ensure that Android X is enabled in your project settings. This is done by modifying the gradle.properties file.

Configuring gradle.properties for Android X

• File Modification: Access the gradle.properties file in your project.

• Add Configuration Line: Insert the following line into the gradle.properties file:

gradle.properties

android.useAndroidX=true

This setting activates Android X, which is essential for the UI components of your activities.

Use AppCompat Theme

Please use an AppCompat theme for your application, for example:

AndroidManifest.xml

<application
            ...
            android:theme="@style/Theme.AppCompat.Light.NoActionBar">
<!-- ... -->
</application>

Optional: Remove unused packages

As the android package contains dependencies not necessarily needed for your app, you can exclude the following dependencies:

yourapp/build.gradle

plugins {
    /* ... */
    id 'kotlin-android'
}

dependencies {
    /* ... */
    api("com.nimmsta.core:shared-android:7.0.+@aar") {
        transitive = true
        changing = true

        exclude group: 'io.ktor', module: 'ktor-server-core'
        exclude group: 'io.ktor', module: 'ktor-server-netty'
        exclude group: 'io.ktor', module: 'ktor-server-websockets'
        exclude group: 'io.ktor', module: 'ktor-server-cors'

        exclude group: 'io.ktor', module: 'ktor-client-android'
    }
}