5 min read

Integrate Interface X Components for Android

In this tutorial, you’ll learn how to integrate the Interface X Components in your Android app. The Interface X Components for Android enables you to easily build any type of search experience for Android, either in Kotlin or Java.

interact

If you want to use the ready-to-go Interface X Archetype for Android as your starting point, see Integrate Interface X Archetype for Android.

Before you begin

For this tutorial, the Empathy Search API and the Empathy Search Adapter are used, but you can use any search API. If you are not using the Empathy Search API, you must either build your own search adapter from scratch by implementing interfaces from the Interface X Types library to communicate with the search API or customize the existing Empathy Search Adapter library to meet the requirements of the search API used.

This step-by-step guide requires knowledge of Gradle, Android, and Kotlin.

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

Android 5.0 Lollipop (API level 21) (opens new window) or later
AndroidX (opens new window)
Java 8 bytecode or later. See Note on Gradle support for Java 8 bytecode

Steps to integrate Interface X Components in your Android project

Declare the Empathy repository.
Install the project dependencies.
Initialize the search adapter.
Initialize the X Components library.

1. Declare the repository

All Interface X Components for Android libraries are available from the Empathy Nexus repository, with some of their transitive dependencies hosted on Google and MavenCentral.

Check the Nexus repository (opens new window) for the latest version of the Interface X Components for Android libraries.

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 several ways to declare the Empathy repository. Refer to the official documentation (opens new window) to learn more about declaring repositories.

Groovy

Include this code in 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

Include this code in the settings.gradle.kts 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 = uri("https://nexus.shared.empathy.co/repository/public")
            credentials {
                username = "user"
                password = "password"
            }
        }
    }
}

coding tip

You can declare all project dependencies in a single location, check out Central declaration of dependencies with Kotlin-DSL from Pablo García’s Medium article Make the most of your Gradle scripts (opens new window).

2. Install the dependencies

Interface X Components for Android consists of three core libraries:

x-types: The Interface X types library that contains all the contracts that the adapter needs to implement to be used with Interface X Components. It also contains all the basic model objects required for interaction with the Empathy Search API, such as RelatedTagDto, ProductCatalogDto, or Price.
x-adapter: The Empathy search adapter, i.e. low-level wrapper around the search API. It is in charge of API communications. It lets you perform operations such as request search results.
x-components: The X Components library that includes pre-built Android views to easily load and display data from the search API. It provides the ViewModels required for each view, to populate them with data and handle input events.

To use x-types, x-adapter, and x-components libraries in your application, add them as dependencies to the module's Gradle build file where the libraries are used.

Groovy

Include this code in the corresponding build.gradle file. For $x_android_version, use the version of the libraries you are using. See the Nexus repository (opens new window) for the latest version.

dependencies {
  implementation "co.empathy.android:x-types:$x_android_version";
  implementation "co.empathy.android:x-adapter:$x_android_version";
  implementation "co.empathy.android:x-components:$x_android_version"
}

Kotlin

Include this code in the corresponding build.gradle.kts file. For $x_android_version, use the version of the libraries you are using. See the Nexus repository (opens new window) for the latest version.

dependencies {
  implementation("co.empathy.android:x-types:$x_android_version"),
  implementation("co.empathy.android:x-adapter:$x_android_version"),
  implementation("co.empathy.android:x-components:$x_android_version")
}

warning

If you use the Interface X Components library, bear in mind that it uses Material elements. Make sure that you use a Material theme (opens new window) in your application before adding the components.

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

Next you need to initialize the search adapter. If you are using the x-adapter, you use the XAdapterImpl class. The XAdapterImpl class is the main entry point for all operations in the library. XAdapterImpl is a singleton: you create it once and re-use it across your application.

It is recommended you initialize the XAdapterImpl class in the Application class:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        val adapter = XAdapterImpl.Builder().build()
    }
}

The builder for XAdapterImpl exposes configuration options for features such as repositories.

warning

If you are not using the Empathy Search API, you need to build your own search adapter or customize the seach adapter library to communicate with the search API you are using.

4. Initialize the library

To use the X Components library, you need to initialize the XComponents class.

The XComponents 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()
        val adapter = XAdapterImpl.Builder().build()
        XComponents.initialize(this, adapter)
    }
}

Once you have integrated Interface X Components for Android in your application, you're ready to start building your search and discovery experience. Check out Use Interface X Components for Android to learn more about customizing and styling your user interface through XML attributes.

Note on Gradle support for Java 8 bytecode

The Interface X Components for Android libraries require 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 your build.gradle file of the module(s) where the Interface X Components libraries are 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"
    }
}