Smartcar

In order to register Smartcar vehicle, you need to:

1. Initialize SDK client.
2. Register a vehicle.
3. Send authorization code to Hiven.
4. Get devices list.

Prerequisites

Before starting registering vehicle, you need to send Hiven the redirectUri (URL you want Smartcar to redirect back after successful authentication) to be added to the whitelist.

Step 1: Initialize SDK Client

Initialize Client using the Hiven apiUrl (optional, defaults to https://api.hiven.energy) and headersGetter (optional, defaults to async () => ({})) providing custom authorization headers.

import { createClient } from '@hiven-energy/hiven-client';

const client = createClient({
  apiUrl: '<apiUrl>',
  headersGetter: async () => ({
    'X-Api-Key': '<apiKey>',
    'X-User-Id': '<userId>',
  }),
});

Step 2: Register a Vehicle

Register a vehicle by retrieving authorization url and redirecting user to it:

import { VehicleManufacturer } from '@hiven-energy/hiven-client';

// ...
export const getApplicationRedirectUri = (): string => {
  // Return redirect url to your application
};

const handleAuthorize = async (manufacturer: VehicleManufacturer) => {
  // ...
  const { authorizationUrl } = await client.getSmartcarAuthorizationUrl(
    manufacturer,
    getApplicationRedirectUri(),
    countryCode,
  );
  console.log('URL: ', decodeURIComponent(authorizationUrl));
  // Redirect user to received "authorizationUrl"
};

Step 3: Send Authorization Code to Hiven

Read authorization code (code) from query parameters and send it to Hiven:

const sendAuthorizationCode = async (code: string) => {
  await client.registerSmartcarVehicle({ code, redirectUri: getApplicationRedirectUri() });
};

Hiven will exchange it to access token and take care of keeping tokens up to date.

Step 3.1: Tesla-Specific Virtual Keys

After exchanging authorization code to access token, if you're onboarding Tesla vehicle, read Vierual Key URL (virtual_key_url) from query parameters and redirect user to its value:

const performVirtualKeyAddition = async (virtualKeyUrl: string) => {
  await openBrowser(virtualKeyUrl);
};

Step 4: Get Devices List

As soon as 200 response is received after sending authorization code to Hiven, the vehicle should already be added.

Validate it by fetching the list of vehicles:

client.getDevicesList(userId: string, options?: Options);

Important note: The userId is a unique identifier of a user in your system. Read more here.

Important note[2]: Hiven stores access and refresh tokens in Hiven Backend, so you don't have to worry about it.

Step 5: Validate Start/Stop Capability (Optional)

Validation is useful to verify if vehicle is smart-charge capable without pairing a charger or if Tesla Virtual Key for 3rd-party was not granted.

client.getVehicleCapabilities(deviceId: string, forceRefresh: boolean, options?: Options);

Options parameter

Every SDK method is shipped with an optional options?: Options parameter which allows to overwrite any header, set in the headersGetter function during client creation:

interface Options {
  headers: Record<string, any>;
}