Caution
Important note.
This repository is now deprecated and will be removed on September 1, 2024. Use the new repository for BlueGPS SDK library and the new demo app for example reference.
Official Android Demo App showcases the BlueGPS SDK features and acts as reference implementation for many of the basic SDK features. Getting started requires you setup a license.
The BlueGPS Android SDK is distributed through Jitpack. It can be integrated through gradle, maven as following:
Before you add BlueGPS depencencies, add it in your settings.gradle at the end of repositories
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}Or if you're using an older project setup, add it in your build.gradle at the end of repositories
allprojects {
repositories {
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}Then add the dependency for BlueGPS-SDK in the build.gradle file for your app or module:
dependencies {
implementation 'com.github.synapseslab:android-bluegps-sdk-demoapp:<version>'
}The version corresponds to release version, for example:
dependencies {
implementation 'com.github.synapseslab:android-bluegps-sdk-demoapp:X.Y.Z'
}Add the JitPack repository to your build file
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
Then add the dependency
dependency>
<groupId>com.github.synapseslab</groupId>
<artifactId>android-bluegps-sdk-demoapp</artifactId>
<version>Tag</version>
</dependency>
The Tag corresponds to release version, for example: 1.4.2
Your first step is initializing the BlueGPSLib, which is the main entry point for all operations in the library. BlueGPSLib is a singleton: you'll create it once and re-use it across your application.
A best practice is to initialize BlueGPSLib in the Application class:
class App : Application() {
override fun onCreate() {
super.onCreate()
BlueGPSLib.instance.initSDK(
sdkEnvironment = Environment.sdkEnvironment,
context = applicationContext,
enabledNetworkLogs = true
)
}
}The BlueGSP-SDK use an Environment where integrator have to put SDK data for register the SDK and for create a communication with the BlueGPS Server see the demo app for detail. The management of the environment is demanded to the app.
object Environment {
private val SDK_ENDPOINT = "{{provided-bluegps-endpoint}}"
private val APP_ID = "com.synapseslab.demosdk"
val sdkEnvironment = SdkEnvironment(
sdkEndpoint = SDK_ENDPOINT,
appId = APP_ID,
)
}The BlueGPS_SDK offers a client for managing authentication and authorization within your application. It leverages Keycloak to handle user authentication.
For the configuration in this case use keyCloakParameters parameter on initSDK(..).
BlueGPSLib.instance.initSDK(
sdkEnvironment = Environment.sdkEnvironment,
context = applicationContext,
keyCloakParameters = Environment.keyCloakParameters
)where keyCloakParameters is this object
val keyCloakParameters = KeyCloakParameters(
authorization_endpoint = "https://[BASE-URL]/realms/[REALMS]/protocol/openid-connect/auth",
token_endpoint = "https://[BASE-URL]/realms/[REALMS]/protocol/openid-connect/token",
redirect_uri = "{{provided-redirect-uri}}",
clientId = "{{provided-client-secret}}", // for user authentication
userinfo_endpoint = "https://[BASE-URL]/realms/[REALMS]/protocol/openid-connect/userinfo",
end_session_endpoint = "https://[BASE-URL]/realms/[REALMS]/protocol/openid-connect/logout",
guestClientSecret = "{{provided-guest-client-secret}}", // for guest authentication
guestClientId = "{{provided-guest-client-id}}" // for guest authentication
)BlueGPS provides 2 kinds of authentication:
- User Authentication:
If you want only the User authentication you must set the clientId.
This means that for each device this is the user on Keycloak that can manage grants for this particular user.
- Guest Authentication:
If you want only the Guest authentication, you must set the guestClientSecret and guestClientId.
This means that we don't have a user that has to login but we use client credentials and there is not an individual user for each app install. Instead BlueGPS treats the user account as a "guest" In this case multiple devices can use the same client credentials to be authenticated and BlueGPS will register the user as a device, and not as a formal Keycloak user.
This paramaters are provided by Synapses after the purchase of the BlueGPS license.
Finally in your AndroidManifest.xml add this and change host and scheme with your configuration.
<activity
android:name="com.synapseslab.bluegps_sdk.authentication.presentation.AuthenticationActivity"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:host="{HOST}"
android:scheme="{SCHEME}" />
</intent-filter>
</activity>Now your app is ready for use keycloak. See KeycloakActivity.kt example for an example of login, logout or refresh token.
To ensure backward compatibility with applications that still utilize the old authentication mechanism, only set the SDK_KEY and SDK_SECRET values. This practice allows seamless integration with legacy apps while maintaining the necessary authentication parameters.
object Environment {
private val SDK_ENDPOINT = "{{provided-bluegps-endpoint}}"
private val SDK_KEY = "{{provided-sdk-key}}"
private val SDK_SECRET = "{{provided-sdk-secret}}"
private val APP_ID = "com.synapseslab.demosdk"
val sdkEnvironment = SdkEnvironment(
sdkEndpoint = SDK_ENDPOINT,
appId = APP_ID,
sdkKey = SDK_KEY,
sdkSecret = SDK_SECRET,
)
}To run the sample app, start by cloning this repo:
git clone git@github.com:synapseslab/android-bluegps-sdk-demoapp.gitand play with it.
BlueGPS_SDK provides a client for manage authentication and authorization inside your app.
BlueGPSSDK provides some built-in capabilities to search for resources and objects within the backend.
BlueGPSSDK provides a logic to interact with controllable items exposed by the backend. Controllable items could be anything that can be remote controlled by the application.
BlueGPSSDK provides some built-in capabilities for rooms and areas.
The purpose of diagnostic API is to give an indication to the integrator of the status of the BlueGPS system.
- SSE Notify region changes - (documentation)
- SSE Notify position changes - (documentation)
- SSE Diagnostic Tag - (documentation)
- SSE Generic Events - (documentation)
Let's see how you can get started with the Android BlueGPS SDK after adding the required dependencies.