如何使用跟踪 SDK - Amazon Location Service

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

如何使用跟踪 SDK

本主题提供了有关如何使用跟踪 SDK 的信息。

Amazon Location 移动跟踪 SDK 提供的实用程序可帮助您轻松进行身份验证、捕获设备位置以及向 Amazon Location 跟踪器发送位置更新。该 SDK 支持通过可配置的更新间隔对位置更新进行本地筛选。这样可以降低数据成本，并优化 iOS 应用程序的间歇性连接。

iOS 跟踪 SDK 可在 GitHub 上找到：适用于 iOS 的 Amazon Location 移动跟踪 SDK。

本节涵盖 Amazon Location 移动跟踪 iOS SDK 的以下主题：

安装

使用以下步骤安装适用于 iOS 的移动跟踪 SDK：

  1. 在您的 Xcode 项目中，转到文件，然后选择添加软件包依赖项。

  2. 在搜索栏中键入以下 URL：https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/，然后按 Enter 键。

  3. 选择 amazon-location-mobile-tracking-sdk-ios 软件包并单击添加软件包。

  4. 选择 AmazonLocationiOSTrackingSDK 软件包产品并单击添加软件包。

使用量

以下步骤介绍了如何从 Amazon 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. 然后，从 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)

筛选条件

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 移动 SDK 跟踪函数

适用于 iOS 的 Amazon Location 移动跟踪 SDK 包括以下函数：

  • 类：LocationTracker

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

    这是用于创建 LocationTracker 对象的初始化程序函数。它需要 LocationCredentialsProvider、trackerName 的实例，以及（可选）LocationTrackingConfig 的实例。如果未提供配置，将使用默认值对其进行初始化。

  • 类：LocationTracker

    setTrackerConfig(config: LocationTrackerConfig)

    它将跟踪器的配置设置为在位置跟踪器初始化后的任何时候生效。

  • 类：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 移动跟踪 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 跟踪器发送位置更新。该 SDK 支持通过可配置的更新间隔对位置更新进行本地筛选。这样可以降低数据成本，优化 Android 应用程序的间歇性连接。

Android 跟踪 SDK 可在 GitHub 上找到：适用于 Android 的 Amazon Location 移动跟踪 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")

使用量

以下步骤展示了如何使用该 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，因为创建 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")

  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 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 移动 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 Service 检索设备位置。

  • 类：LocationTracker

    getDeviceLocation(locationTrackingCallback: LocationTrackingCallback?)

    从融合位置提供程序客户端检索当前的设备位置，并将其上传到 Amazon Location 跟踪器。

  • 类：LocationTracker

    uploadLocationUpdates(locationTrackingCallback: LocationTrackingCallback?)

    根据配置的位置筛选器进行筛选后，将设备位置上传到 Amazon Location Service。

  • 类：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()