Introducing the new and improved JavaScript SDK

The Smartcar API currently offers three back-end and three front-end SDKs for developers who want to build apps for cars. The JavaScript SDK is our most widely used front-end SDK.

We recently launched v2 of the JavaScript SDK. This revamped version makes it easier to build single-page applications (SPAs) on the Smartcar platform. But before we dive into details, let’s discuss how v1 worked and why we decided to do an overhaul.

V1 of the JavaScript SDK

Simple for server-side rendered applications

An important part of building and using an app on the Smartcar platform is the authorization flow. Smartcar uses the OAuth2 framework for its authorization flow. In v1 of the SDK, this flow enabled server-side rendered applications, which use frameworks such as Rails, Django, or Spring:

1. Authorization: Your app’s web page launches the Smartcar authorization dialog in a pop-up window. The user logs in with their vehicle credentials (e.g. Volkswagen Car-Net, Chrysler UConnect) and grants your app access to their vehicle.
2. Redirect, retrieve authorization code, and close pop-up window: The user’s browser is redirected to a specified redirect URI. Your app’s server, listening at the redirect URI, retrieves the authorization code from query parameters. Your app’s server then renders an HTML page with a helper script. This helper script calls an `onComplete` function, notifying your application that the authorization process is complete, and closes the pop-up window.
3. Done! The authorization flow is complete. Your app can now exchange the authorization code for an access token and start making HTTP requests to the Smartcar API to access the vehicle’s location, read its odometer, or lock and unlock its doors.

Challenging for single-page applications

While v1 worked for traditional server-side rendered applications, we noticed that many of our developers wanted to create single-page applications (SPAs), using frameworks like Angular and React. When building SPAs on the Smartcar API, our developers faced several challenges:

1. Server must render HTML: In an SPA, the server communicates with JSON serialization, while the front end uses JavaScript to bring that JSON data into HTML format. So, an SPA server doesn’t usually deal with any HTML code. However, step 2 of the authorization flow requires the server to render an HTML page with a helper script to call the `onComplete` function and close the pop-up window. Since the server doesn’t usually use HTML, this rendering adds unwanted complexity.
2. Cross-origin resource sharing (CORS): In an SPA, it is common for the server and the front end to be hosted on two different domains. So, even if you manage to make the server render an HTML page with the helper script, you will still encounter another problem: With server-side rendered applications, the app’s server is able to call the `onComplete` function only because it is hosted on the same domain as the app’s website. In the case of an SPA, the server will not be able to call the `onComplete` function, because browsers don’t allow scripts from one domain to communicate with scripts from another domain. This security policy is called cross-origin resource sharing, or CORS.‍
3. Loading the entire app: You can try to avoid problems 1 and 2 in the following way: You serve the redirect URI page from the front end. Unfortunately, you’ll then face another problem: In SPAs, the entire application is usually bundled into one single file. So, if you serve your redirect page from the front end, you will need to load your entire application into the pop-up window. This takes time and gives your user a less-than-ideal experience.

V2 of the JavaScript SDK

A simple authorization flow for single-page applications

In order to solve these challenges associated with SPAs, we decided to revamp our JavaScript SDK. The solution we came up with has Smartcar host a redirect page for you. Here’s a diagram of the updated authorization flow:

1. Authorization: Your SPA launches the Smartcar authorization dialog in a pop-up window. The user logs in with their vehicle credentials (e.g. Volkswagen Car-Net, Chrysler UConnect) and grants your app access to their vehicle.
2. Smartcar-hosted redirect page: The user’s browser is redirected to a specified Smartcar-hosted redirect URI — the Smartcar JavaScript SDK redirect page.
3. Retrieve authorization code and close pop-up window using `onComplete`: The Smartcar-hosted redirect page retrieves the authorization code from query parameters. The redirect page will then trigger execution of your SPA’s `onComplete` callback using the `postMessage` web API. This step is handled entirely by the JavaScript SDK.
4. Send authorization code to server: Your SPA sends the retrieved authorization code to your app’s server (through whatever method you like, e.g. a POST request, websockets, etc.).
5. Done! The authorization flow is complete. Your app can now exchange the authorization code for an access token and start making HTTP requests to the Smartcar API to access the vehicle’s location, read its odometer, or lock and unlock its doors.

Using `postMessage` — a web API that allows for secure cross-domain communication — enables v2 of the SDK to send the authorization code from the pop-up to your SPA, while still abiding to CORS rules.

By hosting a redirect page for you and using `postMessage` to securely communicate across domains, we solve all three challenges that SPAs faced with v1 of the SDK:

1. Server doesn’t have to render HTML: Thanks to the Smartcar-hosted redirect page, we handle serving HTML so you don’t have to.
2. Cross-origin resource sharing (CORS) through `postMessage`: Obviously, the Smartcar-hosted redirect page and your SPA are hosted on two different domains. By using the `postMessage` API, however, we can securely send the authorization code back to your app without breaking CORS rules.
3. No need to load the entire app: You no longer need to worry about loading your entire front end into the pop-up, since we serve it for you.

Thanks to v2 of the JavaScript SDK, you can now easily build SPAs on the Smartcar platform! 🎉

And of course…

All else remains equal

• Server-side rendered applications: If you are building a server-side rendered app, don’t worry. V2 of the JavaScript SDK will allow you to build server-side rendered apps in exactly the same way v1 did.
• Host your own redirect page: If you are building an SPA and wish to host your own redirect page, you can absolutely still do so. Please have a look at the Advanced section of the JavaScript SDK’s README to learn more.

Are you ready to start building? Head over to the JavaScript SDK repo and jumpstart your creative engines! For more context, check out our docs — and as always, please don’t hesitate to reach out to us with any questions.

PS: Follow us on LinkedIn and Facebook!