Our frontend SDKs handle getting an authorization code representing a vehicle owner’s consent for your application to interact with their vehicle for the requested permissions. In order to make requests to a vehicle, please use one of our backend SDKs.

For security, token exchanges and requests to vehicles should not be made client side.


Overview


  1. The Single-Page Application launches a pop-up window with Smartcar Connect to request access to a user’s vehicle. It does so by using the Smartcar JavaScript SDK. On Connect, the user logs in with the username and password for their vehicle’s connected services account and grants the Application access to their vehicle.
  2. The user’s browser is redirected to a specified Smartcar-hosted REDIRECT_URI - the Smartcar JavaScript SDK redirect page.
  3. The Smartcar JavaScript SDK redirect page will receive an authorization code as a query parameter. The redirect page will then send the code to the Single-Page Application’s onComplete callback using the postMessage web API. This step is handled entirely by the JavaScript SDK.
  4. The Single-Page Application sends the received authorization code to the Application’s backend service.
  5. The Application sends a request to the Smartcar API. This request contains the authorization code along with the Application’s CLIENT_ID and CLIENT_SECRET.
  6. In response, Smartcar returns an ACCESS_TOKEN and a REFRESH_TOKEN.
  7. Using the ACCESS_TOKEN, the Application can now send requests to the Smartcar API. It can access protected resources and send commands to and from the user’s vehicle via the backend service.

Prerequisites

  • Sign up for a Smartcar account.
  • Make a note of your CLIENT_ID and CLIENT_SECRET from the Configuration section on the Dashboard.
  • Add the special JavaScript SDK redirect URI to your application configuration.
  • Add the REACT_APP_SERVER redirect URI from Setup step 2. to your application configuration.

To use the JavaScript SDK, we require the special redirect URI to provide a simpler flow to retrieve authorization codes. For this tutorial you can use the following:

https://javascript-sdk.smartcar.com/v2/redirect?app_origin=http://localhost:3000

Setup

  1. Clone our repo and install the required dependencies:
    $git clone https://github.com/smartcar/getting-started-javascript-sdk-react.git
    $cd getting-started-javascript-sdk-react/tutorial
    $npm install
    
  2. Set the following environment variables. We will be setting up a server later for our React front-end to communicate with. For now, let’s assume our server is listening on http://localhost:8000.
    $export REACT_APP_CLIENT_ID=<your-client-id>
    $export REACT_APP_REDIRECT_URI= https://javascript-sdk.smartcar.com/v2/redirect?app_origin=http://localhost:3000
    $export REACT_APP_SERVER=http://localhost:8000
    

Note: If you are using Windows, ensure you are appropriately setting environment variables for your shell. Please refer to this post which details how to set environment variables on Windows.

Build your Connect URL

  1. Instantiate a Smartcar object in the constructor of the App component.
    App.jsx
    constructor(props) {
    ...
    // TODO: Authorization Step 1: Initialize the Smartcar object
    this.smartcar = new Smartcar({
        clientId: process.env.REACT_APP_CLIENT_ID,
        redirectUri: process.env.REACT_APP_REDIRECT_URI,
        scope: ['required:read_vehicle_info'],
        mode: 'test',
        onComplete: this.onComplete,
    });
    }
    

This tutorial uses test mode by default. Feel free to set mode to live where you instantiate your Smartcar object to connect to a real vehicle, or simulated to connect to a simulated one.

  1. A single-page application will launch a pop-up window with Smartcar Connect to request access to a user’s vehicle. On Connect, the user logs in with the username and password for their vehicle’s connected services account and grants the application access to their vehicle.

    To launch Connect, we can use the openDialog function that our Smartcar object has access to. We can place this is an onClick handler of an HTML button.

    App.jsx
    authorize() {
        // TODO: Authorization Step 2a: Launch Connect
        this.smartcar.openDialog({forcePrompt: true});
    }
    
    render() {
        // TODO: Authorization Step 2b: Render the Connect component
        return <Connect onClick={this.authorize} />;
    }
    

Handle the response

  1. Once a user has authorized the application to access their vehicle, the user is redirected to the redirect_uri with an authorization code as a query parameter and the pop-up dialog is closed. Using the JavaScript SDK, the frontend can receive this code in the onComplete callback passed into the Smartcar object.
    App.jsx
    onComplete(err, code, status) {
        //TODO: Authorization Step 3: Receive the authorization code
        console.log(code);
        //prints out the authorization code
    };
    

Launching Connect

Restart your server, open up your browser and go to http://localhost:3000/login. You should be reciderect to Smartcar Connect.

This tutorial configures Connect to launch in test mode by default. In test mode, any username and password is valid for each brand.

Smartcar showcases all the permissions your application is asking for - read_vehicle_info in this case. Once you have logged in and accepted the permissions, you should see your authorization code printed to your console.

Getting your first access token

After receiving the authorization code, the React application must exchange it for an ACCESS_TOKEN. To do so, we can send the code to the backend service which we will implement in a bit. Until then, let’s assume our backend service contains an endpoint /exchange that receives an authorization code as a query parameter and exchanges it for an ACCESS_TOKEN.

We can add this logic in our onComplete callback

App.jsx
onComplete(err, code, status) {
  // TODO: Request Step 1: Obtain an access token
  return axios
    .get(`${process.env.REACT_APP_SERVER}/exchange?code=${code}`);
}

Getting data from a vehicle

Once the back-end has the ACCESS_TOKEN, it can send requests to a vehicle using the Smartcar API. The React app will have to send a request to the backend service which in turn sends a request to Smartcar. We have to do this because our frontend does not have the ACCESS_TOKEN.

Assuming our backend has a /vehicle endpoint that returns the information of a user’s vehicle, we can make this query in our completion callback and and set the state of the React app with the returned vehicle attributes.

App.jsx
onComplete(err, code, status) {
  // TODO: Request Step 2a: Get vehicle information
  return axios
    .get(`${process.env.REACT_APP_SERVER}/exchange?code=${code}`)
    .then(_ => {
      return axios.get(`${process.env.REACT_APP_SERVER}/vehicle`);
    })
    .then(res => {
      this.setState({vehicle: res.data});
    });
}

Now that we have the vehicle attributes, we can render a simple Vehicle component that shows the vehicle attributes in a table.

App.jsx
render() {
  // TODO: Request Step 2b: Get vehicle information
  return Object.keys(this.state.vehicle).length !== 0 ? (
    <Vehicle info={this.state.vehicle} />
  ) : (
    <Connect onClick={this.authorize} />
  );
}

Setting up your backend

Now that our frontend is complete, we will need to create a backend service that contains the logic for the /exchange and /vehicle endpoints. You can use any of our backend SDKs below to set up the service starting from the Obtaining an access token step.

When setting up the environment variables for your backend SDK, make sure to set REDIRECT_URI to the custom scheme used for this tutorial i.e. https://javascript-sdk.smartcar.com/v2/redirect?app_origin=http://localhost:3000.