Skip to content

Latest commit

 

History

History
 
 

amazon-location-helpers

README.md

Amazon Location Helpers

amazon-location-helpers helps initialize MapLibre GL JS maps for use with Amazon Location Service. Given an Amazon Cognito Identity Pool ID (or provided an AWS Credentials object) and the name of a Map resource, this will fetch AWS credentials and initialize a Map instance, configured to sign requests with Signature Version 4.

See Allowing unauthenticated guest access to your application using Amazon Cognito for instructions on how to create an Identity Pool. The Identity Pool ID will be used below.

Installation

amazon-location-helpers can be installed from npm for use with apps that include a build step:

npm install amazon-location-helpers

amazon-location-helpers can also be used in static HTML documents. For full functionality, MapLibre GL JS, the AWS SDK for JavaScript, and AWS Amplify Core must be loaded:

<html>
  <head>
    <link
      href="https://unpkg.com/maplibre-gl@1/dist/maplibre-gl.css"
      rel="stylesheet"
    />
  </head>

  <body>
    <div id="map" style="height: 100vh" />
    <script src="https://unpkg.com/maplibre-gl@1"></script>
    <script src="https://unpkg.com/amazon-location-helpers@1"></script>
    <script>
      AmazonLocation.createMap(
        {
          "us-east-1:54f2ba88-9390-498d-aaa5-0d97fb7ca3bd",
        },
        {
          container: "map",
          center: [-123.1187, 49.2819], // initial map centerpoint
          zoom: 10, // initial map zoom
          style: "explore.map,
          hash: true,
        }
      );
    </script>
  </body>
</html>

API

createMap

function createMap(
  config: {
    credentials?: Credentials;
    identityPoolId?: string;
    region?: string;
  },
  options: mapboxgl.MapboxOptions,
  mapgl?: typeof mapboxgl
): Promise<mapboxgl.Map>;

This will instantiate a Map, exchange the provided Amazon Cognito Identity Pool ID for AWS credentials, load the style associated with the explore.map Map resource, and render it to the <div> identified as map, centered on Vancouver, British Columbia:

const map = await AmazonLocation.createMap(
  "us-east-1:54f2ba88-9390-498d-aaa5-0d97fb7ca3bd",
  {
    container: "map",
    center: [-123.1187, 49.2819], // initial map centerpoint
    zoom: 10, // initial map zoom
    style: "explore.map",
  }
);

For a fully worked example, see maplibre-gl-js/index.html.

createRequestTransformer

function createRequestTransformer(config: {
  credentials?: Credentials;
  identityPoolId?: string;
  region?: string;
}): Promise<mapboxgl.TransformRequestFunction>;

This will initialize a transformRequest function suitable for providing to Map's transformRequest property that will intercept requests made by MapLibre GL JS to AWS and sign them using Signature Version 4:

import { createRequestTransformer } from "amazon-location-helpers";

const transformRequest = await createRequestTransformer({
  identityPoolId: "us-east-1:54f2ba88-9390-498d-aaa5-0d97fb7ca3bd",
});

This can then be used with react-map-gl:

// React equivalent to the above example
<ReactMapGL
  latitude={49.2819}
  longitude={-123.1187}
  zoom={10}
  width="100%"
  height="100vh"
  transformRequest={transformRequest}
  mapStyle="explore.map"
/>

For a fully worked example, see maplibre-gl-js-react/src/index.tsx.

getCredentialsForIdentityPool

function getCredentialsForIdentityPool(
  identity: string
): Promise<Credentials>;

This will exchange an Amazon Cognito Identity Pool ID for temporary AWS credentials. For example:

const credentials = await AmazonLocation.getCredentialsForIdentityPool("us-east-1:54f2ba88-9390-498d-aaa5-0d97fb7ca3bd");

// use credentials with other AWS services

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.