Package Index - Steerpath SDK

Steerpath Indoor Navigation SDK.

Steerpath Demo App is available in Google Play. (uses SDK version: 3.0.0-rc22.1)
Steerpath Example App: https://bitbucket.org/nimbledevices/steerpath-android-example.git

Mapbox SDK Documentation: https://www.mapbox.com/android-sdk/api/5.3.0/

Change log

Show the changelog

Permissions

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Dependencies

    build.gradle:

    repositories {
        maven { url "http://steerpath.bintray.com/steerpath" }
    }

    dependencies {
        compile ('com.steerpath:steerpath:android-3.4.4.0@aar') {
            transitive=true
        }
    }
    Uses support library version 25.4.0:
        compile 'com.android.support:cardview-v7:25.4.0'
        compile 'com.android.support:gridlayout-v7:25.4.0'
        compile 'com.android.support:recyclerview-v7:25.4.0'
        compile 'com.android.support:design:25.4.0'
        compile 'com.squareup.okhttp3:okhttp:3.10.0'

    Other dependencies:
        SDK depends on ContextCompat.checkSelfPermission(), which means minimum compileSdkVersion should be 23.
        For more information, visit: https://developer.android.com/reference/android/support/v4/content/ContextCompat.html#checkSelfPermission(android.content.Context, java.lang.String)

        Uses net.lingala.zip4j 1.3.1

Styling

R.color

    R.color.iconized_button                                 Floating Action Buttons tint color
    R.color.location                                        UserLocationView color. The ball in middle of accuracy view and pulse.
    R.color.accuracy_view                                   AccuracyView around UserLocationView
    R.color.accuracy_view_pulse                             AccuracyView animation
    R.color.route                                           Route color is applied to route line and current route segment, route start and end points
    R.color.marker_border                                   SteerpathMarkerView border color
    R.color.divider                                         LevelPickerView divider and pre-lollipop padding color
    R.color.error_button                                    Floating Action Buttons tint color for errors and if runtime permissions are not granted
    R.color.disabled_button                                 Floating Action Buttons tint color for if Bluetooth or Location are disabled
    R.color.current_floor_indicator                         LevelPickerView indicates the floor where user currently is
    R.color.current_floor_indicator_focused                 LevelPickerView indicates floor where user currently is
    R.color.next_waypoint                                   Route line color of next segment(s)
    R.color.attribution_text                                Text color in attributions dialog
    R.color.mapview_loading_screen_background               SteerpathMapView‘s loading screen background color

R.drawable

    Drawables are in svg format. Color references does not work on pre-Lollipop, so tint color is applied to View instead.
    If you override these drawables, make sure that it contains only one color and transparency.

    Buttons:

    R.drawable.ic_bluetooth_off.xml
    R.drawable.ic_gps_off.xml
    R.drawable.ic_gps_fixed.xml
    R.drawable.ic_gps_not_fixed.xml

R.style

    R.style.Steerpath.Style.LevelPicker.Text.Selected       Inherits by default @android:style/Widget.TextView
    R.style.Steerpath.Style.LevelPicker.Text.Unselected     Inherits by default @android:style/Widget.TextView

        Recommended attributes to override:
            android:textColor
            android:background                              Must be @color
            android:textSize

    R.style.Steerpath.Style.LevelPicker.Text.Transition     Inherits by default @android:style/Widget.TextView
    R.style.Steerpath.Style.MapView.LoadingScreen.Text      Shown in SteerpathMapView while installing OfflineBundle

    // Used with DirectionsAdapter:
    R.style.Steerpath.Style.Directions.Text.Current
    R.style.Steerpath.Style.Directions.Text
    R.style.Steerpath.Style.Directions.Image.Current        Required attributes: android:layout_width, android:layout_height, android:layout_marginLeft
    R.style.Steerpath.Style.Directions.Image                Required attributes: android:layout_width, android:layout_height, android:layout_marginLeft
    R.style.Steerpath.Style.Directions.Header               Header text in Directions list

    R.style.Steepath.Theme.Dialog                           Override if not happy with the SDK default look & feel. Used by CompassCalibrationDialog.

    R.style.Steerpath.Style.Attribution.Text                Appearance of copyright text in bottom-left corner. RelativeLayout LayoutParams may be used to change location of the text.

    R.style.Steerpath.Style.Button.Directions               Get Directions- button in default RoutePreviewHolder
    R.style.Steerpath.Style.Button.Cancel                   Cancel button in default RoutePreviewHolder and RouteStepViewHolder
    R.style.Steerpath.Style.Button.Cancel.Inverted          Cancel button in default RoutePreviewHolder and RouteStepViewHolder

    R.style.Steerpath.Style.RouteBadge.Text.Large           Large text in RoutePreviewHolder and RouteStepViewHolder
    R.style.Steerpath.Style.RouteBadge.Text.Medium          Medium text in RoutePreviewHolder and RouteStepViewHolder
    R.style.Steerpath.Style.RouteBadge.Text.Small           Small text in RoutePreviewHolder and RouteStepViewHolder
    R.style.Steerpath.Style.StepByStep.Background           RouteStepViewHolder background

Other things, values, dimens and attrs

    R.dimen.level_picker_width                              LevelPickerView is center aligned with Floating Action Buttons below. It cannot be wider than FAB, which is 60dp by default.
    R.integer.level_picker_padding_pre_lollipop             Since drop shadow nine patching works poorly on pre-Lollipop devices, you can surround LevelPickerView with solid color instead.
    R.integer.accuracy_view_alpha                           Valid range: 0-255
    R.integer.map_widget_margin_left                        Map Widget margin
    R.integer.map_widget_margin_right                       Map Widget margin
    R.integer.map_widget_margin_top                         Map Widget margin
    R.integer.map_widget_margin_bottom                      Map Widget margin
    R.integer.map_widget_compass_margin_right               Magic number that horizontally center aligns Compass with LevelPickerView and Floating Action Buttons
    R.integer.map_widget_level_picker_margin_top            Magic number that prevents LevelPickerView from overlaying Compass
    R.integer.bottom_bar_peek                               Height of the peeking BottomSheetView
    R.bool.show_route_end_point                             Show final point (circle with a ball inside) of the route line

Localisation

    // Dialogs
    R.string.sp_permission_dialog_title                     "Indoor positioning"
    R.string.sp_permissions_dialog_rationale                "App features indoor positioning by Steerpath Ltd. To make use of this feature, give permissions."
    R.string.sp_location_required_dialog_title              "Unable to locate you!"
    R.string.sp_location_required_dialog_body               "To show your location on map, turn on Location."
    R.string.sp_bluetooth_required_dialog_title             "Indoor positioning"
    R.string.sp_bluetooth_required_dialog_body              "App features indoor positioning by Steerpath Ltd. To make use of this feature, enable Bluetooth."
    R.string.sp_not_supported_dialog_title                  "Indoor positioning"
    R.string.sp_not_supported_dialog_body                   "Unfortunately indoor positioning is not available for your device!"
    R.string.sp_error_no_browser                            "No web browser installed on device, can\'t open web page."

    // Buttons. For more information, visit: https://material.io/guidelines/style/writing.html
    R.string.sp_got_it                                      "Got it"
    R.string.sp_close                                       "Close"
    R.string.sp_enable                                      "Enable"
    R.string.sp_not_now                                     "Not Now"
    R.string.sp_done                                        "Done"
    R.string.sp_start                                       "Start"

    // Step-by-Step directions
    R.string.sp_directions                                  "Directions"
    R.string.sp_continue                                    "continue"
    R.string.sp_turn_left                                   "turn left"
    R.string.sp_turn_slight_left                            "turn slightly left"
    R.string.sp_turn_sharp_left                             "turn sharp left"
    R.string.sp_turn_right                                  "turn right"
    R.string.sp_turn_slight_right                           "turn slightly right"
    R.string.sp_turn_sharp_right                            "turn sharp right"
    R.string.sp_go                                          "go". At first glance, "go" is conceptually pretty close to "enter". "Go" refers to taking some (non-walk) vehicle, for example elevator, escalator, skytrain or whatever.
    R.string.sp_go_up                                       "go up"
    R.string.sp_go_down                                     "go down"
    R.string.sp_enter                                       "Enter". Think "enter" as "enter an area". Example: enter Floor 3 (from elevator)
    R.string.sp_destination_reached                         "Destination reached"
    R.string.sp_step_format                                 "Walk %1$dm and %2$s", Example: Walk 100m and turn right, Where %2$s is: sp_continue | sp_turn_left | sp_turn_slight_left | sp_turn_sharp_left | sp_turn_right | sp_turn_slight_right | sp_turn_sharp_right
    R.string.sp_destination_format                          "%1$s%2$s to destination (~%3$d %4$s)", where 1$s is distance, 2$s is distance unit, %3$d is overall distance remaining, %4$s is time unit. Example: 100m to destination (~30 sec)
    R.string.sp_take_transportation_format                  "Take %1$s to %2$s", Example: Take elevator to Floor 3
    R.string.sp_while_in_transportation_format              "%1$s to %2$s", Example: elevator to Floor 3
    R.string.sp_seconds                                     "sec"
    R.string.sp_minutes                                     "min"
    R.string.sp_meters                                      "m"
    R.string.sp_kilometers                                  "km"
    R.string.sp_next_waypoint                               "Next: %1$s"
    R.string.sp_rerouting                                   "Rerouting..."

    R.string.sp_step_current_action_int_format              Walk %1$dm
    R.string.sp_step_current_action_string_format           Walk %1$s
    R.string.sp_step_next_action_format                     and %1$s
    R.string.sp_step_distance_to_next_format                %1$d m
    R.string.sp_step_total_distance_estimation_format       %1$s %2$s
    R.string.sp_step_total_travel_time_estimation_format    %1$d %2$s

    // Compass Calibration Dialog
    R.string.sp_compass_calibration_title                   "Calibrate your blue dot\'s compass"
    R.string.sp_compass_calibration_body                    "Tilt and move your phone 3 times like this:"
    R.string.sp_compass_accuracy                            "Accuracy: %1$s", where %1$s is sp_low | sp_medium | sp_high | sp_unreliable
    R.string.sp_low                                         "Low"
    R.string.sp_medium                                      "Medium"
    R.string.sp_high                                        "High"
    R.string.sp_unreliable                                  "Unreliable"

    // SDK log sharing
    // Modify this if your app cannot be installed to device due to conflicting fileprovider authorities
    R.string.sp_fileprovider_authority                      "com.steerpath.sdk.fileprovider"

    R.string.sp_route_floor_up_text                         "Up". Text to be shown with floor up -icon. Valid with MARKER_RENDER_MODE_SYMBOL_LAYER.
    R.string.sp_route_floor_down_text                       "Down". Text to be shown with floor down -icon. Valid with MARKER_RENDER_MODE_SYMBOL_LAYER.

Packages

Troubleshoot

How to get debug from the SDK?

        SDK has in-built monitoring system for gathering relevant debug information and it simply prints messages to the console. This is called "Monitor".
        - enable with SteerpathClient.StartConfig.Builder().monitor(true);
        - filter logcat with "Monitor". For example: adb logcat *:S Monitor:V
        - SteerpathMapView has helper functionality to display monitor output on top of the map. See SteerpathMapView.showMonitorButton();
        - in production it is recommended to disable monitor as it may expose somewhat sensitive information
    

How to know if location comes from the GPS instead of Bluetooth?

        - bouncing or restless blue dot
        - blue dot in each floor
        - LevelPickerView does not have "current level indicator"
    

I don‘t have live beacon. How to develop my app without one?

        SteerpathMapView has setupClickForFakeLocation() method. This way position can be faked simply by touching the map. NOTE: this disables Bluetooth!

        At the moment SDK does not provide in-built utility for faking the location *without* a map, but such functionality can be implemented of app side
        with LocationSource - api.
    

I can‘t get position at all?

        Requirements for positioning:
        - Nearby beacons are required
        - Application needs permissions. See Permissions section above.
        - Bluetooth must be on. By default, SDK uses no GPS. See LocationRequest for more information.
            If GPS positioning is enabled with LocationRequest, Location Services must be enabled as well.

        If SteerpathMapView or SteerpathMapFragment is used, consider following:
        - SteerpathMap.setMyLocationEnabled(true) needs to be called
        - SteepathMapView.setupClickForFakeLocation() will disable real positioning
        - In-built LocateMe-button will indicate if permissions are not granted or Bluetooth is disabled.

        Position can be also obtained without a map widget.
        - To do so, use FusedLocationProviderApi.Api.get().requestLocationUpdates().
        - onLocationChanged() callbacks for indoor positioning (Location comes from Bluetooth) should be received once in a second.
        - warning: there is no Steerpath api to detect if permissions are not set or if Bluetooth is disabled. If location updates are not received, check these!

        If default configuration is used (no GPS) and no nearby beacons are detected, onLocationChanged() won‘t be called at all.
        If GPS is enabled and no nearby beacons are detected, onLocationChanged() is called when network or gps Location changes.

        Sequence goes as follows in online positioning:
        1. Permissions are set
        2. Device has Bluetooth enabled
        3. Bluetooth beacon is detected
        4. Depending on the beacon type, additional beacon data is first downloaded. This is indicated with following message:
            [  JOB  ] started: FileQuery@429ea900 [file=/data/data/com.steerpath.sdk.example/cache/e:XXXXXXXXXXXXXXXX]
        5. Next, SDK downloads actual positioning data (NDD) for the building. This is indicated with following messages:
            [BLUEDOT] NDD requested: XXXXXXXXXXXXXXXXXXXXXXXX
            [  JOB  ] started: FileQuery@425674e8 [file=/data/data/com.steerpath.sdk.example/cache/XXXXXXXXXXXXXXXXXXXXXXXX.ndd]
        6. Blue dot should now appear automatically and onLocationChanged() callbacks should start receiving updates.

        Depending on the file sizes and network connection, downloading may take awhile. If OfflineBundle is used, additional beacon data
        and positioning data are not downloaded from the Steerpath server. Instead, a local cache is used.

        If position is still not working, check following:
            - You should see "[SERVICE] Guide started"
            - You should see "[SERVICE] Positioning ON: Thread[Thread-XX,X,main]"
            - You should see "[SERVICE] adding eids/uids: X"
            - You should not see "[ ERROR ] failed to load file: NOT_FOUND, code=404, url=https://beacons.xx.steerpath.com/u:XXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXX"
                * But if you do, please grab that url and deliver it to the Steerpath Support.
            - You should not see "[ ERROR ] failed: /data/data/com.steerpath.sdk.example/cache/XXXXXXXXXXXXXXXXXXXXXXXX.ndd, msg=timeout"
                * But if you do, wait a while. SDK attempts automatically to re-download and process required ndd file.

        Before contacting Steerpath Support, please collect "Monitor" messages from the logcat.

    

RouteStepViewHolder callbacks not invoked, destination and distance texts not updating?

        RouteStepViewHolder and DirectionSheet both operates with concepts of "RouteStep" and "RouteTrackerProgress".
        RouteSteps are "Walk 28m and turn left" messages, and RouteTrackerProgress is the progress between two RouteSteps.

        RouteStepViewHolder has update() methods for both and SDK calls them automatically when it sees that there has been some progress on routing:
        - update(Context context, RouteStep step)
        - update(Context context, RouteTrackerProgress progress)

        These callbacks require a position, so if you are running on emulator, callbacks may not be invoked. You may use SteerpathMapView.setupClickForFakeLocation() to fake location on touch.

        Note: there is small difference when using fake location vs. real location:
        - When using fake location, SDK does not initially call update(Context context, RouteTrackerProgress progress). It is called next time new fake location is set by touching the route line somewhere.
        - When routing with real location, update(Context context, RouteTrackerProgress progress) is called almost immediately after first update(Context context, RouteStep step).
    

The map is black?

        Mapbox failed to load style. Search "mbgl" tags from logcat for more information.
    

The map is white?

        Mapbox did load the style, but map tiles are not loaded. Check your initial coordinates. For example, if SteerpathMapView is opened in global view (showing whole world),
        world tiles are attempted to load from position /0/0/0. If Steerpath map tile server does not host such map tiles, map will be white. Change initial camera position with SteerpathMap.setCameraPosition(), your venue position
        is the preferred choice.
    

Data on the server has updated, when I can see changes in my app?

    SDK automatically checks updates and downloads files silently in the background. Updates are applied next time app is launched (this is tied to process, app needs to be killed first).

com.steerpath.sdk.common This package contains utilities used by the different functions of Steerpath.
com.steerpath.sdk.directions This is the core package for accessing Steerpath indoor directions.
com.steerpath.sdk.geofence Geofencing, aka area or zone based triggering, for the Steerpath platform.
com.steerpath.sdk.location This is the core package for accessing Steerpath positioning.
com.steerpath.sdk.maps Steerpath maps provides vector based indoor floor plans and outdoor maps.
com.steerpath.sdk.maps.defaults This package contains default map widgets.
com.steerpath.sdk.maps.model
com.steerpath.sdk.meta This is the core package for accessing Steerpath Web API.
com.steerpath.sdk.telemetry
com.steerpath.sdk.utils Helpers and tools.