npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@smartcar/auth

v2.11.0

Published

javascript auth sdk for the smartcar

Downloads

4,824

Readme

Smartcar JS Client SDK Build Status GitHub tag

The official Smartcar JavaScript SDK.

Overview

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.

Installation

You can install the JavaScript SDK either using npm or through our CDN.

npm

npm install @smartcar/auth

Smartcar CDN

<script src="https://javascript-sdk.smartcar.com/2.11.0/sdk.js"></script>

SDK reference

For detailed documentation on parameters and available methods, please refer to the SDK reference.

Flow

The SDK manages the front-end flow of the OAuth authorization process. The steps are as follows:

  1. User clicks "Connect your car" button (or similar button) which creates a pop-up dialog with Connect.
    1. User selects the make of their vehicle.
    2. User is prompted to log in with their vehicle credentials.
    3. User is presented with a set of requested permissions to grant your application.
    4. User can either "Allow" or "Deny" your application's access to the set of permissions.
  2. Connect redirects the user to the Smartcar JavaScript SDK redirect page along with the resulting code.
  3. The redirect page sends the code to your application's window and closes the pop-up dialog.
  4. Your JavaScript front end receives the code in 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.
  5. Your application's back end server needs to accept the code and 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.

Quick start

1. Register a JavaScript SDK redirect URI

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:

Valid:

  • https://example.com
  • https://myapp.example.com
  • http://localhost:8000

Invalid:

  • https://example.com/some/path
  • http://localhost:8000/some/path
  • http://localhost:8000?foo=bar#baz

Once you have constructed your redirect URI, make sure to register it on the Smartcar dashboard.

2. Initialize Smartcar

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.

3. Launch Connect

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)

Advanced

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.

Smartcar Connect URL generation

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)

Server-side redirect handling

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:

  1. Set the redirect_uri parameter 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.

  1. On your redirect_uri route, 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.
  1. On the redirect route, you can render a page with the JavaScript SDK's redirect helper script. The script will invoke the onComplete callback 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 the onComplete callback will be invoked with no parameters.