Plan your integration
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
-
You can use your preferred language framework for a server-side setup as long as you use OAuth2 Retrieval protocol. In this case:
- Your application redirects the user’s browser to Smartcar Connect.
- The user logs in with the username and password of their vehicle’s connected services account.
- The user grants your application access to their vehicle.
- 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 theredirect_uri
, retrieves the authorizationcode
from query parameters in theredirect_uri
. - In order to exchange the authorization
code
for anaccess_token
, your application makes a request to the Smartcar API. This request must contain the authorizationcode
along with your application’sclient_id
andclient_secret
. - In response, Smartcar returns an
access_token
and arefresh_token
. These should be stored in your application’s database. - Using the
access_token
, your application can now make API requests to the user’s vehicle.
Single-page application
- 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.
- The user’s browser gets redirected to a special Smartcar-hosted
redirect_uri
. For more details on how to configure a Smartcar-hostedredirect_uri
, see our API reference. - Once the user has completed the Smartcar Connect flow, the
onComplete
callback in the JavaScript SDK is invoked with the authorizationcode
. - Your application front end sends the authorization
code
to its back-end service. - In order to exchange the authorization
code
for anaccess_token
, your application makes a request to the Smartcar API. This request must contain the authorizationcode
along with your application’sclient_id
andclient_secret
. - In response, Smartcar returns an
access_token
and arefresh_token
. These should be stored in your application’s database. - Using the
access_token
, your application can now make API requests to the user’s vehicle.
Mobile application
- 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.
- The browser view gets redirected to a special custom-scheme
redirect_uri
. For more details on how to configure a custom-schemeredirect_uri
, see our API reference. - Once the user has completed the Smartcar Connect flow, the completion handler in the iOS or Android SDK is invoked with the authorization
code
. - Your mobile application sends the authorization
code
to its back-end service. - In order to exchange the authorization
code
for anaccess_token
, your application makes a request to the Smartcar API. This request must contain the authorizationcode
along with your application’sclient_id
andclient_secret
. - In response, Smartcar returns an
access_token
and arefresh_token
. These should be stored in your application’s database. - 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
scope
parameter that indicates which permissions your application requests access to.
Every vehicle endpoint has a permission name associated with it. For example, the permission name for the /fuel endpoint is read_fuel
. Please see our API reference for a full list of all permission names.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);