本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 Amazon Location Service SDKs 和架構
<a name="dev-sdks"></a>

AWS 為多種程式設計語言提供軟體開發套件 (SDKs)，可讓您輕鬆地將 Amazon Location Service 整合到您的應用程式。此頁面概述可用的 SDKs、其安裝程序和程式碼範例，協助您在偏好的開發環境中開始使用 Amazon Location Service。

有數種工具可協助您使用 Amazon Location Service。
+ **AWS SDKs** – AWS 軟體開發套件 (SDKs) 提供多種熱門的程式設計語言，提供 API、程式碼範例和文件，讓您更輕鬆地以您偏好的語言建置應用程式。 AWS SDKs 包含核心 Amazon Location APIs和功能，包括對 Maps、Places、Routes、Geofencing 和 Trackers 的存取。若要進一步了解適用於不同應用程式和語言的 SDKs Amazon Location Service 開發套件，請參閱 [依語言分類SDKs](dev-by-language.md)。
+ **MapLibre** – Amazon Location Service 建議使用 [MapLibre](https://github.com/maplibre/maplibre-gl-js) 轉譯引擎轉譯地圖。MapLibre 是一種在 Web 或行動應用程式中顯示地圖的引擎。MapLibre 也有外掛程式模型，並支援使用者界面以某些語言和平台搜尋和路由。若要進一步了解如何使用 MapLibre 及其提供的功能，請參閱 [搭配 Amazon Location 使用 MapLibre 工具和相關程式庫](dev-maplibre.md)。
+ **Amazon Location SDKs** Amazon Location SDKs 是一組開放原始碼程式庫，可讓您更輕鬆地使用 Amazon Location Service 開發應用程式。這些程式庫提供的功能可支援行動和 Web 應用程式的身分驗證、行動應用程式的位置追蹤、Amazon Location 資料類型和 [GeoJSON](https://geojson.org/) 之間的轉換，以及 AWS SDK v3 的 Amazon Location 用戶端託管套件。若要進一步了解 Amazon Location SDKs，請參閱 [依語言分類SDKs](dev-by-language.md)。
+ **Amazon Location Migration SDK** – Amazon Location Migration SDK 提供橋接器，可讓您將現有應用程式從 Google Maps 遷移至 Amazon Location。如果 Amazon Location 支援使用的功能，遷移 SDK 可為使用適用於 JavaScript 的 Google Maps SDK 建置的應用程式提供使用 Amazon Location Service 的選項，而不需要重寫任何應用程式或商業邏輯。Migration SDK 會將所有 API 呼叫重新導向至 Amazon Location，而不是 Google Map。若要開始使用，請參閱 GitHub 上的 [Amazon Location Migration SDK](https://github.com/aws-geospatial/amazon-location-migration)。

# 開發人員教學課程
<a name="sdk-how-to"></a>

使用本節來了解如何使用 Amazon Location Service SDK 的各個層面。

**Topics**
+ [如何使用身分驗證協助程式](how-to-auth-helper.md)
+ [使用 Amazon Location MapLibre Geocoder GL 外掛程式](dev-maplibre-geocoder.md)
+ [如何使用追蹤 SDKs](dev-tracking-sdk.md)
+ [搭配 Amazon Location 使用 MapLibre 工具和相關程式庫](dev-maplibre.md)

# 如何使用身分驗證協助程式
<a name="how-to-auth-helper"></a>

本節提供有關身分驗證協助程式的其他資訊。

## Web
<a name="loc-sdk-auth-web"></a>

Amazon Location JavaScript 身分驗證公用程式可協助從 JavaScript 應用程式進行 Amazon Location Service API 呼叫時進行身分驗證。這些公用程式特別支援使用 API 金鑰或 Amazon Cognito 進行身分驗證。

**安裝**
+ 使用 NPM 安裝此程式庫：

  ```
  npm install @aws/amazon-location-utilities-auth-helper
  ```
+ 若要直接在瀏覽器中使用它，請在 HTML 檔案中包含下列項目：

  ```
  <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-auth-helper@1"></script>
  ```

### Usage
<a name="loc-sdk-auth-usage"></a>

若要使用身分驗證協助程式，請匯入程式庫並呼叫必要的公用程式函數。此程式庫支援驗證來自 Amazon Location Service SDKs請求，包括 [Maps](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-maps/)、[Places](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-places/) 和 [Routes](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-routes/) 獨立SDKs，以及使用 [MapLibre GL JS ](https://github.com/maplibre/maplibre-gl-js)轉譯地圖。

**使用 模組**

此範例示範如何使用獨立的 Places SDK，讓請求透過 API 金鑰進行身分驗證：

```
npm install @aws-sdk/client-geo-places

import { GeoPlacesClient, GeocodeCommand } from "@aws-sdk/client-geo-places";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new GeoPlacesClient(authHelper.getClientConfig());

const input = { ... };
const command = new GeocodeCommand(input);
const response = await client.send(command);
```

此範例示範如何使用獨立的 Routes SDK，以 API 金鑰對請求進行身分驗證：

```
npm install @aws-sdk/geo-routes-client

import { GeoRoutesClient, CalculateRoutesCommand } from "@aws-sdk/geo-routes-client";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new GeoRoutesClient(authHelper.getClientConfig());

const input = { ... };
const command = new CalculateRoutesCommand(input);
const response = await client.send(command);
```

此範例使用 Location SDK 搭配 API 金鑰身分驗證：

```
npm install @aws-sdk/client-location

import { LocationClient, ListGeofencesCommand } from "@aws-sdk/client-location";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new LocationClient(authHelper.getClientConfig());

const input = { ... };
const command = new ListGeofencesCommand(input);
const response = await client.send(command);
```

**使用瀏覽器**

直接在瀏覽器環境中使用時，公用程式函數可在 amazonLocationAuthHelper 全域物件下存取。

此範例示範使用 API 金鑰進行身分驗證的 Amazon Location Client 請求：

```
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>

const authHelper = amazonLocationClient.withAPIKey("<API Key>", "<Region>");
const client = new amazonLocationClient.GeoRoutesClient(authHelper.getClientConfig());
const input = { ... };
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

此範例示範使用以 API 金鑰驗證的 MapLibre GL JS 轉譯映射：

```
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.x"></script>

const apiKey = "<API Key>";
const region = "<Region>";
const styleName = "Standard";

const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor?key=${apiKey}`,
});
```

此範例示範如何使用 Amazon Cognito 使用 MapLibre GL JS 轉譯映射：

```
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.x"></script>
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-auth-helper@1"></script>

const identityPoolId = "<Identity Pool ID>";
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId);

const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor`,
  ...authHelper.getMapAuthenticationOptions(),
});
```

**使用已驗證身分的替代用量**

您可以修改 withIdentityPoolId 函數，以包含已驗證身分的自訂參數：

```
const userPoolId = "<User Pool ID>";

const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId, {
  logins: {
    [`cognito-idp.${region}.amazonaws.com/${userPoolId}`]: "cognito-id-token"
  }
});
```

## iOS
<a name="loc-sdk-auth-ios"></a>

適用於 iOS 的 Amazon Location Service Mobile Authentication SDK 可協助驗證來自 iOS 應用程式的 Amazon Location Service APIs請求。它特別支援透過 API 金鑰或 Amazon Cognito 進行身分驗證。

**安裝**
+ 開啟 Xcode 並前往**檔案 > 新增套件相依性**。
+ 在搜尋列中輸入套件 URL ([https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios/](https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios/))，然後按 Enter 鍵。
+ 選取「amazon-location-mobile-auth-sdk-ios」套件，然後按一下**新增套件**。
+ 選擇「AmazonLocationiOSAuthSDK」套件產品，然後按一下**新增套件**。

### Usage
<a name="loc-sdk-auth-usage"></a>

安裝程式庫之後，請使用 `AuthHelper`類別來設定 API 金鑰或 Amazon Cognito 的用戶端設定。

**API 金鑰**

以下是使用獨立 Places SDK 搭配 API 金鑰身分驗證的範例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoPlaces

func geoPlacesExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: GeoPlacesClient = GeoPlacesClient(config: authHelper.getGeoPlacesClientConfig())

    let input = AWSGeoPlaces.SearchTextInput(
        biasPosition: [-97.7457518, 30.268193],
        queryText: "tacos"
    )

    let output = try await client.searchText(input: input)
}
```

以下是使用具有 API 金鑰身分驗證的獨立 Routes SDK 的範例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoRoutes

func geoRoutesExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: GeoRoutesClient = GeoRoutesClient(config: authHelper.getGeoRoutesClientConfig())

    let input = AWSGeoRoutes.CalculateRoutesInput(
        destination: [-123.1651031, 49.2577281],
        origin: [-97.7457518, 30.268193]
    )

    let output = try await client.calculateRoutes(input: input)
}
```

以下是使用 Location SDK 搭配 API 金鑰身分驗證的範例：

```
import AmazonLocationiOSAuthSDK
import AWSLocation

func locationExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: LocationClient = LocationClient(config: authHelper.getLocationClientConfig())

    let input = AWSLocation.ListGeofencesInput(
        collectionName: "<Collection name>"
    )

    let output = try await client.listGeofences(input: input)
}
```

以下是搭配 Amazon Cognito 使用獨立 Places SDK 的範例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoPlaces

func geoPlacesExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: GeoPlacesClient = GeoPlacesClient(config: authHelper.getGeoPlacesClientConfig())

    let input = AWSGeoPlaces.SearchTextInput(
        biasPosition: [-97.7457518, 30.268193],
        queryText: "tacos"
    )

    let output = try await client.searchText(input: input)
}
```

以下是搭配 Amazon Cognito 使用獨立 Routes SDK 的範例：

```
import AmazonLocationiOSAuthSDK
import AWSGeoRoutes

func geoRoutesExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: GeoRoutesClient = GeoRoutesClient(config: authHelper.getGeoRoutesClientConfig())

    let input = AWSGeoRoutes.CalculateRoutesInput(
        destination: [-123.1651031, 49.2577281],
        origin: [-97.7457518, 30.268193]
    )

    let output = try await client.calculateRoutes(input: input)
}
```

以下是搭配 Amazon Cognito 使用 Location SDK 的範例：

```
import AmazonLocationiOSAuthSDK
import AWSLocation

func locationExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: LocationClient = LocationClient(config: authHelper.getLocationClientConfig())

    let input = AWSLocation.ListGeofencesInput(
        collectionName: "<Collection name>"
    )

    let output = try await client.listGeofences(input: input)
}
```

## Android
<a name="loc-sdk-auth-android"></a>

適用於 Android 的 Amazon Location Service Mobile Authentication SDK 可協助您驗證來自 Android 應用程式的 Amazon Location Service APIs 請求，特別是支援使用 Amazon Cognito 進行身分驗證。

**安裝**
+ 此身分驗證 SDK 可與整體 AWS Kotlin SDK 搭配使用。這兩個 SDKs都會發佈至 Maven Central。檢查 Maven Central 上[身分驗證開發套件](https://mvnrepository.com/artifact/software.amazon.location/auth)的最新版本。
+ 將下列幾行新增至 Android Studio 中 `build.gradle` 檔案的相依性區段：

  ```
  implementation("software.amazon.location:auth:1.1.0")
  implementation("org.maplibre.gl:android-sdk:11.5.2")
  implementation("com.squareup.okhttp3:okhttp:4.12.0")
  ```
+ 對於獨立 Maps、Places 和 Routes SDKs，新增下列行：

  ```
  implementation("aws.sdk.kotlin:geomaps:1.3.65")
  implementation("aws.sdk.kotlin:geoplaces:1.3.65")
  implementation("aws.sdk.kotlin:georoutes:1.3.65")
  ```
+ 對於包含地理圍欄和追蹤的合併位置開發套件，新增以下行：

  ```
  implementation("aws.sdk.kotlin:location:1.3.65")
  ```

### Usage
<a name="loc-sdk-auth-usage"></a>

在程式碼中匯入下列類別：

```
// For the standalone Maps, Places, and Routes SDKs
import aws.sdk.kotlin.services.geomaps.GeoMapsClient
import aws.sdk.kotlin.services.geoplaces.GeoPlacesClient
import aws.sdk.kotlin.services.georoutes.GeoRoutesClient

// For the consolidated Location SDK
import aws.sdk.kotlin.services.location.LocationClient

import software.amazon.location.auth.AuthHelper
import software.amazon.location.auth.LocationCredentialsProvider
import software.amazon.location.auth.AwsSignerInterceptor
import org.maplibre.android.module.http.HttpRequestUtil
import okhttp3.OkHttpClient
```

您可以建立 `AuthHelper` 並搭配 AWS Kotlin SDK 使用：

**範例：具有身分集區 ID 的登入資料提供者**

```
private suspend fun exampleCognitoLogin() {
    val authHelper = AuthHelper.withCognitoIdentityPool("MY-COGNITO-IDENTITY-POOL-ID", applicationContext)
    
    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

**範例：具有自訂登入資料提供者的登入資料提供者**

```
private suspend fun exampleCustomCredentialLogin() {
    var authHelper = AuthHelper.withCredentialsProvider(MY-CUSTOM-CREDENTIAL-PROVIDER, "MY-AWS-REGION", applicationContext)

    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

**範例：具有 API 金鑰的登入資料提供者**

```
private suspend fun exampleApiKeyLogin() {
    var authHelper = AuthHelper.withApiKey("MY-API-KEY", "MY-AWS-REGION", applicationContext)

    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

您可以使用 `LocationCredentialsProvider` 載入 MapLibre 映射。請見此處範例：

```
HttpRequestUtil.setOkHttpClient(
    OkHttpClient.Builder()
        .addInterceptor(
            AwsSignerInterceptor(
                "geo",
                "MY-AWS-REGION",
                locationCredentialsProvider,
                applicationContext
            )
        )
        .build()
)
```

使用建立的用戶端來呼叫 Amazon Location Service。以下是搜尋接近指定經緯度的位置的範例：

```
val suggestRequest = SuggestRequest {
       biasPosition = listOf(-97.718833, 30.405423)
       maxResults = MAX_RESULT
       language = "PREFERRED-LANGUAGE"
   }
val nearbyPlaces = geoPlacesClient.suggest(suggestRequest)
```

# 使用 Amazon Location MapLibre Geocoder GL 外掛程式
<a name="dev-maplibre-geocoder"></a>

Amazon Location MapLibre 地理編碼器外掛程式旨在讓您在使用 [maplibre-gl-geocoder](https://github.com/maplibre/maplibre-gl-geocoder) 程式庫進行映射轉譯和地理編碼時，更輕鬆地將 Amazon Location 功能整合到您的 JavaScript 應用程式。

## 安裝
<a name="geocoder-installation"></a>

從 NPM 安裝 Amazon Location MapLibre 地理編碼器外掛程式，以搭配 模組使用。輸入此命令：

```
npm install @aws/amazon-location-for-maplibre-gl-geocoder
```

您也可以使用指令碼，直接在瀏覽器中匯入 HTML 和 CSS 檔案以供使用：

```
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2"></script>
<link
  href="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2/dist/amazon-location-for-mlg-styles.css"
  rel="stylesheet"
/>
```

## 使用模組 - 獨立 GeoPlaces SDK
<a name="geocoder-module"></a>

此範例使用適用於 [AWS JavaScript V3 的 SDK](https://github.com/aws/aws-sdk-js-v3) 來取得 GeoPlacesClient，以提供給程式庫和 [AuthHelper](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js) 來驗證 GeoPlacesClient。它會啟用地理編碼器的所有 APIs。

```
// Import MapLibre GL JS
import maplibregl from "maplibre-gl";
// Import from the AWS JavaScript SDK V3
import { GeoPlacesClient } from "@aws-sdk/client-geo-places";
// Import the utility functions
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";
// Import the AmazonLocationMaplibreGeocoder
import {
  buildAmazonLocationMaplibreGeocoder,
  AmazonLocationMaplibreGeocoder,
} from "@aws/amazon-location-for-maplibre-gl-geocoder";

const apiKey = "<API Key>";
const mapName = "Standard";
const region = "<Region>"; // region containing Amazon Location API Key

// Create an authentication helper instance using an API key and region
const authHelper = await withAPIKey(apiKey, region);

const client = new GeoPlacesClient(authHelper.getClientConfig());

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${apiKey}`,
});

// Gets an instance of the AmazonLocationMaplibreGeocoder Object.
const amazonLocationMaplibreGeocoder = buildAmazonLocationMaplibreGeocoder(client, { enableAll: true });

// Now we can add the Geocoder to the map.
map.addControl(amazonLocationMaplibreGeocoder.getPlacesGeocoder());
```

## 使用瀏覽器 - 獨立 GeoPlaces SDK
<a name="geocoder-browser"></a>

此範例使用 Amazon Location 用戶端提出使用 API 金鑰進行身分驗證的請求。

**注意**  
其中一些範例使用 Amazon Location GeoPlacesClient。此用戶端以適用於 [AWS JavaScript V3 的 開發套件](https://github.com/aws/aws-sdk-js-v3)為基礎，允許透過 HTML 檔案中參考的指令碼呼叫 Amazon Location。

在 HTML 檔案中包含下列項目：

```
<!-- Import the Amazon Location For Maplibre Geocoder -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2"></script>
<link
  href="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2/dist/amazon-location-for-mlg-styles.css"
  rel="stylesheet"
/>
<!-- Import the Amazon GeoPlacesClient -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
```

在 JavaScript 檔案中包含下列項目：

```
const apiKey = "<API Key>";
const mapStyle = "Standard";
const region = "<Region>"; // region containing Amazon Location API key

// Create an authentication helper instance using an API key and region
const authHelper = await amazonLocationClient.withAPIKey(apiKey, region);

const client = new amazonLocationClient.GeoPlacesClient(authHelper.getClientConfig());

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${apiKey}`,
});

// Initialize the AmazonLocationMaplibreGeocoder object
const amazonLocationMaplibreGeocoderObject = amazonLocationMaplibreGeocoder.buildAmazonLocationMaplibreGeocoder(
  client,
  { enableAll: true },
);

// Use the AmazonLocationWithMaplibreGeocoder object to add a geocoder to the map.
map.addControl(amazonLocationMaplibreGeocoderObject.getPlacesGeocoder());
```

## 函數
<a name="geocoder-functions"></a>

以下列出 Amazon Location MapLibre 地理編碼器外掛程式中使用的函數：
+ `buildAmazonLocationMaplibreGeocoder`

  此類別會建立 的執行個體`AmazonLocationMaplibreGeocder`，這是其他所有其他呼叫的進入點。

  使用獨立 `GeoPlacesClient` API 呼叫 （用戶端是 的執行個體`GeoPlacesClient`)：

  ```
  const amazonLocationMaplibreGeocoder = buildAmazonLocationMaplibreGeocoder(client, { enableAll: true });
  ```

  使用合併 `LocationClient` API 呼叫 （用戶端是 的執行個體`LocationClient`)：

  ```
  const amazonLocationMaplibreGeocoder = buildAmazonLocationMaplibreGeocoder(client, {
    enableAll: true,
    placesIndex: placeIndex,
  });
  ```
+ `getPlacesGeocoder`

  傳回可直接新增至映射的ready-to-use型 IControl 物件。

  ```
  const geocoder = getPlacesGeocoder();
  
  // Initialize map see: <insert link to initializing a map instance here>
  let map = await initializeMap();
  
  // Add the geocoder to the map.
  map.addControl(geocoder);
  ```

# 如何使用追蹤 SDKs
<a name="dev-tracking-sdk"></a>

本主題提供如何使用追蹤 SDKs的相關資訊。

# iOS
<a name="loc-mobile-tracking-ios"></a>

Amazon Location 行動追蹤 SDK 提供公用程式，可協助輕鬆驗證、擷取裝置位置，以及傳送位置更新至 Amazon Location Trackers。開發套件支援以可設定的更新間隔對位置更新進行本機篩選。這可降低資料成本，並最佳化 iOS 應用程式的間歇性連線。

iOS 追蹤 SDK 可在 GitHub 上取得：適用於 [iOS 的 Amazon Location Mobile Tracking SDK](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios)。

本節涵蓋 Amazon Location 行動追蹤 iOS 開發套件的下列主題：

**Topics**
+ [安裝](#loc-mobile-tracking-install-ios)
+ [Usage](#loc-mobile-tracking-usage-ios)
+ [篩選條件](#loc-mobile-tracking-ios-filters)
+ [iOS Mobile SDK 追蹤函數](#loc-mobile-tracking-functions)
+ [範例](#loc-mobile-tracking-example-ios)

## 安裝
<a name="loc-mobile-tracking-install-ios"></a>

使用下列程序安裝適用於 iOS 的行動追蹤 SDK：

1. 在您的 Xcode 專案中，前往**檔案**，然後選取**新增套件相依性**。

1. 在搜尋列中輸入下列 URL：https：//[https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/)。

1. 選取`amazon-location-mobile-tracking-sdk-ios`套件，然後按一下**新增套件**。

1. 選取`AmazonLocationiOSTrackingSDK`套件產品，然後按一下**新增套件**。

## Usage
<a name="loc-mobile-tracking-usage-ios"></a>

下列程序說明如何使用 Amazon Cognito 的登入資料建立身分驗證協助程式。

1. 安裝程式庫之後，您需要將一個或兩個描述新增至 `info.plist` 檔案：

   ```
   Privacy - Location When In Use Usage Description
   Privacy - Location Always and When In Use Usage Description
   ```

1. 接著，在您的 類別中匯入 AuthHelper：

   ```
   import AmazonLocationiOSAuthSDKimport AmazonLocationiOSTrackingSDK
   ```

1. 然後，您將使用 Amazon Cognito 的登入資料建立身分驗證協助程式，以建立`AuthHelper`物件並搭配 AWS SDK 使用。

   ```
   let authHelper = AuthHelper()
   let locationCredentialsProvider = authHelper.authenticateWithCognitoUserPool(identityPoolId: "My-Cognito-Identity-Pool-Id", region: "My-region") //example: us-east-1
   let locationTracker = LocationTracker(provider: locationCredentialsProvider, trackerName: "My-tracker-name")
   
   // Optionally you can set ClientConfig with your own values in either initialize or in a separate function
   // let trackerConfig = LocationTrackerConfig(locationFilters: [TimeLocationFilter(), DistanceLocationFilter()],
   
        trackingDistanceInterval: 30,
        trackingTimeInterval: 30,
        logLevel: .debug)
   
   // locationTracker = LocationTracker(provider: credentialsProvider, trackerName: "My-tracker-name",config: trackerConfig)
   // locationTracker.setConfig(config: trackerConfig)
   ```

## 篩選條件
<a name="loc-mobile-tracking-ios-filters"></a>

Amazon Location 行動追蹤 iOS SDK 有三個內建的位置篩選條件。
+ `TimeLocationFilter`：根據定義的時間間隔篩選要上傳的目前位置。
+ `DistanceLocationFilter`：根據指定的距離閾值篩選位置更新。
+ `AccuracyLocationFilter`：透過比較自上次更新以來移動的距離與目前位置的準確性來篩選位置更新。

此範例`LocationTracker`會在建立時於 中新增篩選條件：

```
val config = LocationTrackerConfig(
    trackerName = "MY-TRACKER-NAME",
    logLevel = TrackingSdkLogLevel.DEBUG,
    accuracy = Priority.PRIORITY_HIGH_ACCURACY,
    latency = 1000,
    frequency = 5000,
    waitForAccurateLocation = false,
    minUpdateIntervalMillis = 5000,
    locationFilters = mutableListOf(TimeLocationFilter(), DistanceLocationFilter(), AccuracyLocationFilter())
)

locationTracker = LocationTracker(
    applicationContext,
    locationCredentialsProvider,
    config,
)
```

此範例使用 在執行時間啟用和停用篩選條件`LocationTracker`：

```
// To enable the filter
locationTracker?.enableFilter(TimeLocationFilter())

// To disable the filter
locationTracker?.disableFilter(TimeLocationFilter())
```

## iOS Mobile SDK 追蹤函數
<a name="loc-mobile-tracking-functions"></a>

適用於 iOS 的 Amazon Location 行動追蹤 SDK 包含下列函數：
+ **類別**： `LocationTracker`

  `init(provider: LocationCredentialsProvider, trackerName: String, config: LocationTrackerConfig? = nil)`

  這是用來建立`LocationTracker`物件的初始化器函數。它需要 `LocationCredentialsProvider` 的執行個體，`trackerName`以及選擇性的 執行個體`LocationTrackingConfig`。如果未提供組態，則會使用預設值初始化組態。
+ **類別**： `LocationTracker`

  `setTrackerConfig(config: LocationTrackerConfig)`

  這會將 Tracker 的組態設定為在位置追蹤器初始化後的任何時間點生效。
+ **類別**： `LocationTracker`

  `getTrackerConfig()`

  這會取得要在應用程式中使用或修改的位置追蹤組態。

  傳回： `LocationTrackerConfig`
+ **類別**： `LocationTracker`

  `getDeviceId()`

  取得位置追蹤器產生的裝置 ID。

  傳回： `String?`
+ **類別**： `LocationTracker`

  `startTracking()`

  開始存取使用者位置並將其傳送至 AWS 追蹤器的程序。
+ **類別**： `LocationTracker`

  `resumeTracking()`

  繼續存取使用者位置並將其傳送至 AWS 追蹤器的程序。
+ **類別**： `LocationTracker`

  `stopTracking()`

  停止追蹤使用者位置的程序。
+ **類別**： `LocationTracker`

  `startBackgroundTracking(mode: BackgroundTrackingMode)`

  開始存取使用者位置的程序，並在應用程式位於背景時將其傳送至 AWS 追蹤器。 `BackgroundTrackingMode`具有下列選項：
  + `Active:` 此選項不會自動暫停位置更新。
  + `BatterySaving:` 此選項會自動暫停位置更新。
  + `None:` 此選項整體會停用背景位置更新。
+ **類別**： `LocationTracker`

  `resumeBackgroundTracking(mode: BackgroundTrackingMode)`

  在應用程式位於背景時，繼續存取使用者位置並將其傳送至 AWS 追蹤器的程序。
+ **類別**： `LocationTracker`

  `stopBackgroundTracking()`

  當應用程式在背景時，停止存取使用者位置並將其傳送至 AWS 追蹤器的程序。
+ **類別**： `LocationTracker`

  `getTrackerDeviceLocation(nextToken: String?, startTime: Date? = nil, endTime: Date? = nil, completion: @escaping (Result<GetLocationResponse, Error>)`

  擷取使用者裝置的上傳追蹤位置，介於開始和結束日期和時間之間。

  傳回： `Void`
+ **類別**： `LocationTrackerConfig`

  `init()`

  這會使用預設值初始化 LocationTrackerConfig。
+ **類別**： `LocationTrackerConfig`

  `init(locationFilters: [LocationFilter]? = nil, trackingDistanceInterval: Double? = nil, trackingTimeInterval: Double? = nil, trackingAccuracyLevel: Double? = nil, uploadFrequency: Double? = nil, desiredAccuracy: CLLocationAccuracy? = nil, activityType: CLActivityType? = nil, logLevel: LogLevel? = nil)`

  這會`LocationTrackerConfig`使用使用者定義的參數值初始化 。如果未提供參數值，則會將其設定為預設值。
+ **類別**： `LocationFilter`

  `shouldUpload(currentLocation: LocationEntity, previousLocation: LocationEntity?, trackerConfig: LocationTrackerConfig)`

  `LocationFilter` 是使用者可以為其自訂篩選條件實作實作的通訊協定。使用者需要實作 `shouldUpload` 函數來比較先前和目前的位置，如果應該上傳目前的位置，則傳回 。

## 範例
<a name="loc-mobile-tracking-example-ios"></a>

本節詳細說明使用適用於 iOS 的 Amazon Location Mobile Tracking SDK 的範例。

**注意**  
確定已在 `info.plist` 檔案中設定必要的許可。這些是 [Usage](#loc-mobile-tracking-usage-ios)區段中列出的相同許可。

下列範例示範追蹤裝置位置和擷取追蹤位置的功能：

```
Privacy - Location When In Use Usage Description
Privacy - Location Always and When In Use Usage Description
```

開始追蹤位置：

```
do {
    try locationTracker.startTracking()
    } 
catch TrackingLocationError.permissionDenied {
        // Handle permissionDenied by showing the alert message or opening the app settings
        }
```

繼續追蹤位置：

```
do { 
    try locationTracker.resumeTracking()
    } 
catch TrackingLocationError.permissionDenied {
    // Handle permissionDenied by showing the alert message or opening the app settings
    }
```

停止追蹤位置：

```
locationTracker.stopTracking()
```

開始背景追蹤：

```
do {
    locationTracker.startBackgroundTracking(mode: .Active) // .Active, .BatterySaving, .None
    } 
catch TrackingLocationError.permissionDenied {
   // Handle permissionDenied by showing the alert message or opening the app settings
   }
```

繼續背景追蹤：

```
do {
    locationTracker.resumeBackgroundTracking(mode: .Active)
    } 
catch TrackingLocationError.permissionDenied {
    // Handle permissionDenied by showing the alert message or opening the app settings
    }
```

若要停止背景追蹤：

```
locationTracker.stopBackgroundTracking()
```

從追蹤器擷取裝置的追蹤位置：

```
func getTrackingPoints(nextToken: String? = nil) {
let startTime: Date = Date().addingTimeInterval(-86400) // Yesterday's day date and time
let endTime: Date = Date() 
locationTracker.getTrackerDeviceLocation(nextToken: nextToken, startTime: startTime, endTime: endTime, completion: { [weak self] result in
    switch result {
    case .success(let response):
        
        let positions = response.devicePositions
        // You can draw positions on map or use it further as per your requirement

        // If nextToken is available, recursively call to get more data
        if let nextToken = response.nextToken {
            self?.getTrackingPoints(nextToken: nextToken)
        }
    case .failure(let error):
        print(error)
    }
})
}
```

# Android Mobile 追蹤 SDK
<a name="loc-mobile-tracking-android"></a>

Amazon Location 行動追蹤 SDK 提供公用程式，可協助輕鬆驗證、擷取裝置位置，以及傳送位置更新至 Amazon Location Trackers。開發套件支援以可設定的更新間隔對位置更新進行本機篩選。這可降低資料成本，並最佳化 Android 應用程式的間歇性連線。

Android 追蹤 SDK 可在 GitHub 上取得：適用於 [Android 的 Amazon Location Mobile Tracking SDK](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-android)。此外，[AWS Maven 儲存庫](https://central.sonatype.com/artifact/software.amazon.location/tracking)提供行動身分驗證 SDK 和 AWS SDK。Android 追蹤 SDK 旨在與一般 AWS SDK 搭配使用。

本節涵蓋 Amazon Location 行動追蹤 Android SDK 的下列主題：

**Topics**
+ [安裝](#loc-mobile-tracking-install-android)
+ [Usage](#loc-mobile-tracking-usage-android)
+ [篩選條件](#loc-mobile-tracking-android-filters)
+ [Android Mobile SDK 追蹤函數](#loc-mobile-tracking-functions)
+ [範例](#loc-mobile-tracking-example-android)

## 安裝
<a name="loc-mobile-tracking-install-android"></a>

若要安裝 SDK，請在 Android Studio 中將下列幾行新增至 build.gradle 檔案的相依性區段：

```
implementation("software.amazon.location:tracking:0.0.1")
implementation("software.amazon.location:auth:0.0.1")
implementation("com.amazonaws:aws-android-sdk-location:2.72.0")
```

## Usage
<a name="loc-mobile-tracking-usage-android"></a>

此程序說明如何使用 開發套件來驗證和建立 `LocationTracker` 物件：

**注意**  
此程序假設您已匯入 [安裝](#loc-mobile-tracking-install-android)章節所述的程式庫。

1. 在程式碼中匯入下列類別：

   ```
   import software.amazon.location.tracking.LocationTracker
   import software.amazon.location.tracking.config.LocationTrackerConfig
   import software.amazon.location.tracking.util.TrackingSdkLogLevel
   import com.amazonaws.services.geo.AmazonLocationClient
   import software.amazon.location.auth.AuthHelper
   import software.amazon.location.auth.LocationCredentialsProvider
   ```

1. 接著建立 `AuthHelper`，因為建立`LocationTracker`物件需要 `LocationCredentialsProvider` 參數：

   ```
   // Create an authentication helper using credentials from Amazon Cognito
   val authHelper = AuthHelper(applicationContext)
   val locationCredentialsProvider : LocationCredentialsProvider = authHelper.authenticateWithCognitoIdentityPool("My-Cognito-Identity-Pool-Id")
   ```

1. 現在，使用 `LocationCredentialsProvider`和 `LocationTrackerConfig` 來建立`LocationTracker`物件：

   ```
   val config = LocationTrackerConfig(
       trackerName = "MY-TRACKER-NAME",
       logLevel = TrackingSdkLogLevel.DEBUG,
       accuracy = Priority.PRIORITY_HIGH_ACCURACY,
       latency = 1000,
       frequency = 5000,
       waitForAccurateLocation = false,
       minUpdateIntervalMillis = 5000,
   )
   locationTracker = LocationTracker(
       applicationContext,
       locationCredentialsProvider,
       config,
   )
   ```

## 篩選條件
<a name="loc-mobile-tracking-android-filters"></a>

Amazon Location 行動追蹤 Android SDK 有三個內建的位置篩選條件。
+ `TimeLocationFilter`：根據定義的時間間隔篩選要上傳的目前位置。
+ `DistanceLocationFilter`：根據指定的距離閾值篩選位置更新。
+ `AccuracyLocationFilter`：透過比較自上次更新以來移動的距離與目前位置的準確性來篩選位置更新。

此範例`LocationTracker`會在建立時於 中新增篩選條件：

```
val config = LocationTrackerConfig(
    trackerName = "MY-TRACKER-NAME",
    logLevel = TrackingSdkLogLevel.DEBUG,
    accuracy = Priority.PRIORITY_HIGH_ACCURACY,
    latency = 1000,
    frequency = 5000,
    waitForAccurateLocation = false,
    minUpdateIntervalMillis = 5000,
    locationFilters = mutableListOf(TimeLocationFilter(), DistanceLocationFilter(), AccuracyLocationFilter())
)
locationTracker = LocationTracker(
    applicationContext,
    locationCredentialsProvider,
    config,
)
```

此範例使用 在執行時間啟用和停用篩選條件`LocationTracker`：

```
// To enable the filter
locationTracker?.enableFilter(TimeLocationFilter())

// To disable the filter
locationTracker?.disableFilter(TimeLocationFilter())
```

## Android Mobile SDK 追蹤函數
<a name="loc-mobile-tracking-functions"></a>

適用於 Android 的 Amazon Location 行動追蹤 SDK 包含下列函數：
+ **類別**： `LocationTracker`

  `constructor(context: Context,locationCredentialsProvider: LocationCredentialsProvider,trackerName: String)`, 或 `constructor(context: Context,locationCredentialsProvider: LocationCredentialsProvider,clientConfig: LocationTrackerConfig)`

  這是用來建立`LocationTracker`物件的初始化器函數。它需要 `LocationCredentialsProvider` 的執行個體，`trackerName`以及選擇性的 執行個體`LocationTrackingConfig`。如果未提供組態，則會使用預設值初始化組態。
+ **類別**： `LocationTracker`

  `start(locationTrackingCallback: LocationTrackingCallback)`

  開始存取使用者位置並將其傳送至 Amazon Location 追蹤器的程序。
+ **類別**： `LocationTracker`

  `isTrackingInForeground()`

  檢查位置追蹤目前是否正在進行中。
+ **類別**： `LocationTracker`

  `stop()`

  停止追蹤使用者位置的程序。
+ **類別**： `LocationTracker`

  `startTracking()`

  開始存取使用者位置並將其傳送至 AWS 追蹤器的程序。
+ **類別**： `LocationTracker`

  `startBackground(mode: BackgroundTrackingMode, serviceCallback: ServiceCallback)`

  開始存取使用者位置的程序，並在應用程式位於背景時將其傳送至 AWS 追蹤器。 `BackgroundTrackingMode`具有下列選項：
  + `ACTIVE_TRACKING`：此選項會主動追蹤使用者的位置更新。
  + `BATTERY_SAVER_TRACKING`：此選項每 15 分鐘追蹤一次使用者的位置更新。
+ **類別**： `LocationTracker`

  `stopBackgroundService()`

  當應用程式在背景時，停止存取使用者位置並將其傳送至 AWS 追蹤器的程序。
+ **類別**： `LocationTracker`

  `getTrackerDeviceLocation()`

  從 Amazon Location 服務擷取裝置位置。
+ **類別**： `LocationTracker`

  `getDeviceLocation(locationTrackingCallback: LocationTrackingCallback?)`

  從融合位置提供者用戶端擷取目前的裝置位置，並將其上傳至 Amazon Location 追蹤器。
+ **類別**： `LocationTracker`

  `uploadLocationUpdates(locationTrackingCallback: LocationTrackingCallback?)`

  根據設定的位置篩選條件篩選後，將裝置位置上傳至 Amazon Location 服務。
+ **類別**： `LocationTracker`

  `enableFilter(filter: LocationFilter)`

  啟用特定位置篩選條件。
+ **類別**： `LocationTracker`

  `checkFilterIsExistsAndUpdateValue(filter: LocationFilter)`

  停用特定位置篩選條件。
+ **類別**： `LocationTrackerConfig`

  `LocationTrackerConfig( // Required var trackerName: String, // Optional var locationFilters: MutableList = mutableListOf( TimeLocationFilter(), DistanceLocationFilter(), ), var logLevel: TrackingSdkLogLevel = TrackingSdkLogLevel.DEBUG, var accuracy: Int = Priority.PRIORITY_HIGH_ACCURACY, var latency: Long = 1000, var frequency: Long = 1500, var waitForAccurateLocation: Boolean = false, var minUpdateIntervalMillis: Long = 1000, var persistentNotificationConfig: NotificationConfig = NotificationConfig()) `

  這會初始化`LocationTrackerConfig`具有使用者定義參數值的 。如果未提供參數值，則會將其設定為預設值。
+ **類別**： `LocationFilter`

  `shouldUpload(currentLocation: LocationEntry, previousLocation: LocationEntry?): Boolean`

  `LocationFilter` 是使用者可以為其自訂篩選條件實作實作的通訊協定。您需要實作 `shouldUpload`函數來比較先前和目前的位置，如果應該上傳目前的位置，則傳回 。

## 範例
<a name="loc-mobile-tracking-example-android"></a>

下列程式碼範例顯示行動追蹤 SDK 功能。

此範例使用 `LocationTracker`開始和停止背景追蹤：

```
// For starting the location tracking
locationTracker?.startBackground(
BackgroundTrackingMode.ACTIVE_TRACKING,
object : ServiceCallback {
    override fun serviceStopped() {
        if (selectedTrackingMode == BackgroundTrackingMode.ACTIVE_TRACKING) {
            isLocationTrackingBackgroundActive = false
        } else {
            isLocationTrackingBatteryOptimizeActive = false
        }
    }
},
)

// For stopping the location tracking
locationTracker?.stopBackgroundService()
```

# 搭配 Amazon Location 使用 MapLibre 工具和相關程式庫
<a name="dev-maplibre"></a>

[MapLibre](https://maplibre.org/) 主要是用於在 Web 或行動應用程式中顯示地圖的轉譯引擎。不過，它還包含對外掛程式的支援，並提供使用 Amazon Location 其他方面的功能。以下說明您可以根據要使用的區域或位置使用的工具。

**注意**  
若要使用 Amazon Location 的任何方面，請[AWS 為您要使用的語言安裝 SDK](dev-by-language.md)。
+ **地圖**

  若要在應用程式中顯示地圖，您需要一個地圖轉譯引擎，該引擎將使用 Amazon Location 提供的資料，並繪製至螢幕。地圖轉譯引擎也提供平移和縮放地圖的功能，或將標記或推送銷和其他註釋新增至地圖。

  Amazon Location Service 建議使用 [MapLibre](https://github.com/maplibre/maplibre-gl-js) 轉譯引擎轉譯地圖。MapLibre GL JS 是一種在 JavaScript 中顯示映射的引擎，而 MapLibre Native 提供 iOS 或 Android 的映射。

  MapLibre 也有外掛程式生態系統來擴展核心功能。如需詳細資訊，請造訪 https：//[https://maplibre.org/maplibre-gl-js/docs/plugins/](https://maplibre.org/maplibre-gl-js/docs/plugins/)。
+ **Places 搜尋**

  若要更輕鬆地建立搜尋使用者介面，您可以使用適用於 Web 的 [MapLibre 地理編碼器](https://github.com/maplibre/maplibre-gl-geocoder) (Android 應用程式可以使用 [Android Places 外掛程式](https://github.com/maplibre/maplibre-plugins-android/tree/master/plugin-places))。

  使用 [Amazon Location for MapLibre 地理編碼器程式庫](https://github.com/aws-geospatial/amazon-location-for-maplibre-gl-geocoder?tab=readme-ov-file)，簡化`amazon-location-for-maplibre-gl-geocoder`在 JavaScript 應用程式中搭配 使用 Amazon Location 的程序。

  如需詳細資訊，請參閱[使用 Amazon Location MapLibre Geocoder GL 外掛程式](dev-maplibre-geocoder.md)。
+ **路由**
+ **地理圍欄和追蹤器**

  MapLibre 沒有任何用於地理圍欄和追蹤的特定轉譯或工具，但您可以使用轉譯功能和[外掛程式](https://maplibre.org/maplibre-gl-js/docs/plugins/)在地圖上顯示地理圍欄和追蹤的裝置。

  追蹤的裝置可以使用 [MQTT](tracking-using-mqtt.md) 或手動傳送更新至 Amazon Location Service。可以使用 回應地理圍欄事件[AWS Lambda](https://docs.aws.amazon.com/lambda/)。

許多開放原始碼程式庫可用於為 Amazon Location Service 提供額外的功能，例如提供空間分析功能的 [Turf](https://github.com/Turfjs/turf)。

許多程式庫使用開放的標準 [GeoJSON](https://geojson.org/) 格式資料。Amazon Location Service 提供程式庫，可將回應轉換為 GeoJSON，以用於 JavaScript 應用程式。如需詳細資訊，請參閱[適用於 Amazon Location Service SDKs 和架構](dev-sdks.md)。

# 依語言分類SDKs
<a name="dev-by-language"></a>

**開發套件版本**  
我們建議您使用在專案中使用的軟體 AWS 開發套件和任何其他SDKs的最新組建，並將軟體SDKs保持在最新狀態。 AWS 開發套件為您提供最新的功能和功能，以及安全性更新。若要尋找適用於 JavaScript 的 AWS SDK 最新組建，請參閱適用於 *AWS JavaScript 的 SDK* 文件中的[瀏覽器安裝](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html#In_the_Browser)主題。

下表依應用程式類型提供語言和架構的 AWS SDKs 和 Map Rendering Framework 版本相關資訊：Web、行動或後端應用程式。

------
#### [ Web frontend ]

下列 AWS SDKs和 Map Rendering Framework 版本可用於 Web 前端應用程式開發。


| 語言/架構 | AWS 開發套件 | 映射轉譯架構 | 
| --- | --- | --- | 
|  **完全支援**  | 
|  JavaScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  ReactJS  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  TypeScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  **部分支援**  | 
|  流暢度  |  [https://docs.amplify.aws/start/q/integration/flutter/](https://docs.amplify.aws/start/q/integration/flutter/) Flutter 尚未完全受到 支援 AWS，但透過 Amplify 提供有限的支援。  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 程式庫被視為實驗性。  | 
|  Node.js  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native) [https://www.npmjs.com/package/@maplibre/maplibre-gl-native](https://www.npmjs.com/package/@maplibre/maplibre-gl-native) | 
|  PHP  |  [https://aws.amazon.com/sdk-for-php/](https://aws.amazon.com/sdk-for-php/)  |  PHP 不支援 MapLibre。  | 

------
#### [ Mobile frontend ]

下列 AWS SDKs和 Map Rendering Framework 版本可用於行動前端應用程式開發。


| 語言/架構 | AWS 開發套件 | 映射轉譯架構 | 
| --- | --- | --- | 
|  **完全支援**  | 
|  Java  |  [https://aws.amazon.com/sdk-for-java/](https://aws.amazon.com/sdk-for-java/)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  Kotlin  |  [https://aws.amazon.com/sdk-for-kotlin/](https://aws.amazon.com/sdk-for-kotlin/)  適用於 Android 的 Amazon Location Service Mobile Authentication SDK：https：//[https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-android](https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-android) 適用於 Android 的 Amazon Location Service Mobile Tracking SDK：https：//[https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-android](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-android)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native) 需要自訂繫結，因為 MapLibre 是以 Java 為基礎。  | 
|  ObjectiveC  |  [https://github.com/aws-amplify/aws-sdk-ios](https://github.com/aws-amplify/aws-sdk-ios)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  ReactNative  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  Swift  |  [https://aws.amazon.com/sdk-for-swift/](https://aws.amazon.com/sdk-for-swift/) 適用於 iOS 的 Amazon Location Service Mobile Authentication SDK：https：//[https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios](https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios) 適用於 iOS 的 Amazon Location Service Mobile Tracking SDK：https：//[https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  **部分支援**  | 
|  流暢度  |  [https://docs.amplify.aws/start/q/integration/flutter/](https://docs.amplify.aws/start/q/integration/flutter/) Flutter 尚未完全受到 支援 AWS，但透過 Amplify 提供有限的支援。  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 程式庫被視為實驗性。  | 

------
#### [ Backend application ]

下列 AWS SDKs可用於後端應用程式開發。此處未列出映射轉譯架構，因為後端應用程式通常不需要映射轉譯。


| 語言 | AWS 開發套件 | 
| --- | --- | 
|  .NET  |  [https://aws.amazon.com/sdk-for-net/](https://aws.amazon.com/sdk-for-net/)  | 
|  C\$1\$1  |  [https://aws.amazon.com/sdk-for-cpp/](https://aws.amazon.com/sdk-for-cpp/)  | 
|  Go  |  [https://aws.amazon.com/sdk-for-go/](https://aws.amazon.com/sdk-for-go/)  | 
|  Java  |  [https://aws.amazon.com/sdk-for-java/](https://aws.amazon.com/sdk-for-java/)  | 
|  JavaScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | 
|  Node.js  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | 
|  TypeScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | 
|  Kotlin  |  [https://aws.amazon.com/sdk-for-kotlin/](https://aws.amazon.com/sdk-for-kotlin/)  | 
|  PHP  |  [https://aws.amazon.com/sdk-for-php/](https://aws.amazon.com/sdk-for-php/)  | 
|  Python  |  [https://aws.amazon.com/sdk-for-python/](https://aws.amazon.com/sdk-for-python/)  | 
|  Ruby  |  [https://aws.amazon.com/sdk-for-ruby/](https://aws.amazon.com/sdk-for-ruby/)  | 
|  Rust  |  [https://aws.amazon.com/sdk-for-rust/](https://aws.amazon.com/sdk-for-rust/) 適用於 Rust 的 AWS SDK 處於開發人員預覽版中。  | 

------

# 依語言映射轉譯 SDK
<a name="map-rendering-by-language"></a>

我們建議使用 [MapLibre](https://github.com/maplibre/maplibre-gl-js) 轉譯引擎轉譯 Amazon Location Service 映射。

MapLibre 是一種在 Web 或行動應用程式中顯示地圖的引擎。MapLibre 也有外掛程式模型，並支援使用者界面以某些語言和平台搜尋和路由。

若要進一步了解如何使用 MapLibre 及其提供的功能，請參閱 [搭配 Amazon Location 使用 MapLibre 工具和相關程式庫](dev-maplibre.md)和 [如何使用動態地圖](dynamic-maps-how-to.md)。

下表依應用程式類型提供語言和架構的 Map Rendering SDKs 版本相關資訊：Web 或行動應用程式。

------
#### [ Web frontend ]

下列 Map Rendering SDKs可用於 Web 前端應用程式開發。


| 語言/架構 | 地圖轉譯架構 | 
| --- | --- | 
|  **完全支援**  | 
|  JavaScript  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  ReactJS  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  TypeScript  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  **部分支援**  | 
|  流暢度  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 程式庫被視為實驗性。  | 
|  Node.js  |   Node.js 不支援 MapLibre。  | 
|  PHP  |   PHP 不支援 MapLibre。  | 

------
#### [ Mobile frontend ]

下列 Map Rendering SDKs可用於行動前端應用程式開發。


| 語言/架構 | 地圖轉譯架構 | 
| --- | --- | 
|  **完全支援**  | 
|  Java  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  Kotlin  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native) 需要自訂繫結，因為 MapLibre 是以 Java 為基礎。  | 
|  ObjectiveC  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  ReactNative  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  Swift  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  **部分支援**  | 
|  流暢度  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 程式庫被視為實驗性。  | 

------

# 地址表單 SDK
<a name="address-form-sdk"></a>

地址表單 SDK 可簡化建置智慧型地址輸入表單。使用 SDK 建置的地址表單會在使用者開始輸入時提供相關的地址建議。當使用者選取建議時，地址表單會自動填入城市、州和郵遞區號等欄位。這可透過將手動輸入降至最低，減少錯誤並加快資料輸入速度。使用者也可以在地圖上預覽選取的地址，並調整其位置 pin 以指出特定的入口或接收位置，大幅提高準確性。

![\[顯示自動完成功能的地址表單 SDK 示範\]](http://docs.aws.amazon.com/zh_tw/location/latest/developerguide/images/address-form-demo.gif)


## 試用
<a name="address-form-try-it"></a>

### 示範
<a name="address-form-demo"></a>

嘗試全功能[地址表單示範](https://aws-geospatial.github.io/address-form-sdk-js/)。

### 自行建置
<a name="address-form-builder"></a>

跳到 [開始使用](#address-form-getting-started) 以使用地址表單 SDK 開始實作地址表單，或使用 Location Service 的 WYSIWYG [地址表單建置器精靈](https://console.aws.amazon.com/location/solution-builder/home#/address-form)嘗試無程式碼方法，該精靈採用此 SDK 技術，並可在 Amazon Location Service 主控台中存取，網址為 https：//[https://console.aws.amazon.com/location/](https://console.aws.amazon.com/location/)。此互動式精靈可讓您建立具有預測建議、自動欄位人口和彈性配置的自訂表單。開發人員可以在 React JavaScript、React TypeScript 或獨立 HTML/JavaScript 中下載ready-to-use套件，以便輕鬆整合，而無需撰寫任何程式碼。

## 主要功能
<a name="address-form-features"></a>

地址表單 SDK 的主要功能包括：
+ 為地址和 POIs 提供內建預先分類建議，加速資料輸入。
+ 啟用可設定的位置類型搜尋 （例如郵遞區號、地區），以獲得更精確的結果。
+ 提供自動瀏覽器位置偵測，以快速將使用者集中在其目前區域。
+ 顯示內建地圖視覺效果，以提升清晰度和內容。
+ 允許在地圖上調整地址位置，而不會遺失系統提供的位置，以確保準確性和控制。
+ 包含不需要編碼的 WYSIWYG 建置器工具，可節省時間和精力。
+ 實作 typeahead APIs 的解引導和快取，以最佳化效能並降低成本。
+ 支援樣式自訂，以符合應用程式的品牌和使用者體驗。

它使用以下 Amazon Location Service API 操作來提供地址資訊以定址表單：

**[GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html)**  
擷取用於轉譯互動式地圖的地圖圖磚，以視覺化地址的位置並調整地址的位置。

**[自動完成](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html)**  
以使用者類型提供即時地址建議。

**[建議](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html)**  
以使用者類型提供即時地址和 POI 建議。

**[ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html)**  
如果使用者選擇根據其目前位置自動填寫其地址，則將使用者的目前位置轉換為最近的已知地址。

**[GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html)**  
從 Autocomplete 或建議 API 的結果中選取地址後，擷取所選地址的詳細位置資訊。

## 定價
<a name="address-form-pricing"></a>

開發套件是根據 Apache-2.0 授權免費提供的[開放原始碼](https://github.com/aws-geospatial/address-form-sdk-js)。您只需支付 API 用量。請參閱 [Amazon Location Service 定價頁面](https://aws.amazon.com/location/pricing/)。

## 開始使用
<a name="address-form-getting-started"></a>

地址表單 SDK 可用於 React 應用程式或獨立的 HTML 和 JavaScript 頁面。請依照下列指示開始使用。

### 先決條件
<a name="address-form-prerequisites"></a>

**注意**  
地址表單 SDK 需要具有必要許可的 API 金鑰，才能正常運作。使用 Amazon Location Service 主控台中的[地址表單 SDK Builder 精靈](https://console.aws.amazon.com/location/solution-builder/home#/address-form)建立具有下列許可的 API 金鑰，或依照下列指示手動建立金鑰。

使用 地址表單 SDK 需要在 API 金鑰政策中允許下列動作：
+ `geo-maps:GetTile` - 顯示地圖元件時需要此項目。請參閱 [GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html) API 參考。
+ `geo-places:Autocomplete` - 對 typeahead 功能使用 `Autocomplete`操作時，這是必要的。請參閱 [Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) API 參考。
+ `geo-places:Suggest` - 對 typeahead 功能使用 `Suggest`操作時，這是必要的。請參閱[建議](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html) API 參考。
+ `geo-places:ReverseGeocode` - 當允許使用者使用瀏覽器的地理位置 API 提供其目前位置時，這是必要的。請參閱 [ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html) API 參考。
+ `geo-places:GetPlace` - 使用 typeahead 功能時需要此項目。請參閱 [GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html) API 參考。

遵循[使用 API 金鑰來驗證](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html)指南，以建立具有必要許可的 Amazon Location Service API 金鑰。

具有必要許可的 [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html) API 的金鑰政策範例：

#### 地址表單許可的 CreateKey 請求
<a name="createkey-example"></a>

```
{
  "KeyName": "ExampleKey",
  "ExpireTime": "YYYY-MM-DDThh:mm:ss.sss",
  "Restrictions": {
    "AllowActions": [
      "geo-maps:GetTile",
      "geo-places:Autocomplete",
      "geo-places:Suggest",
      "geo-places:GetPlace",
      "geo-places:ReverseGeocode"
    ],
    "AllowResources": [
      "arn:aws:geo-maps:<Region>::provider/default",
      "arn:aws:geo-places:<Region>::provider/default"
    ]
  }
}
```

### 安裝
<a name="address-form-installation"></a>

#### HTML/JavaScript
<a name="address-form-html-js-install"></a>

在 HTML 程式碼中包含開發套件的下列 CSS 和 JavaScript 

```
...
<head>
...
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
/>
...
</head>
...
<body>
...
<script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
</body>
...
```

#### 反應
<a name="address-form-react-install"></a>

從 npm 安裝 SDK： `npm install @aws/address-form-sdk-js`

### 使用 SDK
<a name="address-form-use-sdk"></a>

將下列程式碼新增至您的 React 應用程式。`AMAZON_LOCATION_API_KEY` 使用您的 API 金鑰和建立 API 金鑰`AMAZON_LOCATION_REGION`的區域進行更新。提交表單時，回`onSubmit`呼會提供`getData`非同步函數。使用 `intendedUse`值呼叫此函數來擷取表單資料。

```
onSubmit: async (getData) => {
  const data = await getData({
    intendedUse: "SingleUse", // or "Storage"
  });
};
```

**注意**  
`"Storage"` 如果您需要存放或快取結果，請使用 。這可確保符合 Amazon Location Service [預期用途要求](https://docs.aws.amazon.com/location/latest/developerguide/places-intended-use.html)。

------
#### [ HTML/JavaScript ]

```
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Address Form</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
    />
  </head>
  <body>
    <form
      id="amazon-location-address-form"
      class="address-form flex-row flex-1"
    >
      <div class="flex-column">
        <input
          data-type="address-form"
          name="addressLineOne"
          data-api-name="suggest"
          data-show-current-location="true"
        />
        <input data-type="address-form" name="addressLineTwo" />
        <input data-type="address-form" name="city" />
        <input data-type="address-form" name="province" />
        <input data-type="address-form" name="postalCode" />
        <input data-type="address-form" name="country" />
        <div class="flex-row">
          <button data-type="address-form" type="submit">Submit</button>
          <button data-type="address-form" type="reset">Reset</button>
        </div>
      </div>
      <div data-type="address-form" data-map-style="Standard,Light"></div>
    </form>
    <></script>
script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"
    <script>
      AddressFormSDK.render({
        root: "#amazon-location-address-form",
        apiKey: "AMAZON_LOCATION_API_KEY",
        region: "AMAZON_LOCATION_REGION",
        showCurrentCountryResultsOnly: true,
        onSubmit: async (getData) => {
          // Get form data with intendedUse parameter
          // Use "SingleUse" for one-time display only
          // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
          const data = await getData({ intendedUse: "SingleUse" });
          console.log(data);
        },
      });
    </script>
  </body>
</html>
```

------
#### [ React ]

```
import React from 'react';
import { AddressForm, Flex } from "@aws/address-form-sdk-js";

export default function App() {
  return (
    <AddressForm
      apiKey="AMAZON_LOCATION_API_KEY"
      region="AMAZON_LOCATION_REGION"
      onSubmit={async (getData) => {
        // Get form data with intendedUse parameter
        // Use "SingleUse" for one-time display only
        // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
        const data = await getData({ intendedUse: "SingleUse" });
        console.log(data);
      }}
    >
      <Flex
        direction="row"
        flex
      >
        <Flex direction="column">
          <input
            data-api-name="autocomplete"
            data-type="address-form"
            name="addressLineOne"
            placeholder="Enter address"
          />
          <input
            data-type="address-form"
            name="addressLineTwo"
          />
          <input
            data-type="address-form"
            name="city"
            placeholder="City"
          />
          <input
            data-type="address-form"
            name="province"
            placeholder="State/Province"
          />
          <input
            data-type="address-form"
            name="postalCode"
          />
          <input
            data-type="address-form"
            name="country"
            placeholder="Country"
          />
          <Flex direction="row">
            <button address-form="submit">
              Submit
            </button>
            <button address-form="reset">
              Reset
            </button>
          </Flex>
        </Flex>
        <AddressFormMap
          mapStyle={[
            'Standard',
            'Light'
          ]}
         />
      </Flex>
    </AddressForm>
  );
}
```

------

## 支援的國家/地區
<a name="address-form-supported-countries"></a>

地址表單 SDK 支援使用 Amazon Location Service 在全球自動填入地址。下列國家/地區對地址欄位剖析提供完整支援，其中每個地址元件都會填入其個別欄位：
+ 澳洲 (AU)
+ 加拿大 (CA)
+ 法國 (FR)
+ 香港特別行政區 (HK)
+ 愛爾蘭 (IE)
+ 紐西蘭 (紐西蘭)
+ 菲律賓 (PH)
+ 新加坡 (SG)
+ 英國 (GB)
+ 美國 (US)

所有其他國家/地區都處於預覽狀態。預覽國家/地區會在`addressLineOne`欄位中顯示完整的地址，而不需要國家/地區特定的格式。未來的版本將改善此行為，您可以使用最新版本的 SDK 來存取這些改進項目。

## 支援的 AWS 區域
<a name="address-form-supported-aws-regions"></a>

地址表單 SDK 和地址表單建置器精靈可在 Amazon Location Service 運作的所有 AWS 區域使用其 APIs的`Current`版本。檢視 [Amazon Location 支援區域中支援區域](https://docs.aws.amazon.com/location/latest/developerguide/location-regions.html)的完整清單。

## API 參考
<a name="address-form-api-reference"></a>

請參閱 [README API 參考](https://github.com/aws-geospatial/address-form-sdk-js#api-reference)。