Skip to main content

Android SDK

The Radar SDK abstracts away cross-platform differences between location services, allowing you to add geofencing, location tracking, trip tracking, geocoding, and search to your apps with just a few lines of code.

Learn how to integrate the Android SDK below. You can also see the source and a detailed SDK reference on GitHub.

Install SDK#

The best way to add the SDK to your project is via Gradle in Android Studio.

The SDK is small and typically adds less than 500 KB to your compiled app.

Gradle (recommended)#

The SDK is distributed using Maven Central.

Add the SDK to the dependencies section of your app's build.gradle file:

dependencies {    implementation 'io.radar:sdk:3.18.+'}

Add manually#

You can also add the SDK to your project manually. Download the current release and unzip the package. The package contains an aar file. In Android Studio, add the SDK as a module using File > New Module > Import .JAR/.AAR Package.

Dependencies#

The SDK depends on Google Play Services Location version 21.0.1 and higher, which will be automatically included as a transitive dependency by Gradle. Learn more about managing dependencies in Gradle here.

If you haven't already configured your project for Google Play Services, follow the instructions here.

As of version 3.8.0, the SDK uses play-services-location:21.0.1. If another dependency that depends on play-services-location is causing version conflicts, you can exclude the transitive dependencies and include the play-services-location dependency at the project level instead. We strongly recommend using 21.0.1 or higher.

As an alternative to Google Play Services, the SDK also optionally supports Huawei Mobile Services.

The SDK currently supports API level 16 or above.

Initialize SDK#

When your app starts, in application onCreate(), initialize the SDK with your publishable API key, found on the Settings page.

Use your Test Publishable key for testing and non-production environments. Use your Live Publishable key for production environments.

import io.radar.sdk.Radar
class MyApplication : Application() {
    override fun onCreate() {        super.onCreate()
        Radar.initialize(this, "prj_test_pk...")    }
}

Request permissions#

Radar respects standard Android location permissions.

For foreground tracking or trip tracking with continuous mode, Radar requires the ACCESS_FINE_LOCATION permission for precise location and/or the ACCESS_COARSE_LOCATION permission for approximate location. These permissions are automatically added by the SDK manifest along with the INTERNET, ACCESS_NETWORK_STATE, FOREGROUND_SERVICE, and RECEIVE_BOOT_COMPLETED permissions.

For background tracking or geofencing with responsive mode, and if targeting API level 29 or above, Radar also requires the new ACCESS_BACKGROUND_LOCATION permission. You must add the ACCESS_BACKGROUND_LOCATION permission to your manifest manually. To start a foreground service or use the continuous tracking preset, you must add the FOREGROUND_SERVICE_LOCATION permission:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
</manifest>

To request foreground and background permissions:

import android.Manifestimport android.app.AlertDialogimport android.content.pm.PackageManagerimport android.os.Build
import androidx.core.app.ActivityCompat
import io.radar.sdk.Radar
class MainActivity : AppCompatActivity() {  private val foregroundLocationPermissionsRequestCode = 1  private val backgroundLocationPermissionsRequestCode = 2
  override fun onCreate(savedInstanceState: Bundle?) {    super.onCreate(savedInstanceState)    Radar.initialize(this, "prj_test_pk_...")    requestLocationPermissions()  }
  private fun requestLocationPermissions() {    if (ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {      if (Build.VERSION.SDK_INT == Build.VERSION_CODES.Q) {        ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_BACKGROUND_LOCATION), backgroundLocationPermissionsRequestCode)      } else {        ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION), foregroundLocationPermissionsRequestCode)      }    }  }
  override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {    super.onRequestPermissionsResult(requestCode, permissions, grantResults)    if (requestCode == foregroundLocationPermissionsRequestCode && grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {      if (ActivityCompat.shouldShowRequestPermissionRationale(this, Manifest.permission.ACCESS_BACKGROUND_LOCATION)) {        AlertDialog.Builder(this)          .setTitle("Background location permissions needed")          .setMessage("Background location permission needed, tap \"Allow all the time\" on the next screen")          .setPositiveButton(            "OK"          ) { _, _ ->            ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.ACCESS_BACKGROUND_LOCATION), backgroundLocationPermissionsRequestCode)          }          .create()          .show()      }    }  }}

Foreground tracking#

Once the user has granted foreground permissions, you can track the user's location in the foreground.

To track the user's location in the foreground, call:

Radar.trackOnce { status, location, events, user ->    // do something with location, events, user}

You may provide an optional instance of RadarTrackCallback with an implementation of onComplete() that receives the request status, the user's location, the events generated, if any, and the user. The request status can be:

  • RadarStatus.SUCCESS: success
  • RadarStatus.ERROR_PUBLISHABLE_KEY: SDK not initialized
  • RadarStatus.ERROR_PERMISSIONS: location permissions not granted
  • RadarStatus.ERROR_LOCATION: location services error or timeout (10 seconds)
  • RadarStatus.ERROR_NETWORK: network error or timeout (10 seconds)
  • RadarStatus.ERROR_BAD_REQUEST: bad request (missing or invalid params)
  • RadarStatus.ERROR_UNAUTHORIZED: unauthorized (invalid API key)
  • RadarStatus.ERROR_PAYMENT_REQUIRED: payment required (organization disabled or usage exceeded)
  • RadarStatus.ERROR_FORBIDDEN: forbidden (insufficient permissions)
  • RadarStatus.ERROR_NOT_FOUND: not found
  • RadarStatus.ERROR_RATE_LIMIT: too many requests (rate limit exceeded)
  • RadarStatus.ERROR_SERVER: internal server error
  • RadarStatus.ERROR_UNKNOWN: unknown error

Background tracking for geofencing#

Once you have initialized the SDK and the user has authorized background permissions, you can start tracking the user's location in the background.

The SDK supports custom tracking options as well as three presets.

For geofencing, we recommend using RadarTrackingOptions.RESPONSIVE. This preset detects whether the device is stopped or moving. When moving, it tells the SDK to send location updates to the server every 2-3 minutes. When stopped, it tells the SDK to shut down to save battery. Once stopped, the device will need to move more than 100 meters to wake up and start moving again.

Assuming the user has authorized background permissions, background tracking will work even if the app has been backgrounded or killed, as Android location services will wake up the app to deliver events and the SDK uses JobScheduler to schedule network requests.

To start tracking for geofencing, call:

Radar.startTracking(RadarTrackingOptions.RESPONSIVE)

To determine whether tracking has been started, call:

Radar.isTracking()

To stop tracking (e.g., when the user logs out), call:

Radar.stopTracking()

You only need to call these methods once, as these settings will be persisted across app sessions.

Background tracking for trips#

For trips, we recommend using RadarTrackingOptions.continuous. This preset tells the SDK to send location updates to the server every 30 seconds, regardless of whether the device is moving.

Tracking for the duration of a trip is started or updated by including tracking options in the startTrip call:

Radar.startTrip(tripOptions, RadarTrackingOptions.CONTINUOUS) { status, trip, events ->  if (status == Radar.RadarStatus.SUCCESS) {    // do something  } else {    // handle error  }}

If tracking was disabled before the trip started, it will stop after the trip ends. Otherwise, it will revert to the tracking options in use before the trip started:

// Complete tripRadar.completeTrip { status, trip, events ->    // do something}
// Cancel tripRadar.cancelTrip { status, trip, events ->    // do something}

Learn more about starting, completing, and canceling trips in the trip tracking documentation.

Mock tracking for testing#

Can't go for a walk or a drive? You can simulate a sequence of location updates. For example, to simulate a sequence of 10 location updates every 3 seconds by car from an origin to a destination, call:

val origin = Location("mock")origin.latitude = 40.78382origin.longitude = -73.97536
val destination = Location("mock")destination.latitude = 40.70390destination.longitude = -73.98670
Radar.mockTracking(    origin,    destination,    Radar.RadarRouteMode.CAR,    10,    3) { status, location, events, user ->    // do something with location, events, user}

Location metadata#

The SDK can also pass along information like motion activity detection, speed and heading via the location metadata field. Turn on useLocationMetadata in your sdkConfiguration to enable this feature. Include permissions for motion activity detection in your manifest

<manifest xmlns:android="http://schemas.android.com/apk/res/android">    <uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" /></manifest>

You will need to manually prompt for motion permissions with

ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.ACTIVITY_RECOGNITION), 3)

ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.ACTIVITY_RECOGNITION), ACTIVITY_RECOGNITION_PERMISSION_CODE)

Listening for events with a receiver#

To listen for events, location updates, and errors client-side, create a class that extends RadarReceiver. Then, pass in an instance of your receiver when initializing the SDK in application onCreate().

import io.radar.sdk.Radar
class MyApplication : Application() {
    override fun onCreate() {        super.onCreate()
        val receiver = MyRadarReceiver()        Radar.initialize(this, "prj_test_pk...", receiver, Radar.RadarLocationServicesProvider.GOOGLE)    }
}

Your receiver should implement the following:

class MyRadarReceiver: RadarReceiver() {
    override fun onEventsReceived(context: Context, events: Array<RadarEvent>, user: RadarUser?) {        // do something with events, user    }
    override fun onLocationUpdated(context: Context, location: Location, user: RadarUser) {        // do something with location, user    }
    override fun onClientLocationUpdated(context: Context, location: Location, stopped: Boolean, source: RadarLocationSource) {        // do something with location, stopped, source    }
    override fun onError(context: Context, status: RadarStatus) {        // do something with status    }
    override fun onLog(context: Context, message: String) {        // print message for debug logs    }
    overide fun onLocationPermissionStatusUpdated(context: Context,status: RadarLocationPermissionStatus) {      // do something with location permission status     }
}

Manual tracking#

If you want to manage location services yourself, you can manually update the user's location instead by calling:

Radar.trackOnce(location) { status, location, events, user ->    // do something with location, events, user}

where location is a Location instance with a valid latitude, longitude, and accuracy.

Identify user#

The SDK automatically collects installId (a GUID generated on fresh install) and deviceId (Android ID).

You can also assign a custom userId, also called External ID in the dashboard. To set a custom userId, call:

Radar.setUserId(userId)

where userId is a stable unique ID for the user.

To set a dictionary of custom metadata for the user, call:

Radar.setMetadata(metadata)

where metadata is a JSONObject with up to 16 keys and values of type string, boolean, or number.

Finally, to set an optional description for the user, displayed in the dashboard, call:

Radar.setDescription(description)

You only need to call these methods once, as these settings will be persisted across app sessions.

Learn more about when Radar creates new user records here.

Debug logging#

By default, only critical errors are logged to the console. To enable debug logging, call:

Radar.setLogLevel(Radar.RadarLogLevel.DEBUG)

The Android SDK automatically logs lifecycle events without the additional setup required on iOS.

Other APIs#

The Android SDK also exposes APIs for beacons, anonymous context, geocoding, search, and distance.

Beacons#

To range and monitor beacons, you must request Bluetooth permissions. If targeting API level 31 or above, both BLUETOOTH_CONNECT and BLUETOOTH_SCAN are required runtime permissions.

The following bluetooth permissions must be added to your manifest:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.BLUETOOTH" />    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
</manifest>

To range beacons in the foreground, call:

Radar.trackOnce(RadarTrackingOptionsDesiredAccuracy.HIGH, true) { status, location, events, user ->    // do something with user.beacons}

To monitor beacons in the background, update your tracking options:

val trackingOptions = RadarTrackingOptions.RESPONSIVEtrackingOptions.beacons = trueRadar.startTracking(trackingOptions)

Learn more about beacons.

Get location#

Get a single location update without sending it to the server:

Radar.getLocation { status, location, stopped ->    // do something with location}

Context#

With the context API, get context for a location without sending device or user identifiers to the server:

Radar.getContext { status, location, context ->    // do something with context}

Geocoding#

With the forward geocoding API, geocode an address, converting address to coordinates:

Radar.geocode("20 jay street brooklyn ny") { status, addresses ->    // do something with addresses}

With the reverse geocoding API, reverse geocode a location, converting coordinates to address:

Radar.reverseGeocode(location) { status, addresses ->    // do something with addresses}

With the IP geocoding API, geocode the device's current IP address, converting IP address to city, state, and country:

Radar.ipGeocode { status, address, proxy ->    // do something with address, proxy}

Search#

With the autocomplete API, autocomplete partial addresses and place names, sorted by relevance:

Radar.autocomplete(    "brooklyn roasting", // query    near,    10 // limit) { status, addresses ->    // do something with addresses}

With the geofence search API, search for geofences near a location, sorted by distance:

Radar.searchGeofences(    near,    1000, // radius (meters)    arrayOf("store"), // tags    null, // metadata    10 // limit) { status, location, geofences ->    // do something with geofences}

With the places search API, search for places near a location, sorted by distance:

Radar.searchPlaces(    near,    1000, // radius (meters)    arrayOf("starbucks"), // chains    null, // categories    null, // groups    10 // limit) { status, location, places ->    // do something with places}

With the address validation API (currently in beta), validate a structured address in the US or Canada:

Radar.validateAddress(address) { status, address, result ->    // do something with validation result and address}

Distance#

With the distance API, calculate the travel distance and duration from an origin to a destination:

Radar.getDistance(    origin,    destination,    EnumSet.of(RadarRouteMode.FOOT, RadarRouteMode.CAR),    RadarRouteUnits.IMPERIAL) { status, routes ->  // do something with routes}

Matrix#

With the matrix API, calculate the travel distance and duration between multiple origins and destinations for up to 25 routes:

Radar.getMatrix(    origins,    destinations,    RadarRouteMode.CAR,    RadarRouteUnits.IMPERIAL) { status, routes ->  // do something with matrix.routeBetween(originIndex, destinationIndex)}

Conversions#

With the conversions API, log a conversion, such as a purchase or signup, to analyze alongside your app's location activity:

Radar.logConversion(    name,    metadata,) { status, event ->    // do something with the conversion event}
// Conversion with revenueRadar.logConversion(    name,    revenue,    metadata,) { status, event ->    // do something with the conversion event}

Notifications#

With setNotificationOptions, set the icon and the background color of foreground service and event notifications:

// Set both foreground service and event notifications
Radar.setNotificationOptions(RadarNotificationsOptions(  "icon_1", // iconString  "color_1", // iconColor))
// Or, set the foreground service notification and event notifications separately
Radar.setNotificationOptions(RadarNotificationsOptions(  foregroundServiceIconString = "icon_2",  foregroundServiceIconColor = "color_2",  eventIconString = "icon_3",  eventIconColor = "color_3",))

Huawei#

By default, the SDK depends on Google Play Services Location. However, you can use Huawei Mobile Services Location Kit instead.

If you haven't already configured your project for Huawei Mobile Services, follow the instructions here.

Then, add the dependency to your app's build.gradle file:

dependencies {    implementation 'com.huawei.hms:location:6.4.0.300'}

Finally, pass in RadarLocationServicesProvider.HUAWEI when you initialize the SDK:

Radar.initialize(context, publishableKey, receiver, RadarLocationServicesProvider.HUAWEI)