Observation Graph SDK for Android

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


Requirements

  • The Observation Graph SDK is compatible with API level 21 or higher.
  • After compilation, the SDK should add under 1.0 MB to your app’s size.
  • The SDK requires ACCESS_FINE_LOCATION and INTERNET permissions.


Get an API key and SDK Download

Your Factual account representative will provide you with an API key and a download of the SDK.


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.
    mavenCentral()

    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 SDK:
    /* Play Services for Location */
    implementation 'com.google.android.gms:play-services-location:12.0.1'

    /* Volley for HTTP requests */
    implementation 'com.android.volley:volley:1.1.0'

    implementation 'org.apache.thrift:libthrift:0.9.3'

    /* Room for data persistence */
    implementation 'android.arch.persistence.room:runtime:1.0.0'

    // The OG AAR:
    implementation(name: 'factual-og-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 {
    exclude 'META-INF/DEPENDENCIES'
  }
}


Location Permissions

Your AndroidManifest.xml should include the following:

Permissions:

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

Receiver and Service:

...
    <receiver android:name="com.factual.android.LocationUpdateReceiver"/>
    <service
      android:name="com.factual.android.ObservationGraphJobService"
      android:label="Observation Graph Job Service"
      android:permission="android.permission.BIND_JOB_SERVICE"/>
  </application>
  ...
</manifest>

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.


Sample Implementation Code

Following is an example Android Activity running the Observation Graph SDK.

A few things to note:

  • The package name in the example would be replaced by your own.
  • The SDK detects which location permissions your app has requested and behaves appropriately. It will not request any location authorizations on its own. For illustrative purposes, the code example below shows you how this can be accomplished.


Insert your API Key

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

public static final String API_KEY = "your-api-key";


Example Project

Please reference the code example at https://github.com/Factual/sdk-examples