Skip to content

Latest commit

 

History

History
226 lines (173 loc) · 11.8 KB

README.md

File metadata and controls

226 lines (173 loc) · 11.8 KB
Raw

Smartcar JavaScript SDK

Smartcar JavaScript SDK documentation.

Classes

Smartcar

Typedefs

OnComplete : function
WindowOptions : Object

Position and size settings for the popup window.

Smartcar

Kind: global class

new Smartcar(options)

Initializes Smartcar class.

Param Type Default Description
options Object the SDK configuration object
options.clientId String the application's client id
options.redirectUri String the registered redirect uri of the application
[options.scope] Array.<String> requested permission scopes
[options.onComplete] OnComplete called on completion of Smartcar Connect
[options.testMode] Boolean false Deprecated, please use mode instead. Launch Smartcar Connect in test mode.
[options.mode] String 'live' Determine what mode Smartcar Connect should be launched in. Should be one of test, live or simulated.

smartcar.getAuthUrl(options) ⇒ String

Generates Smartcar OAuth URL.

Kind: instance method of Smartcar Returns: String - Connect URL to redirect user to.

Param Type Default Description
options Object the link configuration object
[options.state] String arbitrary state passed to redirect uri
[options.forcePrompt] Boolean false force permission approval screen to show on every authentication, even if the user has previously consented to the exact scope of permission
[options.vehicleInfo.make] String vehicleInfo is an object with an optional property make, which allows users to bypass the car brand selection screen. For a complete list of supported brands, please see our API Reference documentation.
[options.singleSelect] Boolean | Object An optional value that sets the behavior of the grant dialog displayed to the user. If set to true, single_select limits the user to selecting only one vehicle. If single_select is passed in as an object with the property vin, Smartcar will only authorize the vehicle with the specified VIN. See the API reference for more information.
[options.flags] Array.<String> An optional space-separated list of feature flags that your application has early access to.
[options.user] String An optional unique identifier for a vehicle owner. This identifier is used to aggregate analytics across Connect sessions for each vehicle owner.

Example

https://connect.smartcar.com/oauth/authorize?
response_type=code
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&scope=read_odometer read_vehicle_info
&redirect_uri=https://example.com/home
&state=0facda3319
&make=TESLA
&single_select=true
&single_select_vin=5YJSA1E14FF101307
&flags=country:DE color:00819D
&user=2dad4eaf-9094-4bff-bb0f-ffbbdde8b562

smartcar.openDialog(options)

Launches Smartcar Connect in a new window.

Kind: instance method of Smartcar

Param Type Default Description
options Object the link configuration object
[options.state] String arbitrary state passed to redirect uri
[options.forcePrompt] Boolean false force permission approval screen to show on every authentication, even if the user has previously consented to the exact scope of permission
[options.vehicleInfo.make] String vehicleInfo is an object with an optional property make, which allows users to bypass the car brand selection screen. For a complete list of supported makes, please see our API Reference documentation.
[options.singleSelect] Boolean | Object An optional value that sets the behavior of the grant dialog displayed to the user. If set to true, single_select limits the user to selecting only one vehicle. If single_select is passed in as an object with the property vin, Smartcar will only authorize the vehicle with the specified VIN. See the API reference for more information.
[options.flags] Array.<String> An optional space-separated list of feature flags that your application has early access to.
[options.windowOptions] WindowOptions position and size settings for the popup window

smartcar.addClickHandler(options)

Adds an on-click event listener to the element with the provided id.

On-click event calls openDialog when the specified element is clicked.

Kind: instance method of Smartcar

Param Type Default Description
options Object clickHandler configuration object
[options.id] String id of the element to add click handler to
[options.selector] String css selector of the element(s) to add click handler to
[options.state] String arbitrary state passed to redirect uri
[options.forcePrompt] Boolean false force permission approval screen to show on every authentication, even if the user has previously consented to the exact scope of permission
[options.vehicleInfo.make] String vehicleInfo is an object with an optional property make, which allows users to bypass the car brand selection screen. For a complete list of supported makes, please see our API Reference documentation.
[options.singleSelect] Boolean | Object An optional value that sets the behavior of the grant dialog displayed to the user. If set to true, single_select limits the user to selecting only one vehicle. If single_select is passed in as an object with the property vin, Smartcar will only authorize the vehicle with the specified VIN. See the API reference for more information.
[options.flags] Array.<String> An optional space-separated list of feature flags that your application has early access to.
[options.windowOptions] WindowOptions position and size settings for the popup window

smartcar.unmount()

Remove Smartcar's event listeners.

  1. remove listener on the global window object: The Smartcar SDK uses a global 'message' event listener to recieve the authorization code from the pop-up dialog. Call this method to remove the event listener from the global window.

  2. remove click event listeners on DOM elements The Smartcar SDK also provides an addClickHandler method to attach click events to DOM elements. These event listeners will also be removed by calling this unmount method.

Kind: instance method of Smartcar

Smartcar.AccessDenied ⇐ Error

Access denied error returned by Connect.

Kind: static class of Smartcar Extends: Error

new Smartcar.AccessDenied(message)

Param Type Description
message String detailed error description

Smartcar.VehicleIncompatible ⇐ Error

Vehicle incompatible error returned by Connect. Will optionally have a vehicleInfo object if the user chooses to give permissions to provide that information. See our Connect documentation for more details.

Kind: static class of Smartcar Extends: Error

new Smartcar.VehicleIncompatible(message, vehicleInfo)

Param Type Description
message String detailed error description
vehicleInfo Object If a vehicle is incompatible, the user has the option to return vehicleInfo to the application.
vehicleInfo.vin String returned if user gives permission.
vehicleInfo.make String returned if user gives permission.
vehicleInfo.year Number returned if user gives permission.
[vehicleInfo.model] String optionally returned if user gives permission.

Smartcar.InvalidSubscription ⇐ Error

Invalid subscription error returned by Connect.

Kind: static class of Smartcar Extends: Error

new Smartcar.InvalidSubscription(message)

Param Type Description
message String detailed error description

OnComplete : function

Kind: global typedef

Param Type Description
error Error something went wrong in Connect; this normally indicates that the user denied access to your application or does not have a connected vehicle
code String the authorization code to be exchanged from a backend sever for an access token
[state] Object contains state if it was set on the initial authorization request
[virtualKeyUrl] String virtual key URL used by Tesla to register Smartcar's virtual key on a vehicle. This registration will be required in order to use any commands on a Tesla vehicle. It is an optional argument as it is only included in specific cases.

WindowOptions : Object

Position and size settings for the popup window.

Kind: global typedef See: Please reference the Window.open()#Window Features MDN article for more details Properties

Name Type
[top] String
[left] String
[width] String
[height] String