Embedded Explorer Quick Start Guide

Welcome! Let’s start with the basics of integrating Embedded Explorer with your application.

Getting Started

Prerequisites

There are two options available as listed below

Option 1:

You should have been supplied an API Key. Embedded Explorer uses this key to automatically request a session token during initialization. The API key is a passed parameter to the Embedded Explorer mount function. The mount function instantiates the Embedded Explorer object and performs various initialization operations.

Option 2:

You should have been provided an API Client ID and Client Secret. This pair is used to generate access tokens for your front-end application.

Initializing the Viewer

Embedded Explorer is provided as a React component and can be mounted to a DOM node.

1. Add charset mata tag in head section

<meta charset="UTF-8">

2. Load the required scripts, including React and the Embedded Explorer widget.

<script crossorigin src="https://unpkg.com/react@17/umd/react.production.min.js"> </script>
<script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js"></script>
<script crossorigin src="https://embedded-explorer.eagleview.com/static/embedded-explorer-widget.js"></script>

embedded-explorer 3. Create a div with a unique id to mount the map to. The viewer will fill the entire div, so it must be sized as well.

<div id='map' style="height: 100%; width: 100%;"></div>

4. Finally, instantiate the viewer and mount it using the provided mount method. Here we can pass either API Key or token.

API Key Method

const map = new window.ev.EmbeddedExplorer().mount('map', { apiKey:'<API_KEY>' });

Client ID/Secret Method

const map = new window.ev.EmbeddedExplorer().mount('map', { authToken:'<access_token>' });

Generating an Access Token

To generate an access token, make a request from the Authentication API as shown below.:

POST https://api.eagleview.com/auth-service/v1/token HTTP/1.1
Authorization: Basic Base64(client_id:client_secret)
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Note that the Base64 value should be encoded before constructing the request.

A successful request will return the message below:

HTTP/1.1 200 OK
{
  "access_token": "eyJraWQiOiJhTy1PRUtPeH...",
  "expires_in": 86400,
  "scope": "default",
  "token_type": "Bearer"
}

If an error occurs during the request, you may receive one of the following responses:

HTTP/1.1 401 Unauthorized

{
  "errorCode": 60015,
  "errorDescription": "grant_type value not supported."
}

HTTP/1.1 401 Unauthorized
{
  "errorCode": 60003,
  "errorDescription": "the client details are invalid."
}

Notes on Using this Guide

In the reference implementation, we provide a basic ASP.NET example of constructing the authentication request, passing the generated access token to the front end, and initializing the map.

Please note that this doesn’t cover the process of refreshing an expired access token, and instead requests an access token once, when the application starts up.

Interacting with the Viewer

Startup Config

Provide your configuration parameters at startup when initializing the viewer to customize the widget or start with a specific view.

For example:

const map = new window.ev.EmbeddedExplorer().mount('map', { 
  authToken: '<access_token>',
  view: {
    lonLat: {
      lon: 45,
      lat: 23,
    },
  },
});

API Methods

Once you have the viewer up and running, you’ll be able to call the provided API functions to interact with it. These methods are provided directly on the object returned from calling mount in your setup.

For example:

map.setLonLat({ lon: 45, lat: 23})

Annotations

Annotations can be added to the viewer via the respective API methods. For example, the following will add three point annotations, log clicks on them, and then only remove one of them by a user provided id.

map.addFeatures({
  geoJson: [
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [0, 0] },
      properties: { id: 'point-1' },
    },
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [1, 1] },
      properties: { id: 'point-2' },
    },
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [2, 2] },
      properties: { id: 'point-3' },
    },
  ],
});

map.on('featureClick', (features) => {
  for (feature in features.geoJson) {
    console.log(`Feature Clicked! ${feature.properties.id}`);
  }
});

map.removeFeatures({
  geoJson: (feature) => feature.properties.id === 'point-1',
});

For a full list of the available API methods, configuration options, and annotation types, please view the API documentation included with this guide.

For help or questions, please reach out to customersupport@eagleview.com.