Xee Android SDK V4
API V4 on Android devices
The new Xee Android SDK making easier the usage of our newTable of contents
- Requirements
- Example project
- Installation
- Setup
- Usage
- Authentication
- Vehicles
- Users
- Signals
- Privacies
- Trips
- Authorizations
- Sign-In button
- Documentation
- Issues
- Author
- License
Requirements
This SDK works for all devices with an Android version >= 16
Example project
We provide a demo app that shows how the SDK might be used
Installation
Our SDK is built over jitpack.io.
In order to use this SDK, please do the following:
Add this to your root project build.gradle
allprojects {
repositories {
maven {
url "https://jitpack.io"
}
}
}
Then just add each module your need to the dependencies in the build.gradle file.
dependencies {
compile 'com.github.xee-lab.sdk-android:sdk-core:4.1.24'
compile 'com.github.xee-lab.sdk-android:sdk-api:4.1.24'
}
If you just need to sign in with Xee, you can just use:
compile 'com.github.xee-lab.sdk-android:sdk-core:4.1.24'
If you need to use our api, just only use the sdk-api
(no need to add the sdk-core
line because it's a direct dependency of sdk-api
)
compile 'com.github.xee-lab.sdk-android:sdk-api:4.1.24'
Setup
Once the SDK is installed, create an application on our developer space to get credentials, see how to create an app.
Then initialize the SDK following these steps:
-
Create a
OAuth2Client
with your credentials information and scopesval oAuth2Client = OAuth2Client.Builder() .clientId("your_client_id") .clientSecret("your_client_secret") .redirectUri("your_redirect_uri") // optional .scopes(Arrays.asList("scope1", "scopes2", "...")) .build()
-
Create a
XeeEnv
with your credentials information and link yourOAuth2Client
val xeeEnv = XeeEnv(context, oAuthClient)
-
Use this
XeeEnv
to create an instance of each module you needval xeeAuth = XeeAuth(xeeEnv) val xeeApi = XeeApi(xeeEnv)
Note that you can enable SDK logs (please disable them for release) for each module you want with a second parameter like this:
val xeeApi = XeeApi(xeeEnv, true) // enable SDK logs
You can also set the timeout for requests:
val xeeApi = XeeApi(xeeEnv, true, 30000) // set timeout in ms
Now you're ready to use the SDK!
Usage
Here are some examples of commons methods you might use.
Note that we'll keep this SDK up to date to provide you all the endpoints availables on the 4rd version of the API
RxJava which makes easier and more flexible requests to our API.
Also, the SDK useAuthentication
Please see the authentication flow for explanations
Create an account
xeeAuth.register(object : RegistrationCallback {
override fun onCanceled() {
'your code'
}
override fun onError(error: Throwable) {
'your code'
}
override fun onRegistered() {
'your code'
}
override fun onLoggedAfterRegistration() {
'your code'
}
})
Authenticate the user
xeeAuth.connect(object : AuthenticationCallback {
override fun onError(error: Throwable) {
'your code'
}
override fun onSuccess() {
'your code'
}
})
Disconnect the user
xeeAuth.disconnect(object : DisconnectCallback {
override fun onCompleted() {
'your code'
}
})
Vehicles
Everything about your vehicles
Associate vehicle
Set a vehicle for an user with a specified device_id and pin code
xeeApi.associateVehicle("id", "pin")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ vehicle -> 'your code' }, { error -> 'your code' })
Retrieve users's vehicles
Returns vehicles corresponding to specified user id (me is also acceptable)
xeeApi.getUserVehicles("user_id") // no parameters corresponds to "me" by default
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ vehicles -> 'your code' }, { error -> 'your code' })
Dissociate vehicle
Delete the pairing between a vehicle and a device
xeeApi.dissociateVehicle("vehicle_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ 'your code' }) { error -> 'your code' }
Retrieve vehicle
Returns a vehicle corresponding to specified id
xeeApi.getVehicle("vehicle_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ vehicles -> 'your code' }, { error -> 'your code' })
Update vehicle
Update a vehicle with a specified ID
xeeApi.updateVehicle("vehicle_id", vehicle_to_update)
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ vehicleUpdated -> 'your code' }, { error -> 'your code' })
Retrieve vehicle status
Returns the vehicle status of the vehicle
xeeApi.getVehicleStatus("vehicle_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ status -> 'your code' }, { error -> 'your code' })
Users
Access to your profile
Retrieve an user
Returns a user corresponding to specified id, me is also acceptable
xeeApi.getUser("user_id") // no parameters corresponds to "me" by default
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ user -> 'your code' }, { error -> 'your code' })
Update user
Update the current user
xeeApi.updateUser()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ userUpdated -> 'your code' }, { error -> 'your code' })
Signals
Signals of Vehicles (CAN signals, GPS and Accelerometer)
Retrieve accelerometers
Retrieves the accelerometers data of a vehicle in a given date range
xeeApi.getVehicleAccelerometers("vehicle_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ accelerometers -> 'your code' }, { error -> 'your code' })
Retrieve device data
Retrieves the device data of a vehicle in a given time range
xeeApi.getVehicleDeviceData("vehicle_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ data -> 'your code' }, { error -> 'your code' })
Retrieve locations
Retrieves the locations of a vehicle in a given date range
xeeApi.getVehicleLocations("vehicle_id", "from", "to", "limit")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ locations -> 'your code' }, { error -> 'your code' })
Retrieve signals
Retrieves signals for a vehicle in a given date range
xeeApi.getVehicleSignals("vehicle_id", "from", "to", "limit")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ signals -> 'your code' }, { error -> 'your code' })
You can also filter by signals you want
xeeApi.getVehicleSignals("vehicle_id", "from", "to", "BatteryVoltage,LockSts", "limit")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ signals -> 'your code' }, { error -> 'your code' })
Privacies
Operations about privacies
Stop a privacy
Stop an existing privacy session
xeeApi.disablePrivacy("privacy_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ privacyStopped -> 'your code' }, { error -> 'your code' })
Retrieve privacies
Returns vehicles privacies between 2 dates inclusive
xeeApi.getVehiclePrivacies("vehicle_id", "from", "to", "limit")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ privacies -> 'your code' }, { error -> 'your code' })
Creates a new privacy
Creates a new privacy session on this vehicle
xeeApi.enablePrivacy("vehicle_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ privacy -> 'your code' }, { error -> 'your code' })
Trips
Access to the trips of the vehicles
Retrieve trip
Returns trip corresponding to specified vehicle id
xeeApi.getTrip("trip_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ trip -> 'your code' }, { error -> 'your code' })
Retrieve trip locations
Returns trips locations by redirecting to the signals api with the good date range
xeeApi.getTripLocations("trip_id", "from", "to", "limit")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ locations -> 'your code' }, { error -> 'your code' })
Retrieve trip signals
Returns trips signals by redirecting to the signals api with the good date range
xeeApi.getTripSignals("trip_id", "from", "to", "limit")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ signals -> 'your code' }, { error -> 'your code' })
Retrieve vehicle trips
Returns trips corresponding to specified vehicle id. Request by date is inclusive. For example if a trip starts from 15:00 and ends at 16:00. A request from 15:15 to 15:45 will return this trip.
xeeApi.getVehicleTrips("vehicle_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ trips -> 'your code' }, { error -> 'your code' })
Authorizations
Manage OAuth authorizations
Revoke authorization
Revokes the specified authorization
xeeApi.revokeAuthorization("authorization_id")
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ 'your code'}) { error -> 'your code'}
Retrieve users's authorizations
Returns authorizations corresponding to specified user id
xeeApi.getAuthorizations("user_id") // no parameters corresponds to "me" by default
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe({ authorizations -> 'your code' }, { error -> 'your code' })
Sign-In button
Use the Sign-In button to sign in with Xee. Three themes and three sizes are provided
- size: icon, normal, large
- theme: grey, green, white
Use the Sign-In & Sign-Up buttons in layout file
<com.xee.sdk.core.auth.SignInButton
android:id="@+id/sign_in_button"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:signInBtnSize="normal"
app:signInBtnTheme="grey"
/>
<com.xee.sdk.core.auth.SignUpButton
android:id="@+id/sign_up_button"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:signUpBtnSize="normal"
app:signUpBtnTheme="grey"
/>
Then set listeners for your action
signInBtn.setOnClickListener {
xeeAuth.connect(object : AuthenticationCallback {
override fun onError(error: Throwable) {
'your code'
}
override fun onSuccess() {
'your code'
}
})
}
signUpBtn.setOnClickListener {
xeeAuth.register(object : RegistrationCallback {
override fun onCanceled() {
'your code'
}
override fun onError(error: Throwable) {
'your code'
}
override fun onRegistered() {
'your code'
}
override fun onLoggedAfterRegistration() {
'your code'
}
})
}
Documentation
You can generate documentation of SDK by using Dokka tool. Just execute the command below:
./gradlew dokka
Note that the output documentation can be found in javadoc folder of each module of the SDK
Issues
We're working hard to provide you an issue free SDK, but we're just humans so we can do mistakes.
If you find something, feel free to fill an issue or/and fork the repository to fix it !sdk-android
Author
License
XeeSDK is available under the Apache License 2.0. See the LICENSE file for more info.