如何使用追蹤 SDKs

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

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

iOS 追蹤 SDK 可在 GitHub 上取得：適用於 iOS 的 Amazon Location Mobile Tracking SDK。

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

主題

安裝
用量
篩選條件
iOS Mobile SDK 追蹤函數
範例

安裝

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

在您的 Xcode 專案中，前往檔案，然後選取新增套件相依性。
在搜尋列中輸入下列 URL：https：//https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/。
選取amazon-location-mobile-tracking-sdk-ios套件，然後按一下新增套件。
選取AmazonLocationiOSTrackingSDK套件產品，然後按一下新增套件。

用量

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

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


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

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


import AmazonLocationiOSAuthSDKimport AmazonLocationiOSTrackingSDK

然後，您將建立 AuthHelper 物件，並使用 Amazon Cognito 的登入資料建立身分驗證協助程式，並將其與 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)

篩選條件

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 追蹤函數

適用於 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函數來比較先前和目前的位置，如果應該上傳目前的位置，則傳回。

範例

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

注意

確定已在 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)
    }
})
}

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

Android 追蹤 SDK 可在 GitHub 上取得：適用於 Android 的 Amazon Location Mobile Tracking SDK。此外，AWS Maven 儲存庫提供行動身分驗證 SDK 和 AWS SDK。Android 追蹤 SDK 旨在與一般 AWS SDK 搭配使用。

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

安裝

若要安裝 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")

用量

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

注意

此程序假設您已匯入安裝章節所述的程式庫。

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


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

接著建立 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")

現在，使用 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 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 追蹤函數

適用於 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函數來比較先前和目前的位置，如果應該上傳目前的位置，則傳回。

範例

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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 MapLibre Geocoder GL 外掛程式

使用 MapLibre 工具