With the JavaScript Consumer SDK, your consumer app can show the location of vehicles and other locations of interest tracked in Fleet Engine on a web-based map. This allows your consumer users to see the progress of their shipments. This guide assumes you have set up Fleet Engine with its associated Google Cloud project and API keys. See Fleet Engine for details.
You set up the JavaScript Consumer SDK following these steps:
Enable the Maps JavaScript API
Enable the Maps JavaScript API in the Google Cloud Console project that you use for your Fleet Engine instance. For more details, see Enable APIs in the Maps JavaScript API documentation.
Set up authorization
For API method calls from low-trust environments, Fleet Engine requires the use of JSON Web Tokens (JWTs) signed by an appropriate service account. Low-trust environments include smartphones and browsers. A JWT originates on your server, which is a fully-trusted environment. The JWT is signed, encrypted, and passed to the client for subsequent server interactions until it expires or is no longer valid.
Your backend should authenticate and authorize against Fleet Engine using standard Application Default Credentials mechanisms. Make sure to use JWTs that have been signed by an appropriate service account. For a list of service-account roles, see Fleet Engine service account roles in Fleet Engine Basics.
Your consumer app should authenticate your end users with thedelivery_consumer role from your Google Cloud project to return only
consumer-specific information. In this way, Fleet Engine filters and redacts all
other information in the responses. For example, during an unavailability task,
no location information is shared with an end user. See Service account
roles for scheduled tasks.
In contrast, your backend should authenticate and authorize against Fleet Engine using standard Application Default Credentials mechanisms.
How does authorization work?
Authorization with Fleet Engine data involves both server-side and client-side implementation.
Server-side authorization
Before you set up authentication and authorization in your web-based application, your backend server must be able to issue JSON Web Tokens to your web-based application for access to Fleet Engine. Your web-based application sends these JWTs with its requests so Fleet Engine recognizes the requests as authenticated and authorized to access the data in the request. For instructions on server-side JWT implementation, see Issue JSON Web Tokens under Fleet Engine Essentials.
Specifically, keep in mind the following for the JavaScript Consumer SDK for tracking shipments:- General guidelines for issuing JSON Web Tokens
- Scheduled tasks JWT guidelines
- Example token for a consumer app
Client-side authorization
When you use the JavaScript Consumer SDK, it requests a token from the server using an authorization token fetcher. It does this when any of the following is true:
No valid token exists, such as when the SDK hasn't called the fetcher on a fresh page load, or when the fetcher hasn't returned with a token.
The token has expired.
The token is within one minute of expiring.
Otherwise, the JavaScript Consumer SDK uses the previously-issued, valid token and does not call the fetcher.
Create an authorization token fetcher
Create your authorization token fetcher using these guidelines:
The fetcher must return a data structure with two fields, wrapped in a
Promiseas follows:A string
token.A number
expiresInSeconds. A token expires in this amount of time after fetching. The authentication token fetcher must pass the expiry time in seconds, from the time of fetching to the library as shown in the example.
The fetcher should call a URL on your server to retrieve a token. This URL--the
SERVER_TOKEN_URL--depends on your backend implementation. The following example URL is for the sample app backend on GitHub:https://SERVER_URL/token/delivery_consumer/TRACKING_ID
Example - Create an authentication token fetcher
The following examples show how to create an authorization token fetcher:
JavaScript
async function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
TypeScript
function authTokenFetcher(options: {
serviceType: google.maps.journeySharing.FleetEngineServiceType,
context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
// The developer should generate the correct
// SERVER_TOKEN_URL based on options.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.token,
expiresInSeconds: data.ExpiresInSeconds,
};
}