Amazon Location Service - Getting Started with First Map App

` element in your HTML to hold the map. You can style this `

` in your CSS to set dimensions as needed for your application. You must download the CSS file, `style.css`, from our GitHub repository. This will help you focus on business logic. Save the `style.css` and `index.html` files in the same folder. Download the `style.css` file from [GitHub](https://github.com/aws-geospatial/amazon-location-samples-js/blob/quick_start_sample_js/quick-start/style.css). ```

``` #### Add API key and AWS Region details Add the API key you created in [Use API keys to authenticate](using-apikeys.md) to this file, along with the AWS Region where the key was created. ``` ..... .....

``` ### Add Map to your application In this section, we will add Map capabilities to the application. Before you start, your files should be in this folder structure. If have not already done so, please download the `style.css` file from [GitHub](https://github.com/aws-geospatial/amazon-location-samples-js/blob/quick_start_sample_js/quick-start/style.css). ``` |---FirstApp [Folder] |-------------- index.html [File] |-------------- style.css [File] ``` #### Create a Function to Initialize the Map To set up your map, create the following function, `initializeMap(...)`, after the line `//Add functions`. Choose an initial center location and zoom level. In this example, we set the map center to Vancouver, Canada, with a zoom level of 10. Add navigation controls for easy zooming. ``` /** * Initializes the map with the specified style and color scheme. */ function initializeMap(mapStyle = "Standard", colorScheme = "Dark") { const styleUrl = `https://maps.geo.${AWS_REGION}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${API_KEY}&color-scheme=${colorScheme}`; const map = new maplibregl.Map({ container: 'map', // The ID of the map container style: styleUrl, // The style URL for the map center: [-123.116226, 49.246292], // Starting center coordinates zoom: 10, // Initial zoom level validateStyle: false // Disable style validation }); return map; // Return the initialized map } ``` #### Initialize the Map Call `initializeMap(...)` to initialize the map. Optionally, you can initialize it with your preferred style and color scheme after the `initializeMap` function. For more style options, see [AWS map styles and features](map-styles.md). ``` // Step 1: Setup API Key and AWS Region const API_KEY = "Your_API_Key"; const AWS_REGION = "Region_where_you_created_API_Key"; // Step 2.1 Add maps to application // Step 2.2 initialize the map const map = initializeMap("Standard","Light"); // Step 3: Add places features to application ``` Open `index.html` in a browser to see the map in action. #### Add Navigation Control Optionally, you can add navigation controls (zoom and rotation) to the map. This should be done after calling `initializeMap(...)`. ``` // Step 2.1 initialize the map const map = initializeMap("Standard","Light"); // Step 2.2 Add navigation controls to the map map.addControl(new maplibregl.NavigationControl()); // Step 3: Add places features to application ``` #### Review the Map Code Congratulations\$1 Your first app is ready to use a map. Open `index.html` in a browser. Make sure `style.css` is in the same folder as `index.html`. Your final HTML should look like this: ``` Amazon Location Service - Getting Started with First Map App

``` ### Add Places to your application In this section, we will set up add places capabilities to the application. Download the JavaScript file from GitHub, [https://github.com/aws-geospatial/amazon-location-samples-js/blob/quick_start_sample_js/quick-start/utils.js](https://github.com/aws-geospatial/amazon-location-samples-js/blob/quick_start_sample_js/quick-start/utils.js). Before you start, your files should be in this folder structure: ``` |---FirstApp [Folder] |-------------- index.html [File] |-------------- style.css [File] |-------------- utils.js [File] ``` #### Create Function to Create GeoPlaces To add search functionality, initialize the `GeoPlaces` class using `AuthHelper` and `AmazonLocationClient`. Add the following `getGeoPlaces(map)` function before the `` tag in `index.html`. ``` /** * Gets a GeoPlaces instance for Places operations. */ function getGeoPlaces(map) { const authHelper = amazonLocationClient.withAPIKey(API_KEY, AWS_REGION); // Authenticate using the API key and AWS region const locationClient = new amazonLocationClient.GeoPlacesClient(authHelper.getClientConfig()); // Create a GeoPlaces client const geoPlaces = new GeoPlaces(locationClient, map); // Create GeoPlaces instance return geoPlaces; // Return the GeoPlaces instance } ``` #### Create Function to Add Search Box to the Application Add the following `addSearchBox(map, geoPlaces)`, `renderPopup(feature)`, and `createPopup(feature)` functions before the `` tag in `index.html` to complete the search functionality setup. ``` /** * Adds search box to the map. */ function addSearchBox(map, geoPlaces) { const searchBox = new MaplibreGeocoder(geoPlaces, { maplibregl, showResultsWhileTyping: true, // Show results while typing debounceSearch: 300, // Debounce search requests limit: 30, // Limit number of results popuprender: renderPopup, // Function to render popup reverseGeocode: true, // Enable reverse geocoding zoom: 14, // Zoom level on result selection placeholder: "Search text or nearby (lat,long)" // Placeholder text for search box. }); // Add the search box to the map map.addControl(searchBox, 'top-left'); // Event listener for when a search result is selected searchBox.on('result', async (event) => { const { id, result_type } = event.result; // Get result ID and type if (result_type === "Place") { // Check if the result is a place const placeResults = await geoPlaces.searchByPlaceId(id); // Fetch details for the selected place if (placeResults.features.length) { createPopup(placeResults.features[0]).addTo(map); // Create and add popup for the place } } }); } /** * Renders the popup content for a given feature. */ function renderPopup(feature) { return ` `; } /** * Creates a popup for a given feature and sets its position. */ function createPopup(feature) { return new maplibregl.Popup({ offset: 30 }) // Create a new popup .setLngLat(feature.geometry.coordinates) // Set the popup position .setHTML(renderPopup(feature)); // Set the popup content } ``` #### Add Search Box to the Application Create a `GeoPlaces` object by calling `getGeoPlaces(map)` as defined in Section 3.1 and then call `addSearchBox(map, geoPlaces)` to add the search box to the application. ``` // Step 2: Add maps to application // Step 2.1 initialize the map const map = initializeMap("Standard","Light"); // Step 2.2 Add navigation controls to the map map.addControl(new maplibregl.NavigationControl()); // Step 3: Add places feature to application // Step 3.1: Get GeoPlaces instance. It will be used for adding search box and map click functionality const geoPlaces = getGeoPlaces(map); // Step 3.2: Add search box to the map addSearchBox(map, geoPlaces); ``` Your place search is ready to use. Open `index.html` in a browser to see it in action. #### Add Function to Show Popup on User Click on the Map Create a function `addMapClick(map, geoPlaces)` to display a popup when the user clicks on the map. Add this function just before the `` tag. ``` /** * Sets up reverse geocoding on map click events. */ function addMapClick(map, geoPlaces) { map.on('click', async ({ lngLat }) => { // Listen for click events on the map const response = await geoPlaces.reverseGeocode({ query: [lngLat.lng, lngLat.lat], limit: 1, click: true }); // Perform reverse geocoding if (response.features.length) { // If there are results const clickMarker = new maplibregl.Marker({ color: "orange" }); // Create a marker const feature = response.features[0]; // Get the clicked feature const clickedPopup = createPopup(feature); // Create popup for the clicked feature clickMarker.setLngLat(feature.geometry.coordinates) // Set marker position .setPopup(clickedPopup) // Attach popup to marker .addTo(map); // Add marker to the map clickedPopup.on('close', () => clickMarker.remove()).addTo(map); // Remove marker when popup is closed } }); } ``` #### Call Function to Add Map Click Feature To enable the map click action, call `addMapClick(map, geoPlaces)` after the line containing `addSearchBox(map, geoPlaces)`. ``` // Step 3: Add places feature to application // Step 3.1: Get GeoPlaces instance. It will be used for adding search box and map click functionality const geoPlaces = getGeoPlaces(map); // Step 3.2: Add search box to the map addSearchBox(map, geoPlaces); // Step 3.3: Setup map click functionality addMapClick(map, geoPlaces); ``` #### Review Maps and Places application Congratulations\$1 Your first application is ready to use Maps and Places. Open `index.html` in a browser. Make sure `style.css` and `utils.js` are in the same folder with `index.html`. Your final HTML should look like this: ``` Amazon Location Service - Getting Started with First Map App

``` ### Explore more You have completed the quick start tutorial, and should have an idea of how Amazon Location Service is used to build applications. To get more out of Amazon Location, you can check out the following resources: + **Query suggestion details** - Consider extending the `GeoPlaces` class or using a similar approach to `ReverseGeocode` to get more details about results returned by the `Suggestion` API. + **Choose the right API for your business needs** - To determine the best Amazon Location API for your requirements, check out this resource: [Choose the right API](choose-an-api.md). + **Check out Amazon Location "how-to" guides** - Visit the [Amazon Location Service Developer Guide](https://docs.aws.amazon.com/location/) for tutorials and further resources. + **Documentation and product information** - For complete documentation, visit the [Amazon Location Service Developer Guide](https://docs.aws.amazon.com/location/) . To learn more about the product, go to the [Amazon Location Service Product](https://aws.amazon.com/location) page. # Create your first Geofences and Trackers application In this section, you'll create an application that demonstrates the key features of using the Amazon Location Geofences and Trackers. The applications demonstrate how a tracker and geofence interact using a combination of Lambda, AWS IoT, and Amazon Location features. Choose iOS or Android platform to get started. Before you start to build your application, follow the procedures in [Use the Amazon Location Service console to authenticate](set-up-auth.md) to grant appropriate access. **Topics** + [Create an iOS application](ios-geofence-app.md) + [Create an Android application](android-geofence-app.md) # Create an iOS application Follow these procedures to build an iOS application using Amazon Location Service. Clone the project files from [GitHub](https://github.com/aws-geospatial/amazon-location-samples-ios/tree/main/tracking-with-geofence-notifications). ## Create Amazon Location resources for your app You can generate Amazon Location Service resources once your AWS account is ready. These resources will be essential for executing the provided code snippets. **Note** If you haven't created an AWS account yet, please [create an AWS account](https://portal.aws.amazon.com/billing/signup#/start/email). To begin you will need to create a Amazon Cognito Identity Pool Id, use the following procedure: 1. In the AWS console, navigate to the Amazon Cognito service and then select **Identity pools** from the left side menu and select **Create Identity pool**. 1. Make sure **Guest Access** is checked, and press **Next** to continue. 1. Next create a new IAM role or Use an existing IAM role. 1. Enter an Identity pool name, and make sure Identity Pool has access to Amazon Location `(geo)` resources for the map and tracker you will be creating in the next procedure. 1. Now you need to create and style a map in the AWS Amazon Location console, use the following procedure: 1. Navigate to the [Maps section](https://console.aws.amazon.com/location/maps/home) in the Amazon Location console and select **Create Map** to preview available map styles. 1. Give the new map resource a **Name** and **Description**. Record the name you assign to the map resource, as it is used later in the tutorial. 1. When choosing a map style, consider the map data provider. Refer to section 82 of the [AWS service terms](http://aws.amazon.com/service-terms) for more details. 1. Accept the [Amazon Location Terms and Conditions](https://aws.amazon.com/service-terms/#:~:text=82.%20Amazon%20Location%20Service), then select **Create Map**. After map has been created, you can interact with the map by zooming in, out, or panning in any direction. To create a tracker using the Amazon Location console 1. Open the [Amazon Location Service console](https://console.aws.amazon.com/location/). 1. In the left navigation pane, choose **Trackers**. 1. Choose **Create tracker**. 1. Fill in the all the required fields. 1. Under **Position filtering**, choose the option that best fits how you intend to use your tracker resource. If you do not set Position filtering, the default setting is TimeBased. For more information, see Trackers in this guide, and PositionFiltering in the Amazon Location Service Trackers API Reference. 1. Choose **Create tracker** to finish. ## Create a Geofence Collection When creating a geofence collection you can use either the console, API or CLI. The following procedures walk you through each option. Create a geofence collection using the Amazon Location console: 1. Open the Amazon Location Service console at https://console.aws.amazon.com/location/. 1. In the left navigation pane, choose Geofence Collections. 1. Choose Create geofence collection. 1. Provide a name and description for the collection. 1. Under EventBridge rule with CloudWatch as a target, you can create an optional EventBridge rule to get started reacting to geofence events. This enables Amazon Location to publish events to Amazon CloudWatch Logs. 1. Choose Create geofence collection. Create a geofence collection using the Amazon Location APIs: Use the CreateGeofenceCollection operation from the Amazon Location Geofences APIs. The following example uses an API request to create a geofence collection called `GOECOLLECTION_NAME`. ``` POST /geofencing/v0/collections Content-type: application/json { "CollectionName": "GOECOLLECTION_NAME", "Description": "Geofence collection 1 for shopping center", "Tags": { "Tag1" : "Value1" } } ``` Create a geofence collection using AWS CLI commands: Use the create-geofence-collection command. The following example uses an AWS CLI to create a geofence collection called `GOECOLLECTION_NAME`. ``` aws location \ create-geofence-collection \ --collection-name "GOECOLLECTION_NAME" \ --description "Shopping center geofence collection" \ --tags Tag1=Value1 ``` ## Link a tracker to a geofence collection To link a tracker to a geofence collection you can use either the console, API, or CLI. The following procedures walk you through each option. Link a tracker resource to a geofence collection using the Amazon Location Service console: 1. Open the Amazon Location console. 1. In the left navigation pane, choose **Trackers**. 1. Under **Device Trackers**, select the name link of the target tracker. 1. Under **Linked Geofence Collections**, choose **Link Geofence Collection**. 1. In the **Linked Geofence Collection window**, select a geofence collection from the dropdown menu. 1. Choose **Link**. 1. After you link the tracker resource, it will be assigned an Active status. Link a tracker resource to a geofence collection using the Amazon Location APIs: Use the ``AsssociateTrackerConsumer operation from the Amazon Location Trackers APIs. The following example uses an API request that associates ExampleTracker with a geofence collection using its Amazon Resource Name (ARN). ``` POST /tracking/v0/trackers/ExampleTracker/consumers Content-type: application/json { "ConsumerArn": "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME" } ``` Link a tracker resource to a geofence collection using AWS CLI commands: Use the `associate-tracker-consumer ` command. The following example uses an AWS CLI to create a geofence collection called `GOECOLLECTION_NAME`. ``` aws location \ associate-tracker-consumer \ --consumer-arn "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME" \ --tracker-name "ExampleTracker" ``` ## Use AWS Lambda with MQTT Create a Lambda function: To create a connection between AWS IoT Core and Amazon Location Service, you need an AWS Lambda function to process messages forwarded by EventBridge CloudWatch events. This function will extract any positional data, format it for Amazon Location Service, and submit it through the Amazon Location Tracker API. You can create this function through the AWS Lambda console, or you can use the AWS Command Line Interface (AWS CLI) or the AWS Lambda APIs. To create a Lambda function that publishes position updates to Amazon Location using the console: 1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/. 1. From the left navigation, choose Functions. 1. Choose Create Function, and make sure that Author from scratch is selected. 1. Fill out the following boxes: + a Function name + for the **Runtime** option, choose Node.js 16.x. 1. Choose Create function. 1. Choose the Code tab to open the editor. 1. Overwrite the placeholder code in index.js with the following: ``` const AWS = require('aws-sdk') const iot = new AWS.Iot(); exports.handler = function(event) { console.log("event===>>>", JSON.stringify(event)); var param = { endpointType: "iot:Data-ATS" }; iot.describeEndpoint(param, function(err, data) { if (err) { console.log("error===>>>", err, err.stack); // an error occurred } else { var endp = data['endpointAddress']; const iotdata = new AWS.IotData({endpoint: endp}); const trackerEvent = event["detail"]["EventType"]; const src = event["source"]; const time = event["time"]; const gfId = event["detail"]["GeofenceId"]; const resources = event["resources"][0]; const splitResources = resources.split("."); const geofenceCollection = splitResources[splitResources.length - 1]; const coordinates = event["detail"]["Position"]; const deviceId = event["detail"]["DeviceId"]; console.log("deviceId===>>>", deviceId); const msg = { "trackerEventType" : trackerEvent, "source" : src, "eventTime" : time, "geofenceId" : gfId, "coordinates": coordinates, "geofenceCollection": geofenceCollection }; const params = { topic: `${deviceId}/tracker`, payload: JSON.stringify(msg), qos: 0 }; iotdata.publish(params, function(err, data) { if (err) { console.log("error===>>>", err, err.stack); // an error occurred } else { console.log("Ladmbda triggered===>>>", trackerEvent); // successful response } }); } }); } ``` 1. Choose Deploy to save the updated function. 1. Choose the Configuration tab. 1. In the Triggers section, click on Add trigger. 1. Select EventBridge (CloudWatch Events) in Source field. 1. Select `Existing Rules` radio option. 1. Enter the rule name like this `AmazonLocationMonitor-GEOFENCECOLLECTION\$1NAME`. 1. Click on the Add button. 1. This will also attach `Resource-based policy statements` in permissions tab MQTT Test Client 1. Open the [https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/). 1. In the left navigation pane, choose MQTT test client. 1. You'll see a section titled **MQTT test client** where you can configure your MQTT connection. 1. After configuring the necessary settings, click on the **Connect** button to establish a connection to the MQTT broker using the provided parameters. 1. Make note of the Endpoint value. Once connected, you can subscribe to MQTT topics or publish messages to topics using the respective input fields provided in the MQTT test client interface. Next you will attach the MQTT Policy: 1. On the left side menu, under **Manage** expand **Security** option and click on **Policies**. 1. Click on **Create Policy** button. 1. Enter a policy name. 1. On **Policy Document** select **JSON** tab. 1. Copy paste the policy shown below, but make sure to update all elements with your `REGION` and `ACCOUNT_ID`: ``` { "Version": "2012-10-17", "Statement": [ { "Action": [ "iot:Connect", "iot:Publish", "iot:Subscribe", "iot:Receive" ], "Resource": [ "arn:aws:iot:REGION:ACCOUNT_ID:client/${cognito-identity.amazonaws.com:sub}", "arn:aws:iot:REGION:ACCOUNT_ID:topic/${cognito-identity.amazonaws.com:sub}", "arn:aws:iot:REGION:ACCOUNT_ID:topicfilter/${cognito-identity.amazonaws.com:sub}/", "arn:aws:iot:REGION:ACCOUNT_ID:topic/${cognito-identity.amazonaws.com:sub}/tracker" ], "Effect": "Allow" } ] } ``` 1. Select the **Create** button to finish. ## Set up sample app code In order to setup the sample code you must have the following tools installed: + Git + XCode 15.3 or Later + iOS Simulator 16 or later Use this procedure to set up the sample app code: 1. Clone the git repository from this URL: [https://github.com/aws-geospatial/amazon-location-samples-ios/tree/main/tracking-with-geofence-notifications](https://github.com/aws-geospatial/amazon-location-samples-ios/tree/main/tracking-with-geofence-notifications). 1. Open the `AWSLocationSampleApp.xcodeproj` project file. 1. Wait for the package resolution process. 1. **Optional**: On the project navigation menu rename `ConfigTemplate.xcconfig` to `Config.xcconfig` and fill in the following values: ``` IDENTITY_POOL_ID = `YOUR_IDENTITY_POOL_ID` MAP_NAME = `YOUR_MAP_NAME` TRACKER_NAME = `YOUR_TRACKER_NAME` WEBSOCKET_URL = `YOUR_MQTT_TEST_CLIENT_ENDPOINT` GEOFENCE_ARN = `YOUR_GEOFENCE_COLLECTION_NAME` ``` ## Use the sample app After setting up the sample code you can now run the app on an iOS simulator or a physical device. 1. Build and run the app. 1. The app will ask you for location and notification permissions. You need to allow them. 1. Tap on `Cognito Configuration` button. 1. If you have not filled the values in `Config.xcconfig` file you need to fill out the field with the resources values you have created previously in the configuration screen. ``` IDENTITY_POOL_ID = `YOUR_IDENTITY_POOL_ID` MAP_NAME = `YOUR_MAP_NAME` TRACKER_NAME = `YOUR_TRACKER_NAME` WEBSOCKET_URL = `YOUR_MQTT_TEST_CLIENT_ENDPOINT` GEOFENCE_ARN = `YOUR_GEOFENCE_COLLECTION_NAME` ``` 1. Save the configuration 1. You can now see the Filter options for time, distance and accuracy. Use them as per your need. 1. Go to `Tracking` tab in the app and you will see the map and `Start Tracking` button. 1. If you have installed the app on a simulator you may want to simulate location changes. This can be done in Features -> Location menu option. For example select Features -> Location -> Freeway Drive. 1. Tap on `Start Tracking` button. You should see the tracking points on the map. 1. The app is also tracking the locations in the background. So, when you move the app in the background it will ask for your permission to continue tracking in background mode. 1. You can stop the tracking by tapping on `Stop Tracking` button. # Create an Android application Follow these procedures to build an iOS application using Amazon Location Service. Clone the project files from [GitHub](https://github.com/aws-geospatial/amazon-location-samples-android/tree/main/tracking-with-geofence-notifications). ## Create Amazon Location resources for your app You can generate Amazon Location Service resources once your AWS account is ready. These resources will be essential for executing the provided code snippets. **Note** If you haven't created an AWS account yet, please [create an AWS account](https://portal.aws.amazon.com/billing/signup#/start/email). To begin you will need to create a Amazon Cognito Identity Pool Id, use the following procedure: 1. In the AWS console, navigate to the Amazon Cognito service and then select **Identity pools** from the left side menu and select **Create Identity pool**. 1. Make sure **Guest Access** is checked, and press **Next** to continue. 1. Next create a new IAM role or Use an existing IAM role. 1. Enter an Identity pool name, and make sure Identity Pool has access to Amazon Location `(geo)`resources for the map and tracker you will be creating in the next procedure. 1. Now you need to create and style a map in the AWS Amazon Location console, use the following procedure: 1. Navigate to the [Maps section](https://console.aws.amazon.com/location/maps/home) in the Amazon Location console and select **Create Map** to preview available map styles. 1. Give the new map resource a **Name** and **Description**. Record the name you assign to the map resource, as it is used later in the tutorial. 1. When choosing a map style, consider the map data provider. Refer to section 82 of the [AWS service terms](http://aws.amazon.com/service-terms) for more details. 1. Accept the [Amazon Location Terms and Conditions](https://aws.amazon.com/service-terms/#:~:text=82.%20Amazon%20Location%20Service), then select **Create Map**. After map has been created, you can interact with the map by zooming in, out, or panning in any direction. To create a tracker using the Amazon Location console 1. Open the [Amazon Location Service console](https://console.aws.amazon.com/location/). 1. In the left navigation pane, choose **Trackers**. 1. Choose **Create tracker**. 1. Fill in the all the required fields. 1. Under **Position filtering**, choose the option that best fits how you intend to use your tracker resource. If you do not set Position filtering, the default setting is TimeBased. For more information, see Trackers in this guide, and PositionFiltering in the Amazon Location Service Trackers API Reference. 1. Choose **Create tracker** to finish. ## Create a Geofence Collection When creating a geofence collection you can use either the console, API or CLI. The following procedures walk you through each option. Create a geofence collection using the Amazon Location console: 1. Open the Amazon Location Service console at https://console.aws.amazon.com/location/. 1. In the left navigation pane, choose Geofence Collections. 1. Choose Create geofence collection. 1. Provide a name and description for the collection. 1. Under EventBridge rule with CloudWatch as a target, you can create an optional EventBridge rule to get started reacting to geofence events. This enables Amazon Location to publish events to Amazon CloudWatch Logs. 1. Choose Create geofence collection. Create a geofence collection using the Amazon Location APIs: Use the CreateGeofenceCollection operation from the Amazon Location Geofences APIs. The following example uses an API request to create a geofence collection called `GOECOLLECTION_NAME`. ``` POST /geofencing/v0/collections Content-type: application/json { "CollectionName": "GOECOLLECTION_NAME", "Description": "Geofence collection 1 for shopping center", "Tags": { "Tag1" : "Value1" } } ``` Create a geofence collection using AWS CLI commands: Use the create-geofence-collection command. The following example uses an AWS CLI to create a geofence collection called `GOECOLLECTION_NAME`. ``` aws location \ create-geofence-collection \ --collection-name "GOECOLLECTION_NAME" \ --description "Shopping center geofence collection" \ --tags Tag1=Value1 ``` ## Link a tracker to a geofence collection To link a tracker to a geofence collection you can use either the console, API, or CLI. The following procedures walk you through each option. Link a tracker resource to a geofence collection using the Amazon Location Service console: 1. Open the Amazon Location console. 1. In the left navigation pane, choose **Trackers**. 1. Under **Device Trackers**, select the name link of the target tracker. 1. Under **Linked Geofence Collections**, choose **Link Geofence Collection**. 1. In the **Linked Geofence Collection window**, select a geofence collection from the dropdown menu. 1. Choose **Link**. 1. After you link the tracker resource, it will be assigned an Active status. Link a tracker resource to a geofence collection using the Amazon Location APIs: Use the ``AsssociateTrackerConsumer operation from the Amazon Location Trackers APIs. The following example uses an API request that associates ExampleTracker with a geofence collection using its Amazon Resource Name (ARN). ``` POST /tracking/v0/trackers/ExampleTracker/consumers Content-type: application/json { "ConsumerArn": "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME" } ``` Link a tracker resource to a geofence collection using AWS CLI commands: Use the `associate-tracker-consumer ` command. The following example uses an AWS CLI to create a geofence collection called `GOECOLLECTION_NAME`. ``` aws location \ associate-tracker-consumer \ --consumer-arn "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME" \ --tracker-name "ExampleTracker" ``` ## Use AWS Lambda with MQTT Create a Lambda function: To create a connection between AWS IoT Core and Amazon Location Service, you need an AWS Lambda function to process messages forwarded by EventBridge CloudWatch events. This function will extract any positional data, format it for Amazon Location Service, and submit it through the Amazon Location Tracker API. You can create this function through the AWS Lambda console, or you can use the AWS Command Line Interface (AWS CLI) or the AWS Lambda APIs. To create a Lambda function that publishes position updates to Amazon Location using the console: 1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/. 1. From the left navigation, choose Functions. 1. Choose Create Function, and make sure that Author from scratch is selected. 1. Fill out the following boxes: + a Function name + for the **Runtime** option, choose Node.js 16.x. 1. Choose Create function. 1. Choose the Code tab to open the editor. 1. Overwrite the placeholder code in index.js with the following: ``` const AWS = require('aws-sdk') const iot = new AWS.Iot(); exports.handler = function(event) { console.log("event===>>>", JSON.stringify(event)); var param = { endpointType: "iot:Data-ATS" }; iot.describeEndpoint(param, function(err, data) { if (err) { console.log("error===>>>", err, err.stack); // an error occurred } else { var endp = data['endpointAddress']; const iotdata = new AWS.IotData({endpoint: endp}); const trackerEvent = event["detail"]["EventType"]; const src = event["source"]; const time = event["time"]; const gfId = event["detail"]["GeofenceId"]; const resources = event["resources"][0]; const splitResources = resources.split("."); const geofenceCollection = splitResources[splitResources.length - 1]; const coordinates = event["detail"]["Position"]; const deviceId = event["detail"]["DeviceId"]; console.log("deviceId===>>>", deviceId); const msg = { "trackerEventType" : trackerEvent, "source" : src, "eventTime" : time, "geofenceId" : gfId, "coordinates": coordinates, "geofenceCollection": geofenceCollection }; const params = { topic: `${deviceId}/tracker`, payload: JSON.stringify(msg), qos: 0 }; iotdata.publish(params, function(err, data) { if (err) { console.log("error===>>>", err, err.stack); // an error occurred } else { console.log("Ladmbda triggered===>>>", trackerEvent); // successful response } }); } }); } ``` 1. Choose Deploy to save the updated function. 1. Choose the Configuration tab. 1. In the Triggers section, click on Add trigger. 1. Select EventBridge (CloudWatch Events) in Source field. 1. Select `Existing Rules` radio option. 1. Enter the rule name like this `AmazonLocationMonitor-GEOFENCECOLLECTION\$1NAME`. 1. Click on the Add button. 1. This will also attach `Resource-based policy statements` in permissions tab MQTT Test Client 1. Open the [https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/). 1. In the left navigation pane, choose MQTT test client. 1. You'll see a section titled **MQTT test client** where you can configure your MQTT connection. 1. After configuring the necessary settings, click on the **Connect** button to establish a connection to the MQTT broker using the provided parameters. 1. Note down Endpoint value. Once connected, you can subscribe to MQTT topics or publish messages to topics using the respective input fields provided in the MQTT test client interface. Next you will attach the MQTT Policy: 1. On the left side menu, under **Manage** expand **Security** option and click on **Policies**. 1. Click on **Create Policy** button. 1. Enter a policy name. 1. On **Policy Document** select **JSON** tab. 1. Copy paste the policy shown below, but make sure to update all elements with your `REGION` and `ACCOUNT_ID`: ``` { "Version": "2012-10-17", "Statement": [ { "Action": [ "iot:Connect", "iot:Publish", "iot:Subscribe", "iot:Receive" ], "Resource": [ "arn:aws:iot:REGION:ACCOUNT_ID:client/${cognito-identity.amazonaws.com:sub}", "arn:aws:iot:REGION:ACCOUNT_ID:topic/${cognito-identity.amazonaws.com:sub}", "arn:aws:iot:REGION:ACCOUNT_ID:topicfilter/${cognito-identity.amazonaws.com:sub}/", "arn:aws:iot:REGION:ACCOUNT_ID:topic/${cognito-identity.amazonaws.com:sub}/tracker" ], "Effect": "Allow" } ] } ``` **Note** Record the policy name and topic name for use in the next procedure. 1. Select the **Create** button to finish. After completing the previous procedure, you will now update the permissions for the guest role as follows: 1. Navigate to Amazon Cognito and open your identity pool. Then, proceed to user access and select the guest role. 1. Click on permission policies to enable editing. ``` { 'Version': '2012-10-17 ', 'Statement': [ { 'Action': [ 'geo:GetMap*', 'geo:BatchUpdateDevicePosition', 'geo:BatchEvaluateGeofences', 'iot:Subscribe', 'iot:Publish', 'iot:Connect', 'iot:Receive', 'iot:AttachPrincipalPolicy', 'iot:AttachPolicy', 'iot:DetachPrincipalPolicy', 'iot:DetachPolicy' ], 'Resource': [ 'arn:aws:geo:us-east-1:{USER_ID}:map/{MAP_NAME}', 'arn:aws:geo:us-east-1:{USER_ID}:tracker/{TRACKER_NAME}', 'arn:aws:geo:us-east-1:{USER_ID}:geofence-collection/{GEOFENCE_COLLECTION_NAME}', 'arn:aws:iot:us-east-1:{USER_ID}:client/${cognito-identity.amazonaws.com:sub}', 'arn:aws:iot:us-east-1:{USER_ID}:topic/${cognito-identity.amazonaws.com:sub}', 'arn:aws:iot:us-east-1:{USER_ID}:topicfilter/${cognito-identity.amazonaws.com:sub}/*', 'arn:aws:iot:us-east-1:{USER_ID}:topic/${cognito-identity.amazonaws.com:sub}/tracker' ], 'Effect': 'Allow' }, { 'Condition': { 'StringEquals': { 'cognito-identity.amazonaws.com:sub': '${cognito-identity.amazonaws.com:sub}' } }, 'Action': [ 'iot:AttachPolicy', 'iot:DetachPolicy', 'iot:AttachPrincipalPolicy', 'iot:DetachPrincipalPolicy' ], 'Resource': [ '*' ], 'Effect': 'Allow' } ] } ``` 1. With the above policy changes, all necessary AWS resources are now configured appropriately for the application. ## Set up the sample app code 1. Open Android Studio and select **New** and then **Project from Version Control**. 1. Navigate to the **File** menu in Android Studio’s top left corner. 1. Select “New” from the dropdown menu. 1. Choose “Project from Version Control”. 1. Enter Repository URL In the dialogue box that appears, find the field marked “URL”. 1. Copy and paste the following URL for the sample app into this field:[https://github.com/aws-geospatial/amazon-location-samples-android.git](https://github.com/aws-geospatial/amazon-location-samples-android.git) 1. Decide on the directory where you want to clone the repository. Use either the default directory or opt for a custom location. 1. After setting the repository URL and directory preferences, hit the “Clone” button. Android Studio will proceed to clone the repository to your specified location. 1. You have now cloned the application to your machine and can begin using it. ## Use the sample app To use the sample follow these procedures: + **Create a `custom.properties`**: To configure your `custom.properties` file, follow these steps: 1. Open your preferred text editor or IDE. 1. Create a new file. 1. Save the file with the name `custom.properties`. 1. Update the `custom.properties` with the following code sample, and replace the `MQTT_END_POINT`, `POLICY_NAME`, `GEOFENCE_COLLECTION_NAME`, and `TOPIC_TRACKER` with actual values: ``` MQTT_END_POINT=xxxxxxxxxxxxx-xxx.xxx.us-east-1.amazonaws.com POLICY_NAME=xxxxxxxxx GEOFENCE_COLLECTION_NAME=xxxxxxxxxxxxxxxxx TOPIC_TRACKER=xxxxxxxxxx ``` 1. Clean and Rebuild the project. After this, you can run the project. + **Sign In**: To sign in to the application, follow the below steps: 1. Press the **Sign In** button. 1. Provide an **Identity Pool Id**, **Tracker name**, and a **Map name**. 1. Press **Sign In** again to finish. + **Manage Filters**: Open the configuration screen, and perform the following: 1. Toggle filters on/off using the switch UI. 1. Update Time and Distance filters when needed. + **Tracking Operations:** Open the tracking screen and perform the following: + You can start and stop tracking in foreground, background, or in battery-saver mode by pressing respective buttons.