Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
110 lines (97 sloc) 7.23 KB

carvoyant connector

About carvoyant

carvoyant designs and sells a device which turns any vehicle built after 1996 into a connected vehicle. This device provides end users access to a multitude of data generated by their vehicles. This connector allows you to connect to Carvoyant's powerful REST APIs to access and work with the data, which opens up tremendous opportunities for innovation.

Purpose of the scriptr.io connector for carvoyant

The purpose of this connector is to simplify and streamline the way you access carvoyant's APIs from scriptr.io, by providing you with a few native objects that you can directly integrate into your own scripts. This will hopefully allow you to create sophisticated applications. For example, using the information about the distance ran by a car and its fuel consumption, you can implement a "pay as you go" car rental application.

Components

  • carvoyant/user.js: this is the main object to interact with. It provides access to data of a given user (the one for who you are passing an access token)
  • carvoyant/vehicle.js: you usually obtain an instance of this component from the former. It allows you to obtain all the actions that you can do on a user's vehicle, usually to retrieve data or to subscribe to notifications
  • carvoyant/notifications.js: handles subscriptions to any type of carvoyant notifications, not only vehicle-related. Used by the former component but can be used directly.
  • carvoyant/common.js: configuration file to specify the path to notification handlers and notification callbacks.
  • carvoyant/mapping.js: configuration file used for internal purposes.
  • carvoyant/util.js: module with utilily functions used internally.
  • carvoyant/client.js: generic http client that handles the communication between scriptr.io and carvoyant. Used by user, vehicle and notifications.
  • carvoyant/api/handleEvent.js: default callback invoked by carvoyant to send notifications to.
  • carvoyant/notificationHandlers/DefaultHandler.js: this is the default handler that is triggered upon the occurrence of any carvoyant event.
  • carvoyant/test/tests.js: a list of all the objects and corresponding methods, for examples on how to use them.

How to use

  • Deploy the aforementioned scripts in your scriptr account, in a folder named "carvoyant".
  • Create a developer account and an application at carvoyant.
  • Create an end user (driver) account (https://driver.carvoyant.com/)
  • Once done, make sure to copy/paste the values of your Client (Consumer) Key, OAuth 2.0 Client ID and Client (Consumer) Secret in the corresponding variables of the "oauth2/config.js file" (respectively client_id and client_secret).
  • In the "oauth2/config.js" file, make sure that the value of the "response_type" variable is set to "token"
  • In the "oauth2/config.js" file, make sure to set the value of the "apiUrl" to the correct carvoyant endpoint (sandbox or production)
  • In the "oauth2/config.js" file, make sure to set the value of the "app" variable to a name you choose
  • In the "oauth2/config.js" file, make sure to leave empty the value of the "apiVer" variable (empty string "")
  • Create a test script in scriptr, or use the script provided in carvoyant/test/.

Obtain access tokens from carvoyant

Step 1

From a front-end application, send a request to the /oauth2/getRequestCodeUrl.js script, passing the username parameter. The username can be the actual end user's carvoyant username or another username he decides to use in your IoT application. The result returned by the aforementioned script should resemble the following:

>> curl -X POST  -F username=edison -F apsws.time=1434722158021 -H 'Authorization: bearer <YOUR_AUTH_TOKEN>' 'https://api.scriptr.io/oauth2/getRequestCodeUrl.js'
{
	"metadata": {
		"requestId": "45753a7f-a2b6-4378-a8e1-3bbddced9694",
		"status": "success",
		"statusCode": "200"
	},
	"result": "https://sandbox-auth.carvoyant.com/OAuth/authorize?client_id=atkchwp98j3whpg6cjgwt98h&response_type=token&state=02a0e4&redirect_uri=https%3A%2F%2Fapi.scriptr.io%2Foauth2%2FgetAccessToken.js%3Fauth_token%3SKzM1RnYwAzc4Mg%3D%3D%26state%3R02a1e4""
}

Step 2

From the front-end, issue a request to the obtained URL. This redirects your end user to the carovyant login page, where he has to enter his credentials then authorize the application on the requested scope. Once this is done, carvoyant automatically calls back the carvoyant/getAccessToken.js script, providing it with an access and a refresh token that it stores in your scriptr.io's global storage. The tokens are also returned by the script.

Use the connector

In order to use the connector, you need to import the main module: carvoyant/user.js, as described below:

var userModule = require("/modules/carvoyant/user.js");

Then create a new instance of the User class, defined in this module (we assume that we already otbained an access token for the given user):

var user = new userModule.User({username:"edison"});

The User class provides many methods to obtain data related to the end user, such as:

var accountsData = user.listAccounts(); // the list of carvoyant accounts owned by this user
var accountDetails = user.getAccount("some_account_id"); // details of a specific carvoyant user account
var vehicles = user.listVehicles(); // lists the vehicles added by this user to his carvoyant accounts

In order to manipulate the end user's vehicles, you first need to obtain a reference to the Vehicle class. You can do this:

  • by invoking the getVehicle(id) method of your User instance, as follows:
var vehicle = user.getVehicle("some_id"); // you can easily obtained the vehicles' ids using user.listVehicles()
  • second option is to create an instance of vehicle, passing a username and a vehicle id:
var vehicleModule = require("/modules/carvoyant/vehicle.js");
var vehicle = new vehicleModule.Vehicle({username:"edison", vehicleId:"some_id"});

Using the vehicle object, you now retrieve data about the vehicle or subscribe to notifications sent by this latter,

var listOfTrips = vehicle.listTrips(); // list the trips done by this vehicle 

// subscribe to harsh accelerations notifications 
var sub = {
  "notificationType": "VEHICLEHARSHACCEL",
  "notificationPeriod": "ONETIME"
};
    
var notification = vehicle.subscribeToNotification(sub);

You can check the list of all available methods using the carvoyant/test/tests.js script.

About notifications

As mentioned, you can subscribe to notifications that are emitted by a given vehicle, or subscribe to more general notifications that relate to the user account (check code documentation of "/carvoyant/notifications.js") for more on this last part. By default, carvoyant is instructed by the connector to send notifications to the https://api.scriptr.io/carvoynat/api/handleNotifications.js API that resides in your account. This API's job is to trigger the handler that is configured to process the corresponding notification type. By default, the "/carvoyant/notifications/DefaultHandler.js" is invoked for all the notification types. You can implement your own handlers and configure what handler to use for what notification type in the "/carvoyant/common.js" script.