The official Smartcar JavaScript SDK.
The Smartcar API lets you read vehicle data (location, odometer) and send commands to vehicles (lock, unlock) using HTTP requests.
To make requests to a vehicle from a web application, the end user must connect their vehicle using Smartcar Connect. The Smartcar JavaScript SDK provides an easy way to launch and handle Connect to retrieve the resulting code.
Before integrating with the JavaScript SDK, you'll need to register an application in the Smartcar dashboard. Once you have registered an application, you will have a Client ID and Client Secret, which will allow you to authorize users.
You can install the JavaScript SDK either using npm or through our CDN.
npm install @smartcar/auth<script src="https://javascript-sdk.smartcar.com/2.8.0/sdk.js"></script>For detailed documentation on parameters and available methods, please refer to the SDK reference.
The SDK manages the front-end flow of the OAuth authorization process. The steps are as follows:
- User clicks "Connect your car" button (or similar button) which creates a pop-up dialog with Connect.
- User selects the make of their vehicle.
- User is prompted to log in with their vehicle credentials.
- User is presented with a set of requested permissions to grant your application.
- User can either "Allow" or "Deny" your application's access to the set of permissions.
- Connect redirects the user to the Smartcar JavaScript SDK redirect page along with the resulting
code. - The redirect page sends the
codeto your application's window and closes the pop-up dialog. - Your JavaScript front end receives the
codein the onComplete function registered in the SDK constructor. This function needs to communicate with your backend to exchange the code for access and refresh tokens. - Your application's back end server needs to accept the
codeand exchange it for an access token.
The SDK facilitates generating OAuth links, creating pop-up dialogs, and receiving authorization codes. This SDK will not assist you with exchanging authorization codes for an access token or making requests to vehicles. Please see our back-end SDKs for more information on handling the access tokens and vehicle requests.
The JavaScript SDK uses a special redirect URI to provide a simpler flow to retrieve authorization codes. The redirect URI takes the following form:
https://javascript-sdk.smartcar.com/v2/redirect?app_origin=<Your Application's Origin>
Note that the version number refers to the major version of the SDK you are using, so updating the SDK to a new major version requires updating your redirect URI in the Smartcar Dashboard accordingly.
The app_origin should be the location at which your website is located. The origin consists of the protocol and the host of your site only, without the resource path.
Some example origins are:
https://example.comhttps://myapp.example.comhttp://localhost:8000
https://example.com/some/pathhttp://localhost:8000/some/pathhttp://localhost:8000?foo=bar#baz
Once you have constructed your redirect URI, make sure to register it on the Smartcar dashboard.
const smartcar = new Smartcar({
clientId: '<your-client-id>',
redirectUri: '<your-redirect-uri>',
scope: ['read_vehicle_info', 'read_odometer'],
onComplete: function(err, code) {
if (err) {
// handle errors from Connect (i.e. user denies access)
}
// handle the returned code by sending it to your back-end server
sendToBackend(code);
},
});Reference: new Smartcar(options)
NOTE: See the full set of available scopes for each endpoint in the Smartcar API reference.
Add a click handler to an HTML element:
smartcar.addClickHandler({id: '#your-button-id'});Reference: smartcar.addClickHandler(options)
Alternatively, you can launch Connect directly:
smartcar.openDialog();Reference: smartcar.openDialog(options)
In addition to the flow described above, you can use the JavaScript SDK in other ways too. The following section will cover some of these cases.
Normally the .addClickHandler() and .openDialog() methods are used to launch Connect. However, if you would like to generate the Connect URL directly, you can do so with the .getAuthUrl() method.
const url = smartcar.getAuthUrl();Reference: smartcar.getAuthUrl(options)
In a traditional OAuth implementation, the redirect URI is normally set to your application's back end, rather than Smartcar's special JavaScript SDK redirect page described in the flow above. Instead of using the JavaScript SDK redirect page, you can still choose to use the traditional server-side architecture (described below). In this architecture you would receive the authorization code on a back-end route instead of the client-side onComplete callback.
To use the JavaScript SDK for this flow, do the following:
- Set the
redirect_uriparameter in the initialization to a route on your application's back-end server:
const smartcar = new Smartcar({
clientId: '<your-client-id>',
redirectUri: '<your-backend-redirect-uri>',
scope: ['read_vehicle_info', 'read_odometer'],
onComplete: function() {},
});Make sure to also register the URI on the Smartcar dashboard.
- On your
redirect_uriroute, you will need to accept the authorization code according to the query parameters documented in the Smartcar API reference.
For example:
https://application-backend.com/page?code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
Or in case of an error:
https://application-backend.com/page?error=access_denied&error_description=User+denied+access+to+application.
- On the redirect route, you can render a page with the JavaScript SDK's redirect helper script. The script will invoke the
onCompletecallback and close out the Connect pop-up dialog.
<script src="https://javascript-sdk.smartcar.com/v2/redirect.js"></script>NOTE: If the page serving the redirect script file does not have the original query parameters sent from Connect (
code,state,error,error_description), then theonCompletecallback will be invoked with no parameters.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![mend-bolt-for-github[bot] avatar](https://avatars.githubusercontent.com/in/16809?v=4 "mend-bolt-for-github[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent