`中設定此樣式，以視需要為您的應用程式設定維度。您必須從 GitHub 儲存庫下載 CSS 檔案 `style.css`。這將協助您專注於商業邏輯。
將 `style.css`和 `index.html` 檔案儲存在相同的資料夾中。
從 [GitHub](https://github.com/aws-geospatial/amazon-location-samples-js/blob/quick_start_sample_js/quick-start/style.css) 下載 `style.css` 檔案。
```
```
#### 新增 API 金鑰和 AWS 區域詳細資訊
將您在此檔案中建立的 API [使用 API 金鑰進行身分驗證](using-apikeys.md) 金鑰，以及建立金鑰 AWS 的區域。
```
.....
.....
```
### 將地圖新增至您的應用程式
在本節中，我們會將 Map 功能新增至應用程式。開始之前，您的檔案應位於此資料夾結構中。
如果尚未這麼做，請從 [GitHub](https://github.com/aws-geospatial/amazon-location-samples-js/blob/quick_start_sample_js/quick-start/style.css) 下載`style.css`檔案。
```
|---FirstApp [Folder]
|-------------- index.html [File]
|-------------- style.css [File]
```
#### 建立 函數以初始化映射
若要設定映射，請在行 `initializeMap(...)`後面建立下列函數 `//Add functions`。
選擇初始中心位置和縮放層級。在此範例中，我們將地圖中心設定為加拿大 Vancouver，縮放層級為 10。新增導覽控制項以輕鬆縮放。
```
/**
* 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
}
```
#### 初始化映射
呼叫 `initializeMap(...)` 以初始化映射。或者，您可以在`initializeMap`函數之後，使用您偏好的樣式和顏色方案來初始化它。如需更多樣式選項，請參閱 [AWS 映射樣式和功能](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
```
在瀏覽器`index.html`中開啟 以查看正在執行的映射。
#### 新增導覽控制項
或者，您可以將導覽控制項 （縮放和旋轉） 新增至地圖。這應該在呼叫 之後完成`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
```
#### 檢閱地圖程式碼
恭喜您！您的第一個應用程式已準備好使用映射。在瀏覽器`index.html`中開啟 。請確定 `style.css` 位於與 相同的資料夾中`index.html`。
您的最終 HTML 看起來應該如下所示：
```
Amazon Location Service - Getting Started with First Map App
```
### 將位置新增至您的應用程式
在本節中，我們將設定新增位置功能到應用程式。從 GitHub 下載 JavaScript 檔案[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)。
開始之前，您的檔案應位於此資料夾結構中：
```
|---FirstApp [Folder]
|-------------- index.html [File]
|-------------- style.css [File]
|-------------- utils.js [File]
```
#### 建立 函數以建立 GeoPlaces
若要新增搜尋功能，請使用 `AuthHelper`和 初始化 `GeoPlaces`類別`AmazonLocationClient`。在 中的``標籤之前新增下列`getGeoPlaces(map)`函數`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
}
```
#### 建立 函數以將搜尋方塊新增至應用程式
在 中的``標籤之前新增下列 `addSearchBox(map, geoPlaces)``renderPopup(feature)`、 和 `createPopup(feature)`函數`index.html`，以完成搜尋功能設定。
```
/**
* 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
}
```
#### 將搜尋方塊新增至應用程式
呼叫 `getGeoPlaces(map)` 3.1 節中定義的 來建立`GeoPlaces`物件，然後呼叫 `addSearchBox(map, geoPlaces)`將搜尋方塊新增至應用程式。
```
// 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);
```
您的位置搜尋已準備好可供使用。在瀏覽器`index.html`中開啟 以查看其運作中的狀態。
#### 新增函數以在使用者按一下地圖時顯示快顯視窗
建立 函數`addMapClick(map, geoPlaces)`，以在使用者按一下地圖時顯示快顯視窗。在``標籤前面新增此函數。
```
/**
* 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
}
});
}
```
#### 呼叫 函數以新增對應點選功能
若要啟用地圖點選動作，請在包含 的行`addMapClick(map, geoPlaces)`後面呼叫 `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);
```
#### 檢閱地圖和位置應用程式
恭喜您！您的第一個應用程式已準備好使用 Maps and Places。在瀏覽器`index.html`中開啟 。確定 `style.css`和 `utils.js` 位於與 相同的資料夾中`index.html`。
您的最終 HTML 看起來應該如下所示：
```
Amazon Location Service - Getting Started with First Map App
```
### 探索更多
您已完成快速入門教學課程，並應了解 Amazon Location Service 如何用於建置應用程式。若要進一步了解 Amazon Location，您可以查看下列資源：
+ **查詢建議詳細資訊** - 考慮將 `GeoPlaces` 類別或使用類似的方法來 `ReverseGeocode`，以取得 `Suggestion` API 傳回之結果的詳細資訊。
+ **選擇適合您業務需求的 API** - 若要判斷符合您需求的最佳 Amazon Location API，請查看此資源：[選擇正確的 API](choose-an-api.md)。
+ **請參閱 Amazon Location "how-to" 指南** - 請造訪 [Amazon Location Service 開發人員指南](https://docs.aws.amazon.com/location/)以取得教學課程和其他資源。
+ **文件和產品資訊** - 如需完整的文件，請參閱 [Amazon Location Service 開發人員指南](https://docs.aws.amazon.com/location/)。若要進一步了解產品，請前往 [Amazon Location Service 產品](https://aws.amazon.com/location)頁面。
# 建立您的第一個 Geofences 和追蹤器應用程式
在本節中，您將建立一個應用程式，示範使用 Amazon Location Geofences 和追蹤器的主要功能。應用程式示範追蹤器和地理ofence 如何使用 Lambda AWS IoT和 Amazon Location 功能的組合進行互動。選擇 iOS 或 Android 平台以開始使用。
開始建置應用程式之前，請遵循中的程序[使用 Amazon Location Service 主控台進行身分驗證](set-up-auth.md)授予適當的存取權。
**Topics**
+ [建立 iOS 應用程式](ios-geofence-app.md)
+ [建立 Android 應用程式](android-geofence-app.md)
# 建立 iOS 應用程式
請依照這些程序，使用 Amazon Location Service 建置 iOS 應用程式。
從 [GitHub](https://github.com/aws-geospatial/amazon-location-samples-ios/tree/main/tracking-with-geofence-notifications) 複製專案檔案。
## 為您的應用程式建立 Amazon Location 資源
您可以在 AWS 帳戶準備就緒後產生 Amazon Location Service 資源。這些資源對於執行提供的程式碼片段至關重要。
**注意**
如果您尚未建立 AWS 帳戶，請[建立 AWS 帳戶](https://portal.aws.amazon.com/billing/signup#/start/email)。
若要開始，您需要建立 Amazon Cognito 身分集區 ID，請使用下列程序：
1. 在 AWS 主控台中，導覽至 Amazon Cognito 服務，然後從左側功能表中選取**身分集**區，然後選取**建立身分集區**。
1. 確定已核取**訪客存取**，然後按**下一步**繼續。
1. 接著建立新的 IAM 角色或使用現有的 IAM 角色。
1. 輸入身分集區名稱，並確保身分集區可以存取您將在下一個程序中建立的映射和追蹤器的 Amazon Location `(geo)` 資源。
1.
現在您需要在 Amazon Location AWS 主控台中建立地圖並建立樣式，請使用下列程序：
1. 導覽至 Amazon Location 主控台中的[映射區段](https://console.aws.amazon.com/location/maps/home)，然後選取**建立映射**以預覽可用的映射樣式。
1. 為新的映射資源命名****和**描述**。記錄您指派給映射資源的名稱，因為它稍後會在教學課程中使用。
1. 選擇映射樣式時，請考慮映射資料提供者。如需詳細資訊，請參閱 [AWS 服務條款](https://aws.amazon.com/service-terms)的第 82 節。
1. 接受 [Amazon Location 條款與條件](https://aws.amazon.com/service-terms/#:~:text=82.%20Amazon%20Location%20Service)，然後選取**建立映射**。建立地圖之後，您可以透過放大、縮小或平移任何方向來與地圖互動。
使用 Amazon Location 主控台建立追蹤器
1. 開啟 [Amazon Location Service 主控台](https://console.aws.amazon.com/location/)。
1. 在左側導覽窗格中，選擇**追蹤器**。
1. 選擇**建立追蹤器**。
1. 填寫所有必要欄位。
1. 在**位置篩選**下，選擇最符合您打算如何使用追蹤器資源的選項。如果您未設定位置篩選，則預設設定為 TimeBased。如需詳細資訊，請參閱本指南中的追蹤器，以及《Amazon Location Service Trackers API 參考》中的 PositionFiltering。
1. 選擇**建立追蹤器**以完成。
## 建立 Geofence 集合
建立地理圍欄集合時，您可以使用主控台、API 或 CLI。下列程序會逐步解說每個選項。
使用 Amazon Location 主控台建立地理圍欄集合：
1. 開啟位於 https：//https://console.aws.amazon.com/location/ 的 Amazon Location Service 主控台。
1. 在左側導覽窗格中，選擇 Geofence 集合。
1. 選擇建立地理圍欄集合。
1. 提供集合的名稱和描述。
1. 在以 CloudWatch 做為目標的 EventBridge 規則下，您可以建立選用的 EventBridge 規則，以開始對地理圍欄事件做出反應。這讓 Amazon Location 能夠將事件發佈到 Amazon CloudWatch Logs 中。
1. 選擇建立地理圍欄集合。
使用 Amazon Location APIs 建立地理圍欄集合：
從 Amazon Location Geofences APIs 使用 CreateGeofenceCollection 操作。下列範例使用 API 請求來建立名為 的地理圍欄集合`GOECOLLECTION_NAME`。
```
POST /geofencing/v0/collections
Content-type: application/json
{
"CollectionName": "GOECOLLECTION_NAME",
"Description": "Geofence collection 1 for shopping center",
"Tags": {
"Tag1" : "Value1"
}
}
```
使用 AWS CLI 命令建立地理圍欄集合：
使用 create-geofence-collection 命令。下列範例使用 AWS CLI 來建立名為 的地理圍欄集合`GOECOLLECTION_NAME`。
```
aws location \ create-geofence-collection \
--collection-name "GOECOLLECTION_NAME" \
--description "Shopping center geofence collection" \
--tags Tag1=Value1
```
## 將追蹤器連結至地理圍欄集合
若要將追蹤器連結至地理圍欄集合，您可以使用主控台、API 或 CLI。下列程序會逐步解說每個選項。
使用 Amazon Location Service 主控台將追蹤器資源連結至地理圍欄集合：
1. 開啟 Amazon Location 主控台。
1. 在左側導覽窗格中，選擇**追蹤器**。
1. 在**裝置追蹤器**下，選取目標追蹤器的名稱連結。
1. 在**連結的地理圍欄集合**下，選擇**連結地理圍欄集合**。
1. 在**連結的地理圍欄集合視窗中**，從下拉式功能表中選取地理圍欄集合。
1. 選擇 **Link (連結)**。
1. 連結追蹤器資源後，會為其指派作用中狀態。
使用 Amazon Location APIs 將追蹤器資源連結至地理圍欄集合：
從 Amazon Location Trackers APIs 使用 ``AsssociateTrackerConsumer 操作。下列範例使用 API 請求，該請求使用其 Amazon Resource Name (ARN) 將 ExampleTracker 與地理圍欄集合建立關聯。
```
POST /tracking/v0/trackers/ExampleTracker/consumers
Content-type: application/json
{
"ConsumerArn": "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME"
}
```
使用 AWS CLI 命令將追蹤器資源連結至地理圍欄集合：
使用 `associate-tracker-consumer ` 命令。下列範例使用 AWS CLI 來建立名為 的地理圍欄集合`GOECOLLECTION_NAME`。
```
aws location \
associate-tracker-consumer \
--consumer-arn "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME" \
--tracker-name "ExampleTracker"
```
## 搭配 MQTT 使用 AWS Lambda
建立 Lambda 函數。
若要在 AWS IoT Core 與 Amazon Location Service 之間建立連線，您需要 AWS Lambda 函數來處理由 EventBridge CloudWatch 事件轉送的訊息。此函數會擷取任何位置資料、將其格式化為 Amazon Location Service，並透過 Amazon Location Tracker API 提交資料。您可以透過 AWS Lambda 主控台建立此函數，也可以使用 AWS Command Line Interface (AWS CLI) 或 AWS Lambda APIs。若要建立使用主控台將位置更新發佈至 Amazon Location 的 Lambda 函數：
1. 在 https：//https://console.aws.amazon.com/lambda/ 開啟 AWS Lambda 主控台。
1. 從左側導覽中，選擇函數。
1. 選擇建立函數，並確定已選取從頭開始撰寫。
1. 填寫下列方塊：
+ 函數名稱
+ 針對**執行期**選項，選擇 Node.js 16.x。
1. 選擇建立函數。
1. 選擇程式碼索引標籤以開啟編輯器。
1. 使用下列項目覆寫 index.js 中的預留位置程式碼：
```
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. 選擇部署以儲存更新的函數。
1. 選擇 Configuration (組態) 索引標籤。
1. 在觸發條件區段中，按一下新增觸發條件。
1. 在來源欄位中選取 EventBridge (CloudWatch Events)。
1. 選取 `現有規則` 選項選項。
1. 輸入類似此 `AmazonLocationMonitor-GEOFENCECOLLECTION\$1NAME` 的規則名稱。
1. 按一下新增按鈕。
1. 這也會在許可索引標籤中連接 `Resource 型政策陳述式`
MQTT 測試用戶端
1. 開啟 https：//[https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/)。
1. 在左側導覽窗格中，選擇 MQTT 測試用戶端。
1. 您將看到標題為 **MQTT 測試用戶端**的區段，您可以在其中設定 MQTT 連線。
1. 設定必要的設定後，按一下**連線**按鈕，使用提供的參數建立與 MQTT 代理程式的連線。
1. 請記下端點值。
連線後，您可以使用 MQTT 測試用戶端界面中提供的個別輸入欄位，訂閱 MQTT 主題或將訊息發佈至主題。接下來，您將連接 MQTT 政策：
1. 在左側選單的**管理**展開**安全性**選項下，按一下**政策**。
1. 按一下**建立政策**按鈕。
1. 輸入政策名稱。
1. 在**政策文件**上，選取 **JSON** 索引標籤。
1. 複製貼上以下顯示的政策，但請務必使用 `REGION`和 更新所有元素`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. 選取要完成的**建立**按鈕。
## 設定範例應用程式程式碼
若要設定範例程式碼，您必須安裝下列工具：
+ Git
+ XCode 15.3 或更新版本
+ iOS 模擬器 16 或更新版本
使用此程序來設定範例應用程式程式碼：
1. 從此 URL 複製 git 儲存庫：https：//[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. 開啟 `AWSLocationSampleApp.xcodeproj` 專案檔案。
1. 等待套件解析程序。
1. **選用**：在專案導覽功能表上，將 重新命名`ConfigTemplate.xcconfig`為 `Config.xcconfig`並填入下列值：
```
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`
```
## 使用範例應用程式
設定範例程式碼之後，您現在可以在 iOS 模擬器或實體裝置上執行應用程式。
1. 建置並執行應用程式。
1. 應用程式會要求您提供位置和通知許可。您需要允許它們。
1. 輕觸 `Cognito Configuration` 按鈕。
1. 如果您尚未在 `Config.xcconfig` 檔案中填入值，則需要將先前在組態畫面中建立的資源值填入 欄位。
```
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. 儲存組態
1. 您現在可以查看時間、距離和準確性的篩選條件選項。根據您的需求使用它們。
1. 前往應用程式中的 `Tracking` 索引標籤，您會看到地圖和 `Start Tracking` 按鈕。
1. 如果您已在模擬器上安裝應用程式，您可能想要模擬位置變更。這可以在功能 -> 位置選單選項中完成。例如，選取功能 -> 位置 -> 高速公路。
1. 輕觸 `Start Tracking` 按鈕。您應該會在地圖上看到追蹤點。
1. 應用程式也會追蹤背景中的位置。因此，當您在背景移動應用程式時，會要求您的許可，才能在背景模式中繼續追蹤。
1. 您可以點選 `Stop Tracking` 按鈕來停止追蹤。
# 建立 Android 應用程式
請依照這些程序，使用 Amazon Location Service 建置 iOS 應用程式。
從 [GitHub](https://github.com/aws-geospatial/amazon-location-samples-android/tree/main/tracking-with-geofence-notifications) 複製專案檔案。
## 為您的應用程式建立 Amazon Location 資源
您可以在 AWS 帳戶準備就緒後產生 Amazon Location Service 資源。這些資源對於執行提供的程式碼片段至關重要。
**注意**
如果您尚未建立 AWS 帳戶，請[建立 AWS 帳戶](https://portal.aws.amazon.com/billing/signup#/start/email)。
若要開始，您需要建立 Amazon Cognito 身分集區 ID，請使用下列程序：
1. 在 AWS 主控台中，導覽至 Amazon Cognito 服務，然後從左側功能表中選取**身分集**區，然後選取**建立身分集區**。
1. 確定已核取**訪客存取**，然後按**下一步**繼續。
1. 接著建立新的 IAM 角色或使用現有的 IAM 角色。
1. 輸入身分集區名稱，並確保身分集區可以存取您將在下一個程序中建立的映射和追蹤器的 Amazon Location `(geo)`資源。
1.
現在您需要在 Amazon Location AWS 主控台中建立地圖並建立樣式，請使用下列程序：
1. 導覽至 Amazon Location 主控台中的[映射區段](https://console.aws.amazon.com/location/maps/home)，然後選取**建立映射**以預覽可用的映射樣式。
1. 為新的映射資源命名****和**描述**。記錄您指派給映射資源的名稱，因為它稍後會在教學課程中使用。
1. 選擇映射樣式時，請考慮映射資料提供者。如需詳細資訊，請參閱 [AWS 服務條款](https://aws.amazon.com/service-terms)的第 82 節。
1. 接受 [Amazon Location 條款與條件](https://aws.amazon.com/service-terms/#:~:text=82.%20Amazon%20Location%20Service)，然後選取**建立映射**。建立地圖之後，您可以透過放大、縮小或平移任何方向來與地圖互動。
使用 Amazon Location 主控台建立追蹤器
1. 開啟 [Amazon Location Service 主控台](https://console.aws.amazon.com/location/)。
1. 在左側導覽窗格中，選擇**追蹤器**。
1. 選擇**建立追蹤器**。
1. 填寫所有必要欄位。
1. 在**位置篩選**下，選擇最符合您打算如何使用追蹤器資源的選項。如果您未設定位置篩選，則預設設定為 TimeBased。如需詳細資訊，請參閱本指南中的追蹤器，以及《Amazon Location Service Trackers API 參考》中的 PositionFiltering。
1. 選擇**建立追蹤器**以完成。
## 建立 Geofence 集合
建立地理圍欄集合時，您可以使用主控台、API 或 CLI。下列程序會逐步解說每個選項。
使用 Amazon Location 主控台建立地理圍欄集合：
1. 開啟位於 https：//https://console.aws.amazon.com/location/ 的 Amazon Location Service 主控台。
1. 在左側導覽窗格中，選擇 Geofence 集合。
1. 選擇建立地理圍欄集合。
1. 提供集合的名稱和描述。
1. 在以 CloudWatch 做為目標的 EventBridge 規則下，您可以建立選用的 EventBridge 規則，以開始對地理圍欄事件做出反應。這讓 Amazon Location 能夠將事件發佈到 Amazon CloudWatch Logs 中。
1. 選擇建立地理圍欄集合。
使用 Amazon Location APIs 建立地理圍欄集合：
從 Amazon Location Geofences APIs 使用 CreateGeofenceCollection 操作。下列範例使用 API 請求來建立名為 的地理圍欄集合`GOECOLLECTION_NAME`。
```
POST /geofencing/v0/collections
Content-type: application/json
{
"CollectionName": "GOECOLLECTION_NAME",
"Description": "Geofence collection 1 for shopping center",
"Tags": {
"Tag1" : "Value1"
}
}
```
使用 AWS CLI 命令建立地理圍欄集合：
使用 create-geofence-collection 命令。下列範例使用 AWS CLI 來建立名為 的地理圍欄集合`GOECOLLECTION_NAME`。
```
aws location \ create-geofence-collection \
--collection-name "GOECOLLECTION_NAME" \
--description "Shopping center geofence collection" \
--tags Tag1=Value1
```
## 將追蹤器連結至地理圍欄集合
若要將追蹤器連結至地理圍欄集合，您可以使用主控台、API 或 CLI。下列程序會逐步解說每個選項。
使用 Amazon Location Service 主控台將追蹤器資源連結至地理圍欄集合：
1. 開啟 Amazon Location 主控台。
1. 在左側導覽窗格中，選擇**追蹤器**。
1. 在**裝置追蹤器**下，選取目標追蹤器的名稱連結。
1. 在**連結的地理圍欄集合**下，選擇**連結地理圍欄集合**。
1. 在**連結的地理圍欄集合視窗中**，從下拉式功能表中選取地理圍欄集合。
1. 選擇 **Link (連結)**。
1. 連結追蹤器資源後，會為其指派作用中狀態。
使用 Amazon Location APIs 將追蹤器資源連結至地理圍欄集合：
從 Amazon Location Trackers APIs 使用 ``AsssociateTrackerConsumer 操作。下列範例使用 API 請求，該請求使用其 Amazon Resource Name (ARN) 將 ExampleTracker 與地理圍欄集合建立關聯。
```
POST /tracking/v0/trackers/ExampleTracker/consumers
Content-type: application/json
{
"ConsumerArn": "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME"
}
```
使用 AWS CLI 命令將追蹤器資源連結至地理圍欄集合：
使用 `associate-tracker-consumer ` 命令。下列範例使用 AWS CLI 來建立名為 的地理圍欄集合`GOECOLLECTION_NAME`。
```
aws location \
associate-tracker-consumer \
--consumer-arn "arn:aws:geo:us-west-2:123456789012:geofence-collection/GOECOLLECTION_NAME" \
--tracker-name "ExampleTracker"
```
## 搭配 MQTT 使用 AWS Lambda
建立 Lambda 函數。
若要在 AWS IoT Core 與 Amazon Location Service 之間建立連線，您需要 AWS Lambda 函數來處理由 EventBridge CloudWatch 事件轉送的訊息。此函數會擷取任何位置資料、將其格式化為 Amazon Location Service，並透過 Amazon Location Tracker API 提交資料。您可以透過 AWS Lambda 主控台建立此函數，也可以使用 AWS Command Line Interface (AWS CLI) 或 AWS Lambda APIs。若要建立使用主控台將位置更新發佈至 Amazon Location 的 Lambda 函數：
1. 在 https：//https://console.aws.amazon.com/lambda/ 開啟 AWS Lambda 主控台。
1. 從左側導覽中，選擇函數。
1. 選擇建立函數，並確定已選取從頭開始撰寫。
1. 填寫下列方塊：
+ 函數名稱
+ 針對**執行期**選項，選擇 Node.js 16.x。
1. 選擇建立函數。
1. 選擇程式碼索引標籤以開啟編輯器。
1. 使用下列項目覆寫 index.js 中的預留位置程式碼：
```
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. 選擇部署以儲存更新的函數。
1. 選擇 Configuration (組態) 索引標籤。
1. 在觸發條件區段中，按一下新增觸發條件。
1. 在來源欄位中選取 EventBridge (CloudWatch Events)。
1. 選取 `現有規則` 選項選項。
1. 輸入類似此 `AmazonLocationMonitor-GEOFENCECOLLECTION\$1NAME` 的規則名稱。
1. 按一下新增按鈕。
1. 這也會在許可索引標籤中連接 `Resource 型政策陳述式`
MQTT 測試用戶端
1. 開啟 https：//[https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/)。
1. 在左側導覽窗格中，選擇 MQTT 測試用戶端。
1. 您將看到標題為 **MQTT 測試用戶端**的區段，您可以在其中設定 MQTT 連線。
1. 設定必要的設定後，按一下**連線**按鈕，使用提供的參數建立與 MQTT 代理程式的連線。
1. 記下端點值。
連線後，您可以使用 MQTT 測試用戶端界面中提供的個別輸入欄位，訂閱 MQTT 主題或將訊息發佈至主題。接下來，您將連接 MQTT 政策：
1. 在左側選單的**管理**展開**安全性**選項下，按一下**政策**。
1. 按一下**建立政策**按鈕。
1. 輸入政策名稱。
1. 在**政策文件**上，選取 **JSON** 索引標籤。
1. 複製貼上以下顯示的政策，但請務必使用 `REGION`和 更新所有元素`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. 選取要完成的**建立**按鈕。
完成先前的程序後，您現在將更新訪客角色的許可，如下所示：
1. 導覽至 Amazon Cognito 並開啟您的身分集區。然後，繼續存取使用者，然後選取訪客角色。
1. 按一下許可政策以啟用編輯。
```
{
'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. 隨著上述政策的變更，現在已針對應用程式適當設定所有必要 AWS 的資源。
## 設定範例應用程式程式碼
1. 開啟 Android Studio，然後選取**新增**，然後從**版本控制投影**。
1. 導覽至 Android Studio 左上角**的檔案**選單。
1. 從下拉式選單中選取「新增」。
1. 選擇「從版本控制專案」。
1. 輸入儲存庫 URL 在出現的對話方塊中，尋找標記為「URL」的欄位。
1. 將範例應用程式的下列 URL 複製並貼到此欄位：[https://github.com/aws-geospatial/amazon-location-samples-android.git](https://github.com/aws-geospatial/amazon-location-samples-android.git)
1. 決定您要複製儲存庫的目錄。使用預設目錄或選擇自訂位置。
1. 設定儲存庫 URL 和目錄偏好設定後，按一下「複製」按鈕。Android Studio 將繼續將儲存庫複製到您指定的位置。
1. 您現在已將應用程式複製到您的機器，並可以開始使用它。
## 使用範例應用程式
若要使用範例，請遵循下列程序：
+ **建立 `custom.properties`**：
若要設定 `custom.properties` 檔案，請依照下列步驟進行：
1. 開啟您偏好的文字編輯器或 IDE。
1. 建立新檔案。
1. 儲存檔案，並將其命名為 `custom.properties`。
1. `custom.properties` 使用以下程式碼範例更新 ，並將 `MQTT_END_POINT`、`GEOFENCE_COLLECTION_NAME`、 `POLICY_NAME`和 取代`TOPIC_TRACKER`為實際值：
```
MQTT_END_POINT=xxxxxxxxxxxxx-xxx.xxx.us-east-1.amazonaws.com
POLICY_NAME=xxxxxxxxx
GEOFENCE_COLLECTION_NAME=xxxxxxxxxxxxxxxxx
TOPIC_TRACKER=xxxxxxxxxx
```
1. 清理和重建專案。之後，您可以執行專案。
+ **登入**：
若要登入應用程式，請遵循下列步驟：
1. 按下**登入**按鈕。
1. 提供**身分集區 ID**、**追蹤器名稱**和**映射名稱**。
1. 再次按下**登入**以完成。
+ **管理篩選條件**：
開啟組態畫面，並執行下列動作：
1. 使用切換 UI 開啟/關閉篩選條件。
1. 視需要更新時間和距離篩選條件。
+ **追蹤操作：**
開啟追蹤畫面並執行下列動作：
+ 您可以按下個別按鈕，在前景、背景或省電模式下開始和停止追蹤。