-
Notifications
You must be signed in to change notification settings - Fork 20
/
README.mdt
142 lines (108 loc) · 5.28 KB
/
README.mdt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
# Smartcar Java SDK [![Build Status][ci-image]][ci-url] [![Code Coverage][coverage-image]][coverage-url] [![JavaDoc][javadoc-image]][javadoc-url] [![Maven Central][maven-image]][maven-url]
## Resources
* [Smartcar Developer Dashboard][smartcar-developer]
* [Smartcar API Reference][smartcar-docs-api]
* [Smartcar Java SDK Documentation][smartcar-sdk-javadoc]
## Installation
The recommended method for obtaining the SDK is via Gradle or Maven through the Maven Central repository. Direct download links are also provided below.
### Gradle
```groovy
compile "${libGroup}:${libName}:${libVersion}"
```
### Maven
```xml
<dependency>
<groupId>${libGroup}</groupId>
<artifactId>${libName}</artifactId>
<version>${libVersion}</version>
</dependency>
```
### Jar Direct Download
* [${libName}-${libVersion}.jar](https://repo1.maven.org/maven2/com/smartcar/sdk/java-sdk/${libVersion}/java-sdk-${libVersion}.jar)
* [${libName}-${libVersion}-sources.jar](https://repo1.maven.org/maven2/com/smartcar/sdk/java-sdk/${libVersion}/java-sdk-${libVersion}-sources.jar)
* [${libName}-${libVersion}-javadoc.jar](https://repo1.maven.org/maven2/com/smartcar/sdk/java-sdk/${libVersion}/java-sdk-${libVersion}-javadoc.jar)
Signatures and other downloads available at [Maven Central](https://central.sonatype.com/artifact/com.smartcar.sdk/java-sdk/${libVersion}).
## Usage
### Authentication
For authentication, Smartcar uses the [authorization code request][1] flow of
the [OAuth 2.0 specification][2]. Before you can make successful calls to the
Smartcar platform, you will need to authenticate with Smartcar, and then obtain
a valid access token for the target vehicle.
1. Make sure you have your application set up in the
[Smartcar Developer Dashboard][smartcar-developer]. You will need the following 3 pieces of
information associated with your application:
* Client ID
* Client Secret
* Redirect URI
2. You can then generate an authentication URL for your user:
```java
// Setup
String clientId = "";
String clientSecret = "";
String redirectUri = "";
String[] scope = {};
String mode = "test";
// Initialize a new AuthClient with your credentials.
AuthClient authClient = new AuthClient.Builder
.clientId(clientId)
.clientSecret(clientSecret)
.redirectUri(redirectUri)
.mode(mode);
// Retrieve the auth URL to start the OAuth flow.
String authUrl = authClient.authUrlBuilder(scope)
.setApprovalPrompt(true)
.setState("some state")
.build();
```
3. Allow the user to complete their portion of the OAuth flow using the
generated URL.
4. Once the user is sent back to the redirect url, the required
authorization code will be included in the query string:
`https://redirect-url.example.com/?code=<AUTHORIZATION_CODE>`
5. Given the authorization code, you can now exchange it for an authorization
token which can be used to access the Smartcar platform:
```java
Auth auth = authClient.exchangeCode(code);
```
### Vehicle Data & Commands
Now that you have authenticated and can access the Smartcar platform, you can
start making requests to vehicles.
1. Obtain a list of authorized vehicles:
```java
VehicleIds response = AuthClient.getVehicleIds(auth.getAccessToken());
String[] vehicleIds = response.getVehicleIds();
```
2. Create an instance of `Vehicle`:
```java
Vehicle vehicle = new Vehicle(vehicleIds[0], auth.getAccessToken());
```
3. You can now access all information about the specified vehicle:
```java
// Retrieve the vehicle's VIN
String vin = vehicle.vin().getVin();
// Read the vehicle's odometer
VehicleOdometer odometerData = vehicle.odometer();
double odometer = odometerData.getDistance();
// Retrieve the vehicle's location
VehicleLocation locationData = vehicle.location();
String latLong = locationData.getLatitude() + ", " + locationData.getLongitude();
// Lock and unlock the vehicle
vehicle.lock();
vehicle.unlock();
```
## Supported Java Releases
Smartcar aims to support the SDK on all LTS Java releases (and Java 8) until the "Extended Support" date as defined in the Oracle Java SE Support Roadmap
In accordance with the Semantic Versioning specification, the addition of support for new Java releases would result in a MINOR version bump and the removal of support for Java releases would result in a MAJOR version bump.
[1]: https://tools.ietf.org/html/rfc6749#section-1.3.1
[2]: https://tools.ietf.org/html/rfc6749
[smartcar-developer]: https://developer.smartcar.com
[smartcar-docs-api]: https://smartcar.com/docs
[smartcar-sdk-javadoc]: https://smartcar.github.io/java-sdk
[ci-image]: https://travis-ci.com/smartcar/java-sdk.svg?token=jMbuVtXPGeJMPdsn7RQ5&branch=master
[ci-url]: https://travis-ci.com/smartcar/java-sdk
[coverage-image]: https://codecov.io/gh/smartcar/java-sdk/branch/master/graph/badge.svg?token=nZAITx7w3X
[coverage-url]: https://codecov.io/gh/smartcar/java-sdk
[javadoc-image]: https://img.shields.io/badge/javadoc-${libVersion}-brightgreen.svg
[javadoc-url]: https://smartcar.github.io/java-sdk
[maven-image]: https://img.shields.io/maven-central/v/com.smartcar.sdk/java-sdk.svg?label=Maven%20Central
[maven-url]: https://central.sonatype.com/artifact/com.smartcar.sdk/java-sdk