Start your content search
3 min read

Integrate Interface X Archetype for Android

Integrate Interface X Archetype for Android

In this tutorial, you’ll learn how to integrate Interface X Archetype in your Android app in a matter of minutes so you can have a search and discovery experience based on predefined features and components for Android, either in Kotlin or Java.

interact

If you need a more custom approach, see Integrate Interface X Components for Android.

Before you begin

For this tutorial, the Empathy Search API is used, but you can use any search API. This step-by-step guide requires knowledge of Gradle, Android, and Kotlin.


To integrate Interface X Archetype in your Android app, you need:


Steps to integrate Interface X Archetype for Android
  1. Declare the Empathy repository.
  2. Install the project dependencies.
  3. Initialize the X Archetype library

1. Declare the repository

The Interface X Archetype for Android library is available from the Empathy Nexus repository, with some of their transitive dependencies hosted on Google and MavenCentral.

Check the Empathy Nexus repository (opens new window) for the latest version of the Interface X Archetype for Android library.

warning

Empathy Nexus repository is a private repository. You need to use the credentials that were provided to you by Empathy.

Depending on your project, there are different ways to declare the Empathy Nexus repository. Refer to the official documentation (opens new window) to learn more about declaring repositories.

Groovy

Add the following code to the settings.gradle file. For username and password, use the credentials that have been provided to you to access the Empathy Nexus repository.


dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://nexus.shared.empathy.co/repository/public"
            credentials {
                username "user"
                password "password"
            }
        }
    }
}
Kotlin

Add the following code to the settings.gradle.kts file. For username and password, use the credentials you have been provided to access the Empathy Nexus repository.


dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://nexus.shared.empathy.co/repository/public")
            credentials {
                username = "user"
                password = "password"
            }
        }
    }
}

2. Install the dependencies

The X Archetype consists of one library containing the X Components for Android and the Empathy search adapter fully instrumented and ready to use for a complete search and discovery experience. To use this library in your Android application, add it as a dependency to the corresponding module's Gradle build file.

Groovy

Add the following code to the build.gradle file of the module where the Interface X Archetype for Android library is used. For $x_customer_name and $x_android_version, use the customer name and the version of the library that have been provided to you.


dependencies {
  implementation "co.empathy.mobile:x-android-$x_customer_name:$x_android_version"
}
Kotlin

Add the following code to the build.gradle.kts file of the module where the Interface X Archetype for Android library is used. For $x_customer_name and $x_android_version, use the customer name and the version of the library that have been provided to you.


dependencies {
  implementation("co.empathy.mobile:x-android-$x_customer_name:$x_android_version")
}

warning

The Interface X Archetype for Android library uses Material elements. Make sure that you use a Material theme (opens new window) in your application before adding the library.


Your app’s theme should extend a theme from Theme.MaterialComponents, rather than Theme.AppCompat.

For example:


<style name="AppTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar" />

If you want to keep using an AppCompat theme for styling, you should use a Bridge theme (opens new window) to support using Material-based components at the same time.

3. Initialize the library

To have a fully-featured search and discovery experience implemented in your Android app, initialize the EmpathyX class. The EmpathyX class is a singleton by itself; you only need to call the initialize method to configure the library behavior:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        EmpathyX.initialize(this)
    }
}

Note on Gradle support for Java 8 bytecode

Interface X Archetype for Android requires Java 8 bytecode or later. Refer to the official documentation (opens new window) to learn more about Java 8 support.

For Gradle version 7.0 or later, the Java compiler produces Java 8 bytecode. For older versions, you must configure the Java Compiler to produce Java 8 bytecode by configuring the build.gradle file of the module where the Interface X Archetype for Android library is used:

Groovy 
android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}
Kotlin 
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}
Cookie-Less