Engine SDK for Android

The steps below will guide you through installing the Engine SDK into your app via Android Studio and Java.


  • The Engine SDK is compatible with API level 20 or higher.
  • After compilation, the SDK should add approximately 1.5 MB to your app’s download size.
  • The SDK requires ACCESS_FINE_LOCATION and INTERNET permissions.

Get an API key

Sign up for access to Engine here.

Get the SDK

Currently the Engine SDK is provided as a downloadable Android Archive (AAR). Once you’ve verified your account, you can access your API key and download the SDK here.

Copy the AAR to Your Project

Copy the AAR to your preferred location for libraries. E.g., app/libs.

Add Repositories and Dependencies

Add Maven and the path to the AAR as repositories in your app/build.gradle as follows:

repositories {
  // Volley and Thrift are found here

  flatDir {
  // Path to the AAR, relative to your project's "app" dir.
  dirs "libs"

dependencies {

Add the AAR and dependencies to app/build.gradle as follows:

dependencies {
  // Existing Dependencies

  // Third party libraries used by the Engine SDK:
  implementation 'com.android.volley:volley:1.1.0'
  implementation('com.google.android.gms:play-services-location:11.0.4', {
    exclude group: 'com.android.support', module: 'support-v4'
  implementation 'org.apache.thrift:libthrift:0.9.3'
  implementation 'com.google.android.gms:play-services-analytics:11.0.4'
  // The Engine AAR:
  implementation(name: 'factual-engine-sdk-android', ext: 'aar')

You may need to exclude META-INF/DEPENDENCIES by adding a packagingOptions block under android in your app/build.gradle as follows:

android {
  packagingOptions {

If you would like notifications from Engine in the app’s background state we recommend implementing Engine via a Broadcast Receiver. Please reference the code examples at https://github.com/Factual/engine-examples

Location Permissions and Service Registration

In AndroidManifest.xml under the application label, add the following service and receiver information:

    <service android:name="com.factual.engine.FactualEngine"/>
    <receiver android:name="com.factual.engine.FactualClientReceiver"/>

Additionally, AndroidManifest.xml should include the following permissions:

  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-feature android:name="android.hardware.location.gps" />
  <uses-feature android:name="android.hardware.location.network" />

The SDK does NOT prompt for these permissions on its own. We’ve deliberately left that to you, so that you can lump in any other permissions you may require, as well as choose the method and timing of the prompt as you require.

Example Implementation Code

The example Android Activity below will:

  • Initialize and start Engine, in conjunction with the required permission checks
  • Make and handle a request for current location candidates
  • Programmatically define a Circumstance
  • Define and register a simple handler for when the Circumstance is met

A few things to note:

  • The SDK detects which location permissions your app has requested. It will not request any location authorizations on its own. This example contains boilerplate code for seeking the permissions.
  • The FactualEngineDelegate interface provides debugging info to your app.

Insert your API Key

In the code example above, you’ll need to provide your API key:

FactualEngine.initialize(this, "your API Key Goes Here");