Integration tutorial | Search SDK | Android

This guide will help you to create a demo application that uses Address Autofill SDK. You can find a ready project in the Search SDK's repository DemoApps folder.

Configure credentials

Before installing the SDK, you will need to gather the appropriate credentials, see Configure credentials section for more information. You do not need to proceed with Configure your secret token, but copy and save the secret token as this will be further used as SDK_REGISTRY_TOKEN in this guide.

Set up the project and the dependencies

Once you have all the needed credentials, you can start demo app development. Complete the following instructions step by step. Depending on your experience with Android development and already installed development tools, some steps can be skipped.

Download the Android Studio. It's preferable to choose the latest available stable Android Studio version. Address Autofill SDK requires Java 8 or later to run. New versions of the Android Studio have embedded Java 11.
Create a new project. Select Empty Activity in the New Project window as a template. Click Next button.

In the next window enter project name and package name. In this tutorial we use AddressAutofill as a name and com.mapbox.demo.autofill as a package name. Choose project location on your laptop, Kotlin as a language, and Minimum SDK at least API 21. Click Finish button. Once its done, Android Studio opens the project and all its files.

This step is required only if your Android Gradle Plugin version is less than 4.2.0 (March 2021). To check the Gradle Plugin version go to: File > Project Structure > Project > Android Gradle Plugin Version.

Address Autofill SDK uses Java 8 features. To enable Java 8 in your project, add the following compileOptions in your module-level build.gradle (in our sample there will be only one module called app, so the gradle configuration file is located at app/build.gradle):

android {
  // ...
  // Configure only for each module that uses Java 8
  // language features (either in its source code or
  // through dependencies).
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "1.8"
  }
}

To download the SDK, you must configure a new maven repository with a valid username and password. In our demo we assume that the token is stored in environment variables with key SDK_REGISTRY_TOKEN (the secret token you saved). You can add those by appending the following lines to your shell configuration file ~/.zshrc:

export SDK_REGISTRY_TOKEN=sk...
export MAPBOX_ACCESS_TOKEN=pk...

Be sure to check in (Android Studio) Terminal that the variables are there by running echo $SDK_REGISTRY_TOKEN.

If your build is configured to prefer settings repositories over project repositories (default for new Android Studio projects with gradle version starting from 6.8), then insert the following entry inside the dependencyResolutionManagement repositories block (see demo app configuration file as an example):

def sdkRegistryToken = System.getenv('SDK_REGISTRY_TOKEN')
if (sdkRegistryToken == null || sdkRegistryToken.empty) {
  throw new Exception("SDK Registry token is not specified.")
}

maven {
  url 'https://api.mapbox.com/downloads/v2/releases/maven'
  authentication {
    basic(BasicAuthentication)
  }
  credentials {
    // Do not change the username below. This should always be `mapbox` (not your username).
    username = "mapbox"
    password = sdkRegistryToken
  }
}

Otherwise, add that entry inside the allprojects repositories block in the project-level build.gradle file located in the project's root directory.

Add the public access token to string constants so that we can use it later in our code to initialize the SDK. Similarly to the previous step, we assume that the public access token is stored in environment variable with key MAPBOX_ACCESS_TOKEN. In the app module build.gradle:

declare mapboxApiToken variable above the android block
use that value inside the android defaultConfig block:

def mapboxApiToken = System.getenv('MAPBOX_ACCESS_TOKEN')
if (mapboxApiToken == null) {
    throw new Exception("API token is not specified.")
}

android {
  namespace 'com.mapbox.demo.autofill'
  compileSdk 32

  defaultConfig {
    resValue "string", "mapbox_access_token", mapboxApiToken
    // ...
  }
}

See demo app build.gradle as an example.

Add the Address Autofill SDK dependency under dependencies block in your module-level build.gradle file.

dependencies {
  implementation "com.mapbox.search:autofill:1.0.0-beta.39"
}

In general it's enough to use the Address Autofill SDK but our demo uses Search UI, Maps, Android lifecycle Kotlin extensions SDKs, so we need to add them inside dependencies block as well:

dependencies {
    implementation "com.mapbox.search:autofill:1.0.0-beta.39"
    implementation "com.mapbox.maps:android:10.9.0"
    implementation "com.mapbox.search:mapbox-search-android-ui:1.0.0-beta.39"
    implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.4.1"
}

The demo app's code was tested for the SDK versions declared in the block above. If you want to use newer SDK versions, make sure you pick compatible versions of the Search and Maps SDK using this instruction.

See demo app build.gradle as an example.

Because you've edited Gradle files, Android Studio will ask you whether you want to sync the Gradle files. Press Sync now at the pop-up to resolve.

Now the SDK dependency is resolvable by the Android project. We can start adding new functionality to our project.

Add the functionality

Declare location permissions in your application's AndroidManifest.xml file. If the location permission granted, by default the Address Autofill SDK will include current user location in the search requests to get more relevant search results. Insert the following lines inside the root <manifest> xml tag:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

See demo app AndroidManifest.xml as an example.

Replace the files in your project with the files from the Demo App according to the following file tree (copy files if they are not present in your project):

app
+- src
   +- main
      +- java
      |  +- com
      |    +- mapbox
      |        +- demo
      |           +- autofill
      |              +- MainActivity.kt
      +- res
         +- layout
         |  +- activity_main.xml
         |
         +- drawable
         |  +- card_background.xml
         |  +- red_marker.png
         |
         +- values
         |  +- colors.xml
         |  +- strings.xml
         |  +- themes.xml
         |
         +- values-night
            +- themes.xml (remove this one!)

Replace string constants declared in strings.xml with the strings declared in the demo app.
Replace color constants declared in colors.xml with the colors declared in the demo app.
Replace default theme declared in themes.xml with the themes from the demo app. You can remove themes.xml from the night mode configuration as we don't support dark theme in our demo app.
Copy card_background.xml from the demo project into the drawable directory.
Copy red_marker.png rom the demo project into the drawable directory.
Replace content of the activity_main.xml file with the activity_main.xml from the demo project.
Replace content of the MainActivity.kt file with the MainActivity.kt from the demo project.

Build the project. In Android Studio menu choose Build -> Make project
Run the app in Android emulator or connected device:

select app configuration in toolbar (next to build icon)
choose available emulator device (or create a new one)
Hit Run app.