Integrate Smartcar Connect

1. Adapt Smartcar Connect to your application architecture

Depending on your web or mobile application architecture, you can implement the Smartcar Connect flow in different ways.

Traditional server-side rendered application

1. You can use your preferred language framework for a server-side setup as long as you use OAuth2 Retrieval protocol. In this case:
   1. Your application redirects the user’s browser to Smartcar Connect.
   2. The user logs in with the username and password of their vehicle’s connected services account.
   3. The user grants your application access to their vehicle.
2. The Smartcar Connect flow is now complete and the user’s browser gets redirected to a specified redirect_uri. Your application’s server, which is listening at the redirect_uri, retrieves the authorization code from query parameters in the redirect_uri.
3. In order to exchange the authorization code for an access_token, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s client_id and client_secret.
4. In response, Smartcar returns an access_token and a refresh_token. These should be stored in your application’s database.
5. Using the access_token, your application can now make API requests to the user’s vehicle.

Single-page application

1. Using the Smartcar JavaScript SDK, your application launches Smartcar Connect in a pop-up window. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle.
2. The user’s browser gets redirected to a special Smartcar-hosted redirect_uri. For more details on how to configure a Smartcar-hosted redirect_uri, see our API reference.
3. Once the user has completed the Smartcar Connect flow, the onComplete callback in the JavaScript SDK is invoked with the authorization code.
4. Your application front end sends the authorization code to its back-end service.
5. In order to exchange the authorization code for an access_token, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s client_id and client_secret.
6. In response, Smartcar returns an access_token and a refresh_token. These should be stored in your application’s database.
7. Using the access_token, your application can now make API requests to the user’s vehicle.

Mobile application

1. Using the Smartcar iOS SDK or the Smartcar Android SDK, your application launches Smartcar Connect in a browser view. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle.
2. The browser view gets redirected to a special custom-scheme redirect_uri. For more details on how to configure a custom-scheme redirect_uri, see our API reference.
3. Once the user has completed the Smartcar Connect flow, the completion handler in the iOS or Android SDK is invoked with the authorization code.
4. Your mobile application sends the authorization code to its back-end service.
5. In order to exchange the authorization code for an access_token, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s client_id and client_secret.
6. In response, Smartcar returns an access_token and a refresh_token. These should be stored in your application’s database.
7. Using the access_token, your application can now make API requests to the user’s vehicle.

2. Adapt Smartcar Connect to your use case

Fit Smartcar Connect into the user journey

To increase conversions and maximize your users’ satisfaction, it is crucial to launch Smartcar Connect at the right moment in your product’s user journey.

We recommend prompting the user to connect their car through Smartcar Connect while they are onboarding their vehicle to your application for the first time.

Standard: Let the user connect one or more vehicles

In the standard Smartcar Connect flow, the user selects their car brand and logs in with the username and password of their vehicle’s connected services account. On the next screen, the user can see all vehicles associated with their account. The user can select one or multiple of these vehicles and grant your application access to them.

We recommend using the standard Smartcar Connect flow whenever you don’t yet know the make or VIN of your user’s vehicle(s). If you know the make or VIN of your user’s vehicle(s), we recommend personalizing the Smartcar Connect flow in the following ways:

Optional: Skip the car brand selection screen

Optional: Check a vehicle’s eligibility before launching Smartcar Connect

Note: The Compatibility API is only available for vehicles sold in the United States.

Optional: Make sure the user connects the right vehicle

3. Set optional and/or required permissions

Optional permissions

Not all vehicles are capable of all permissions. For example, Tesla vehicles aren’t capable of the read_fuel permission, because they don’t have fuel tanks. In order to handle this smoothly, all permissions that your application requests access to in Smartcar Connect are optional by default.

For example, let’s assume that your app requests access to the read_location and the read_fuel permissions. A user connects their Tesla vehicle through Smartcar Connect. The user is able to successfully authorize their vehicle, because both, the read_location and the read_fuel permission are optional. In the background, your application is granted permission to the read_location endpoint only, because the vehicle is incapable of the read_fuel permission.

const permissions = await vehicle.permissions();
console.log(permissions);

Required permissions

If certain permissions are essential to your application’s use case, you can make them required by adding the required: prefix to each pertaining permission within the scope parameter (e.g. required:read_fuel). The user is then able to authorize a vehicle only if the vehicle is capable of all required permissions.

For example, let’s assume that you mark both read_location and read_fuel as required in the scope parameter. A user tries to connect their Tesla vehicle through Smartcar Connect. As Tesla vehicles are incapable of the read_fuel permission, the user isn’t able to successfully authorize their vehicle. Instead, Smartcar sends the vehicle_incompatible error back to your application.

const client = new smartcar.AuthClient({
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  redirectUri: REDIRECT_URI,
});
const scope = ['required:read_location', 'required:read_fuel'];
const authUrl = client.getAuthUrl(scope);