Amazon 位置SDK和圖書館 - Amazon Location Service
如何開始使用 Amazon 位置 SDKAmazon 位置客戶JavaScript 驗證助手地理JSON轉換助手安卓手機驗證 SDKiOS 行動裝置驗證 SDK安卓手機跟踪 SDKiOS 行動裝置追蹤 SDK

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

Amazon 位置SDK和圖書館

Amazon 位置SDK是一組開放原始碼程式庫，可為開發 Amazon 位置應用程式提供有用的功能。包括以下功能：

  • Amazon 位置客戶端 — 在 Amazon 位置對象 AWS SDKv3 被捆綁和打包，以便於在 Web 開發中使用。

  • 身份驗證 — 身份驗證實用程序簡化了在為 Amazon 定 Location Service 構建網頁JavaScript、iOS 或 Android 應用程序時的身份驗證（使用 Amazon Cognito 或API密鑰）。

  • 追蹤 — 行動追蹤功能SDKs適用於 iOS 和安卓系統。這SDK可讓行動應用程式更輕鬆地與 Amazon 位置追蹤器互動。

  • Amazon 地理位置JSON功能 — 地理位置轉JSON換公用程式可讓您輕鬆地在業界標準 Geo JSON 格式資料和 Amazon 位置API格式之間進行轉換。

如何開始使用 Amazon 位置 SDK

Amazon 位置SDK是一組功能，可以使在應用程序中使用 Amazon 定 Location Service 更加簡單。您可以安裝這些功能並將其導入到您的 JavaScript 應用程序中。以下各節說明 Amazon 位置用戶端，以及身份驗證和 Geo JSON 協助程式庫。

Amazon 位置客戶

同 AWS SDKv3，SDK由服務分開。您可以只安裝所需的零件。例如，若要安裝 Amazon 位置用戶端和 Amazon Cognito 的登入資料提供者，請使用下列命令。

npm install @aws-sdk/client-location
npm install @aws-sdk/credential-providers

為了方便在 JavaScript Web 前端應用程序中使用 Amazon 定 Location Service， AWS 提供 Amazon 位置程式庫和登入資料供應商的託管服務包。要使用捆綁的客戶端，請將其添加到腳本標記HTML中，如下所示：

<script src="https://unpkg.com/@aws/amazon-location-client@1.x/dist/amazonLocationClient.js"></script>
注意

該包裝保持最新狀態，並向後兼容以便於使用。使用此腳本標記或NPM安裝將始終獲得最新版本。

JavaScript 驗證助手

Amazon 位置 JavaScript 身份驗證協助程式可讓您在從應用程式撥打 Amazon 位置API呼叫時更輕鬆地進行驗 JavaScript 證。在使用 Amazon Cognito 或API金鑰做為身分驗證方法時，此身份驗證協助程式會特別協助您。這是一個開源庫 GitHub，可在此處使用：https://github.com/aws-geospatial/amazon-location-utilities-auth-hel per-js。

注意

身分驗證協助程式中的 Amazon Cognito 支援不支援 Amazon Cognito 的聯合身分識別功能。

安裝

如果您使用 webpack 之類的構建系統，或者在 html 中包含帶有<script>標籤的預 JavaScript 構建包，則可以將庫與本地安裝一起使用。

  • 使用下列指令來安裝程式庫，使用NPM：

    npm install @aws/amazon-location-utilities-auth-helper

  • 在HTML檔案中使用下列命令來載入指令碼：

    <script src="https://unpkg.com/@aws/amazon-location-utilities-auth-helper@1.x/dist/amazonLocationAuthHelper.js"></script>

Import (匯入)

若要在 JavaScript 應用程式中使用特定函數，您必須匯入該函數。下面的代碼用於withIdentityPoolId將函數導入到您的應用程序。

import { withIdentityPoolId } from '@aws/amazon-location-utilities-auth-helper';

驗證功能

Amazon 位置身份驗證協助程式包括下列傳回AuthHelper物件的函數：

  • async withIdentityPoolId( identityPoolId: string): AuthHelper— 此函數返回一個 AuthHelper 對象，初始化為與 Amazon Cognito 一起工作

  • async withAPIKey( API_KEY: string): AuthHelper-此函數返回一個 AuthHelper 對象，初始化為與API密鑰一起使用。

該AuthHelper對象提供了以下功能：

  • AuthHelper.getMapAuthenticationOptions()— 物件的此函數會傳回 AuthHelper 物 JavaScript 件，其中包含transformRequest可與 MapLibre JS 中的對應選項搭配使用的物件。僅在使用識別集區初始化時才提供。

  • AuthHelper.getLocationClientConfig()— AuthHelper 物件的此函數會傳回具有可credentials用來初始化的 JavaScript 物件 LocationClient。

  • AuthHelper.getCredentials()— AuthHelper 物件的此函數會從 Amazon Cognito 傳回內部登入資料。僅在使用識別集區初始化時才提供。

範例：使用 Amazon Cognito 初始化 MapLibre 地圖物件 AuthHelper

import { withIdentityPoolId } from '@aws/amazon-location-utilities-auth-helper';

const authHelper = await withIdentityPoolId("identity-pool-id"); // use Cognito pool id for credentials

const map = new maplibregl.Map({
    container: "map", // HTML element ID of map element
    center: [-123.1187, 49.2819], // initial map center point
    zoom: 16, // initial map zoom
    style: https://maps.geo.region.amazonaws.com/maps/v0/maps/mapName/style-descriptor', // Defines the appearance of the map
    ...authHelper.getMapAuthenticationOptions(), // Provides credential options required for requests to Amazon Location
});

示例：使用API鍵初始化 MapLibre 映射對象（AuthHelper在這種情況下不需要）

const map = new maplibregl.Map({
    container: "map", // HTML element ID of map element
    center: [-123.1187, 49.2819], // initial map center point
    zoom: 16, // initial map zoom
    style: https://maps.geo.region.amazonaws.com/maps/v0/maps/${mapName}/style-descriptor?key=api-key-id',
});

範例：初始化位置用戶端 AWS SDK對於 JS，使用 Amazon Cognito 和 AuthHelper

這個例子使用 AWS SDK對於 JavaScript 第 3 版。

import { withIdentityPoolId } from '@aws/amazon-location-utilities-auth-helper';

const authHelper = await withIdentityPoolId("identity-pool-id"); // use Cognito pool id for credentials

//initialize the Location client:
const client = new LocationClient({
    region: "region",
    ...authHelper.getLocationClientConfig() // sets up the Location client to use the Cognito pool defined above
});

//call a search function with the location client:
const result = await client.send(new SearchPlaceIndexForPositionCommand({
    IndexName: "place-index", // Place index resource to use
    Position: [-123.1187, 49.2819], // position to search near
    MaxResults: 10 // number of results to return
});

範例：初始化位置用戶端 AWS SDK對於 JS，使用API密鑰和 AuthHelper

這個例子使用 AWS SDK對於 JavaScript 第 3 版。

import { withAPIKey } from '@aws/amazon-location-utilities-auth-helper';

const authHelper = await withAPIKey("api-key-id"); // use API Key id for credentials

//initialize the Location client:
const client = new LocationClient({
    region: "region",
    ...authHelper.getLocationClientConfig() // sets up the Location client to use the API Key defined above
});

//call a search function with the location client:
const result = await client.send(new SearchPlaceIndexForPositionCommand({
    IndexName: "place-index", // Place index resource to use
    Position: [-123.1187, 49.2819], // position to search near
    MaxResults: 10 // number of results to return
});

地理JSON轉換助手

Amazon 位置地理位置轉JSON換輔助程式提供工具，可將 Amazon 定 Location Service 資料類型轉換為業界標準的 Geo JSON 格式，以及從其轉換。例如JSON，使用 Geo 在地圖上彩現地理資料。 MapLibre 這是一個開源庫，可在 GitHub此處使用：https://github.com/aws-geospatial/amazon-location-utilities-datatypes-js。

安裝

您可以將庫與本地安裝（例如 webpack）一起使用，也可以在 html 中 JavaScript 包含帶有<script>標籤的預構建包。

  • 使用下列指令來安裝程式庫NPM。

    npm install @aws/amazon-location-utilities-datatypes

  • 在HTML檔案中使用下列命令來載入指令碼：

    <script src="https://unpkg.com/@aws/amazon-location-utilities-datatypes@1.x/dist/amazonLocationDataConverter.js"></script>

Import (匯入)

若要在 JavaScript 應用程式中使用特定函數，您必須匯入該函數。下面的代碼用於placeToFeatureCollection將函數導入到您的應用程序。

import { placeToFeatureCollection } from '@aws/amazon-location-utilities-datatypes';

地理JSON轉換函數

Amazon 地理位置JSON轉換輔助程式包含下列功能：

  • placeToFeatureCollection(place: GetPlaceResponse | searchPlaceIndexForPositionResponse | searchPlaceIndexForTextResponse, keepNull: boolean): Feature— 此功能將地點搜索功能的響應轉換為JSON FeatureCollection 具有 1 個或多個 Point 功能的 Geo。

  • devicePositionToFeatureCollection(devicePositions: GetDevicePositionResponse | BatchGetDevicePositionResponse | GetDevicePositionHistoryResponse | ListDevicePositionsResponse, keepNull: boolean)— 此功能將跟踪器設備位置功能的響應轉換為JSON FeatureCollection 具有 1 個或多個 Point 功能的 Geo。

  • routeToFeatureCollection(legs: CalculateRouteResponse): FeatureCollection-此函數將響應從計算路由函數轉換為JSON FeatureCollection 具有單個 MultiStringLine 功能的 Geo。路線的每一段都由中的一個 LineString 項目表示 MultiStringLine。

  • geofenceToFeatureCollection(geofences: GetGeofenceResponse | PutGeofenceRequest | BatchPutGeofenceRequest | ListGeofencesResponse): FeatureCollection— 此功能將地理圍欄函數請求或響應轉換為JSON FeatureCollection 具有多邊形功能的地理位置。它可以在響應和請求中轉換地理圍欄，使您可以在使用或上傳地理圍欄之前在地圖上顯示地理圍欄。 PutGeofence BatchPutGeofence

    此功能將圓形地理圍欄轉換為具有近似多邊形的圖徵，但是如果需要，也將具有「中心」和「radius」屬性以重新創建圓形地理圍欄（請參閱下一個功能）。

  • featureCollectionToGeofences(featureCollection: FeatureCollection): BatchPutGeofenceRequestEntry[]— 此函數將JSON FeatureCollection 具有多邊形圖徵的 Geo 轉換為 BatchPutGeofenceRequestEntry 物件陣列，因此結果可用於建立要求 BatchPutGeofence。

    如果中的特徵 FeatureCollection 具有「中心」和「半徑」屬性，它將被轉換為一個圓的地理圍欄請求輸入，忽略多邊形的幾何圖形。

範例：將搜尋結果轉換為點圖層 MapLibre

這個例子使用 AWS SDK對於 JavaScript 第 3 版。

import { placeToFeatureCollection } from '@aws/amazon-location-utility-datatypes';

...

let map; // map here is an initialized MapLibre instance

const client = new LocationClient(config);
const input = { your_input };
const command = new searchPlaceIndexForTextCommand(input);
const response = await client.send(command);

// calling utility function to convert the response to GeoJSON
const featureCollection = placeToFeatureCollection(response);
map.addSource("search-result", featureCollection);
map.addLayer({
    id: "search-result",
    type: "circle",
    source: "search-result",
    paint: {
        "circle-radius": 6,
        "circle-color": "#B42222",
    },
});

安卓手機驗證 SDK

這些公用程式可協助您在從 Android 應用程式撥打 Amazon 定 Location Service API 呼叫時進行驗證。這在使用 Amazon Cognito 或API金鑰做為身份驗證方法時特別有幫助。

Android 移動身份驗證可SDK在 github 上找到：Amazon 定 Location Service 移動身份驗證安SDK卓系統。此外，移動身份驗證SDK和 AWS SDK可在 AWS Maven 倉庫。

安裝

要使用移動身份驗證SDK，請將以下導入語句添加到 Android Studio 中的build.gradle文件中。

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

驗證功能

身份驗證幫助程序SDK具有以下功能：

  • authHelper.authenticateWithApiKey("My-Amazon-Location-API-Key"): LocationCredentialsProvider：此函數返回LocationCredentialsProvider初始化以使用 API Key。

  • authHelper.authenticateWithCognitoIdentityPool("My-Cognito-Identity-Pool-Id"): LocationCredentialsProvider：此函數會傳回LocationCredentialsProvider初始化，以便與 Amazon Cognito 身分識別集區搭配使用。

用量

若要在程式碼SDK中使用，請匯入下列類別：

import com.amazonaws.services.geo.AmazonLocationClient
import software.amazon.location.auth.AuthHelper
import software.amazon.location.auth.LocationCredentialsProvider

建立驗證協助程式和位置用戶端提供者執行個體時，有兩個選項。您可以使用亞馬遜位置API金鑰或 Amazon Cognito 建立執行個體。

  • 若要使用 Amazon 位置API金鑰建立身份驗證協助程式執行個體，請按如下方式宣告協助程式類別：

    var authHelper = AuthHelper(applicationContext)
var locationCredentialsProvider : LocationCredentialsProvider = authHelper.authenticateWithApiKey("My-Amazon-Location-API-Key")

  • 若要使用 Amazon Cognito 建立身份驗證協助程式執行個體，請如下宣告協助程式類別：

    var authHelper = AuthHelper(applicationContext)
var locationCredentialsProvider : LocationCredentialsProvider = authHelper.authenticateWithCognitoIdentityPool("My-Cognito-Identity-Pool-Id")

您可以使用位置登入資料供應商建立 Amazon 位置用戶端執行個體，並撥打電話給 Amazon 位置服務。下列範例會搜尋指定緯度和經度附近的地點。

var locationClient = authHelper.getLocationClient(locationCredentialsProvider.getCredentialsProvider())
var searchPlaceIndexForPositionRequest = SearchPlaceIndexForPositionRequest().withIndexName("My-Place-Index-Name").withPosition(arrayListOf(30.405423, -97.718833))
var nearbyPlaces = locationClient.searchPlaceIndexForPosition(searchPlaceIndexForPositionRequest)

iOS 行動裝置驗證 SDK

這些公用程式可協助您在從 iOS 應用程式撥打 Amazon 定 Location Service API 呼叫時進行驗證。這在使用 Amazon Cognito 或API金鑰做為身份驗證方法時特別有幫助。

iOS 移動身份驗證可SDK在 github 上找到：適用SDK於 iOS 的 Amazon 定 Location Service 移動身份驗證。

安裝

安裝SDK在一個 Xcode 項目中：

  1. 轉到「文件」，然後在XCode項目中選擇「添加 Package 依賴關係」。

  2. 鍵入包URL：https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios/ 進入搜索欄，然後按回車鍵。

  3. 選擇 P amazon-location-mobile-auth-sdk-ios ackage 件，然後按下「新增套件」。

  4. 選擇 P AmazonLocationiOSAuthSDK ackage 產品，然後按添加包裹。

驗證功能

身份驗證幫助程序SDK具有以下功能：

  • authHelper.authenticateWithApiKey("My-Amazon-Location-API-Key"): LocationCredentialsProvider：此函數返回LocationCredentialsProvider初始化以使用 API Key。

  • authHelper.authenticateWithCognitoIdentityPool("My-Cognito-Identity-Pool-Id"): LocationCredentialsProvider：此函數會傳回LocationCredentialsProvider初始化，以便與 Amazon Cognito 身分識別集區搭配使用。

用量

若要使用行動驗證SDK，請將下列陳述式新增至您的活動：

import AmazonLocationiOSAuthSDK
import AWSLocationXCF

建立驗證協助程式和位置用戶端提供者執行個體時，有兩個選項。您可以使用亞馬遜位置API金鑰或 Amazon Cognito 建立執行個體。

  • 若要使用 Amazon 位置API金鑰建立身份驗證協助程式執行個體，請按如下方式宣告協助程式類別：

    let authHelper = AuthHelper()
let locationCredentialsProvider = authHelper.authenticateWithAPIKey(apiKey: "My-Amazon-Location-API-Key", region: "account-region")

  • 若要使用 Amazon Cognito 建立身份驗證協助程式執行個體，請如下宣告協助程式類別：

    let authHelper = AuthHelper()
let locationCredentialsProvider = authHelper.authenticateWithCognitoUserPool(identityPoolId: "My-Amazon-Location-API-Key", region: "account-region")

您可以使用位置登入資料供應商建立 Amazon 位置用戶端執行個體，並撥打電話給 Amazon 位置服務。下列範例會搜尋指定緯度和經度附近的地點。

let locationClient = AWSLocation.default()
let searchPlaceIndexForPositionRequest = AWSLocationSearchPlaceIndexForPositionRequest()!
searchPlaceIndexForPositionRequest.indexName = "My-Place-Index-Name"
searchPlaceIndexForPositionRequest.position = [30.405423, -97.718833]
let nearbyPlaces = locationClient.searchPlaceIndex(forPosition: searchPlaceIndexForPositionRequest)

安卓手機跟踪 SDK

Amazon Location 行動追蹤SDK提供公用程式，可協助您輕鬆進行身份驗證、擷取裝置位置，以及將位置更新傳送至 Amazon 位置追蹤器。SDK支援使用可設定的更新間隔對位置更新進行本機篩選。這樣可以降低數據成本並優化 Android 應用程序的間歇性連接。

安卓跟踪SDK是可用的 GitHub:Amazon 定位移動跟踪SDK為 Android. 此外，移動身份驗證SDK和 AWS SDK可在 AWS Maven 倉庫。Android 跟踪SDK旨在與普通人一起使用 AWS SDK.

本節涵蓋 Amazon 定位移動跟踪 Android 的以下主題SDK：

安裝

要安裝SDK，請將以下行添加到 Android 工作室中構建 .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")

用量

此程序說明如何使SDK用驗證和建立LocationTracker物件：

注意

此程序假設您已匯入本安裝節中提到的資源庫。

  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

  2. 接下來創建一個AuthHelper，因為LocationCredentialsProvider參數是創建對LocationTracker象所需的：

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

  3. 現在，使用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,
)

篩選條件

Amazon 位置移動跟踪 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())

安卓手機SDK追蹤功能

SDK適用於 Android 的 Amazon 位置移動跟踪包括以下功能：

  • 類別：LocationTracker

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

    這是一個初始化函數來創建一個LocationTracker對象。它需要的執行個體LocationCredentialsProvider，以trackerName及選擇性的執行個體LocationTrackingConfig。如果未提供配置，則將使用默認值初始化。

  • 類別：LocationTracker

    start(locationTrackingCallback: LocationTrackingCallback)

    開始存取使用者位置並將其傳送至 Amazon 位置追蹤器的程序。

  • 類別：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 定位服務擷取裝置位置。

  • 類別：LocationTracker

    getDeviceLocation(locationTrackingCallback: LocationTrackingCallback?)

    從融合的位置供應商用戶端擷取目前的裝置位置，並將其上傳到 Amazon 位置追蹤器。

  • 類別：LocationTracker

    uploadLocationUpdates(locationTrackingCallback: LocationTrackingCallback?)

    根據設定的位置篩選器進行篩選後，將裝置位置上傳至 Amazon 位置服務。

  • 類別：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功能來比較以前和當前位置，如果當前位置應該上傳返回。

範例

下列程式碼範例顯示行動裝置追蹤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()

iOS 行動裝置追蹤 SDK

Amazon Location 行動追蹤SDK提供公用程式，可協助您輕鬆進行身份驗證、擷取裝置位置，以及將位置更新傳送至 Amazon 位置追蹤器。SDK支援使用可設定的更新間隔對位置更新進行本機篩選。這樣可以降低數據成本並優化 iOS 應用程序的間歇性連接。

iOS 跟踪可用SDK於 GitHub：適用SDK於 iOS 的 Amazon 位置移動跟踪。

本節涵蓋 Amazon 定位移動跟踪 iOS 的以下主題SDK：

安裝

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

  1. 在您的 Xcode 項目中，轉到文件並選擇添加 Package 依賴項。

  2. 輸入以下內容URL：https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/ 進入搜索欄，然後按回車鍵。

  3. 選擇amazon-location-mobile-tracking-sdk-ios軟件包，然後單擊添加包。

  4. 選擇 P AmazonLocationiOSTrackingSDK ackage 產品，然後單擊添加包裹。

用量

下列程序說明如何使用 Cognito 的認證建立驗證協助程式。

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

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

  2. 接下來， AuthHelper 在你的班級中導入：

    import AmazonLocationiOSAuthSDKimport AmazonLocationiOSTrackingSDK

  3. 然後，您將創建一個AuthHelper對象並將其與 AWS SDK，透過使用 Amazon Cognito 的登入資料建立身份驗證協助程式。

    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)

篩選條件

Amazon 位置移動跟踪 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 行動裝置SDK追蹤功能

SDK適用於 iOS 的 Amazon 位置移動跟踪包括以下功能：

  • 類別：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功能來比較以前和當前位置，如果當前位置應該上傳返回。

範例

本節詳細介紹了使用適用SDK於 iOS 的 Amazon 位置移動跟踪的示例。

注意

請確定已在info.plist檔案中設定必要的權限。這些權限與用量區段中列出的權限相同。

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

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)
    }
})
}