Market App Session

Market Apps are independently deployed web applications that run inside of the native Maven application. When loading a Market App, we want to promote a fluid user experience so drivers aren't having to log in to multiple apps or otherwise provide basic information such as what vehicle they are driving or what is their current location.

To enable the above, we introduce the concept of a Market App Session. This session acts as the integration glue between the native mobile application and your Market App by providing all the necessary context needed to present a good user experience to the driver. When loading a Market App, Maven will generate a session and pass a reference to it (called a sessionToken) to your application (via a URL param) that can then be used to retrieve the session data.

A Maven session currently includes the following data:

Driver details. Basic information on which driver is viewing your Market App.
Driver <> vehicle association: What vehicle is the driver currently using?
Latest vehicle ping: The latest telematics ping of the vehicle that the driver is using.
Current device location: A GPS coordinate of the device the driver is using to view your Market App.

Sessions are static. That is, when generating a session, Maven will take a snapshot of the information above and store it for the duration of the session's lifespan. Sessions are short lived and will automatically expire on the server so stale information is not sent to any application.

Maven has 2 options to consume session data:

Using the Market App Javascript Web SDK (preferred).
Calling the GET Session API manually.

Market App Web SDK (JavaScript)

Maven offers a Market App Web SDK for JavaScript to aid in the development of a Market App. This includes methods to retrieve a Market App Session.

Installation (via CDN)

Include the SDK via a script tag in your web application.

<scipt src="https://sdk.mavenmachines.com/marketapps.sdk.0.1.0.min.js" defer="" />

When the SDK is loaded into the browser, all methods are accessible via the global maven variable.

Get the sessionToken

When loading a Market App, the native Maven application will pass some data (including the session token) as part of a URL parameter called requestContext. This requestContext is a URL encoded string containing information that the SDK uses to initialize itself.

For example, if the entry point of your Market App is https://my-market-app.com/, Maven will load the app with the following URL: https://my-market-app.com?requestContext=<requestContextString>. This requestContext can be passed directly into the SDK to retrieve a session.

const appId = "YOUR-APP-ID";
const apiKey = "YOUR-API-KEY";

const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
const requestContext = urlParams.get("requestContext");

const session = await maven.getSessionFromRequestContext(appId, apiKey, requestContext);

The returned session object from the SDK can then be used to get access to the session data.

const session = await maven.getSessionFromRequestContext(appId, apiKey, requestContext);

const deviceLocation = await session.getLatestDeviceLocation();
const driver = await session.getDriver();
const vehiclePing = await session.getLatestVehiclePing();
const association = await session.getActiveDriverVehicleAssociation();

SDK Configuration

The SDK can be configured with a few options using the maven.configure() method. This method should be called before any other operation in the SDK.

The available configuration options are as follows:

Parameter	Default Value	Options
`sdkBaseUrl`	`"https://integrations.mavenmachines.com"`	Configures the API endpoint used by the SDK. Used for changing environments. For production: `"https://integrations.mavenmachines.com"` For staging: `"https://integrations-staging.mavenmachines.com"`
`mode`	`"production"`	Useful for unit testing / generating mock data. Options are: `"production"`, `"sandbox"`

Example:

maven.configure({
  mode: "sandbox"
});

// WIll return mock data
const session = await maven.getSessionFromRequestContext(appId, apiKey, requestContext);

Get Session API

In order to support other development environments, access to the session data can be retrieved manually by making a direct API call to the Get Session API.

In order to do this, you will need to manually parse the requestContext URL parameter to retrieve the session token to pass into the API. requestContext is a URL encoded string that contains a JSON object. A code example in JavaScipt is below:

const API_KEY = "YOUR-API-KEY";
const SESSION_ENDPOINT = "https://integrations.mavenmachines.com/marketapps/session";

function getSessionFromAPI(sessionToken) {
  const endpoint = new URL(SESSION_ENDPOINT);
  endpoint.searchParams.set('sessionToken', sessinoToken);

  const response = await fetch(endpoint, {
    method: "GET",
    mode: "cors",
    headers: {
      'apiKey': apiKey
    }
  });
  
  return response;
}

// Get the request context from URL
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
const requestContext = urlParams.get("requestContext");

try {
  // Decode and parse
  const decoded = decodeURIComponent(requestContext);
  const parsedContext = JSON.parse(decoded);	
 	
  // The `sessionToken` can be found from the `marketAppSessionToken` parameter in the
  // requestContext JSON object.
  const apiResponse = getSessionFromAPI(parsedContext.marketAppSessionToken);
} catch (e) {
  // Some erorr in parsing or fetching data
  console.error(e);
}

Reference documentation for the get session API can be found here.