Xee Android SDK V4

The new Xee Android SDK making easier the usage of our new API V4 on Android devices

Table of contents

• Requirements
• Example project
• Installation
• Setup
• Usage
• Authentication
  • Create an account
  • Authenticate the user
  • Disconnect the user
• Vehicles
  • Associate vehicle
  • Retrieve users's vehicles
  • Disassociate vehicle
  • Retrieve vehicle
  • Update vehicle
  • Retrieve vehicle status
• Users
  • Retrieve an user
  • Update an user
• Signals
  • Retrieve accelerometers
  • Retrieves device data
  • Retrieve locations
  • Retrieve signals
• Privacies
  • Stop a privacy
  • Retrieve privacies
  • Creates a new privacy
• Trips
  • Retrieve trip
  • Retrieve trip locations
  • Retrieve trip signals
  • Retrieve vehicle trips
• Authorizations
  • Revoke authorization
  • Retrieve users's 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:

1. Create a OAuth2Client with your credentials information and scopes

   val oAuth2Client = OAuth2Client.Builder()
                   .clientId("your_client_id")
                   .clientSecret("your_client_secret")
                   .redirectUri("your_redirect_uri") // optional
                   .scopes(Arrays.asList("scope1", "scopes2", "..."))
                   .build()

2. Create a XeeEnv with your credentials information and link your OAuth2Client

   val xeeEnv = XeeEnv(context, oAuthClient)

3. Use this XeeEnv to create an instance of each module you need

   val 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

Also, the SDK use RxJava which makes easier and more flexible requests to our API.

Authentication

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

Xee • jcholin@xee.com

License

XeeSDK is available under the Apache License 2.0. See the LICENSE file for more info.