Beeline Android SDK

Integrate Beeline routing and navigation into your Android app

Requirements

• Supports Android 21 (5.0 Lollipop) and above

• Supports armeabi-v7a, arm64-v8a, x86, x86_64

• Written in Kotlin and C++

Installation

Contact us for credentials tech@beeline.co

Add Beeline SDK dependency

Register the Beeline maven repository in your project level build.gradle file:

allprojects {

  repositories {

    // other repositories omitted

    maven {
      name = "GitHubPackages"
      url = uri("https://maven.pkg.github.com/RideBeeline/packages")
      credentials {
        username = 'username'
        password = 'password'
      }
    }
  }

}

In your module level build.gradle file:

dependencies {
  implementation 'co.beeline:beeline-sdk:2.0.0'
}

Integration

Specify permissions

The Beeline SDK requires the INTERNET and ACCESS_FINE_LOCATION permissions.

In your AndroidManifest.xml

<!-- Under manifest tag -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

We leave it to you to ensure you request the appropriate location permissions from your users.

See https://developer.android.com/training/permissions/requesting

Beeline Routing

Beeline routing provides cycling and motorcycling optimised routes.

The Beeline routing API will return up to three routes. Please note that in some cases, especially for shorter routes, routes can be close to identical. In this case less than three will be returned.

Example setup

Note, the instance and key parameters will be provided to you by Beeline.

val apiClient = BeelineRoutingApiClient(
  instance: SimpleProperty(RoutingInstance.production),
  userAgent: "<YOUR USER AGENT>",
  clientType: "<YOUR APP NAME>",
  clientVersion: context.appVersion,
  key: { _ in "KEY_PROVIDED_BEELINE" },
  unexpectedErrorHandler: { error -> },
)

val routeProvider: RouteProvider = BeelineRouting(
  routingApi: apiClient,
  userIdProvider: { nil }
)

Example request for a single route

This will provide the best available route

val parameters = RouteParameters(
    vehicle: BICYCLE,
    type: OneWay,
    start: Coordinate(51.50072, -0.12462),
    end: Coordinate(51.50206, -0.14009),
)

// Error handling omitted
val routes = routeProvider.routes(parameters)

Displaying a Beeline route on a map

You can get a list of coordinates that describes the track of the route

val coordinates = routes[0].course.track

Beeline Navigation

Once you have a route you can start navigation. If you go off reroute, it will reroute automatically.

val locationProvider: LocationProvider = DefaultLocationProvider()

val orientationProvider = NativeOrientationFuser(
  locationProvider = locationProvider,
  geomagneticsProvider = AndroidGeomagneticsProvider(),
  sensorsReadingsProvider = AndroidSensorsReadingsProvider(context),
  bridge = AndroidNativeOrientationFuserBridge(),
  onError = { error -> }
)

val navigator = TrackNavigator(
  dispatcher = Dispatchers.Default,
  locations = locationProvider.filteredLocationsFlow,
  routeProvider = routeProvider,
  rerouteBehavior = DefaultRerouteBehavior(
    isAutoRerouteEnabled = { true },
    isAutoRerouteEnabledWhenStartingOffRoute = false,
  ),
  offRouteTolerance = NavigationSettings.OFF_ROUTE_TOLERANCE,
  nudgeTolerance = NavigationSettings.NUDGE_TOLERANCE,
  trafficRerouteCheckInterval = NavigationSettings.TRAFFIC_REROUTE_CHECK_INTERVAL,
  trafficRerouteMinimumDeviationDistance = NavigationSettings.TRAFFIC_REROUTE_MINIMUM_DEVIATION_DISTANCE,
  initialRoute = routes[0],
  originalRoute = routes[0],
)

navigator.start()

// Listen for navigator updates via navigator.snapshotFlow

navigator.stop()

Running in the background

If your app is moved to the background, location updates will stop unless you have a foreground Service running with the android:foregroundServiceType="location" attribute. For the best experience we recommend enabling location updates whilst the app is in the background, but this is not mandatory.

For more information see the Android documentation on accessing location in the background here.