Amazon Location 开发工具包和库 - Amazon Location Service
如何开始使用 Amazon Location 开发工具包Amazon Location 客户端JavaScript 身份验证助手GeoJSON 转换帮助程序安卓手机认证 SDKiOS 移动身份验证软件开发工具包安卓手机追踪 SDKiOS 移动追踪软件开发工具包

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

Amazon Location 开发工具包和库

Amazon Location 开发工具包是一组开源库，为开发 Amazon Location 应用程序提供了有用的功能。包括以下功能：

  • Amazon Location 客户端 — AWS SDK v3 中的 Amazon Location 对象是捆绑和打包的，便于在网页开发中使用。

  • 身份验证 — 在为亚马逊定位服务构建网页、JavaScriptiO S 或 Android 应用程序时，身份验证实用程序简化了身份验证（使用 Amazon Cognito 或 API 密钥）。

  • 跟踪 — 移动追踪软件开发工具包适用于 iOS 和安卓系统。此 SDK 使移动应用程序可以更轻松地与 Amazon 位置追踪器进行交互。

  • 亚马逊定位 GeoJSON 函数 — GeoJ SON 转换实用程序可以轻松地在行业标准 GeoJSON 格式的数据和亚马逊定位 API 格式之间进行转换。

如何开始使用 Amazon Location 开发工具包

Amazon Location 开发工具包是一组函数，可以简化在应用程序中使用 Amazon Location Service。您可以将这些函数安装并导入到您的 JavaScript 应用程序中。以下各部分介绍 Amazon Location 客户端、身份验证和 GeoJSON 帮助程序库。

Amazon Location 客户端

在 S AWS DK v3 中，软件开发工具包是按服务分开的。您可以只安装您需要的部件。例如，要安装 Amazon Location 客户端和 Amazon Cognito 的凭证提供程序，请使用以下命令。

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

为了便于在 JavaScript 网络前端应用程序中使用 Amazon Location Servic AWS e，提供了亚马逊位置库和凭证提供商的托管包。要使用捆绑的客户端，请在脚本标签中将其添加到 HTML 中，如下所示：

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

该软件包保持最新状态并向后兼容，便于使用。使用此脚本标签或 NPM 安装将始终获得最新版本。

JavaScript 身份验证助手

通过您的 JavaScript 应用程序调用 Amazon Location API 时，Amazon Location 身份验证助手可以更轻松地进行身份验证。 JavaScript 在使用 Amazon Cognito 或 API 密钥作为身份验证方法时，此身份验证助手专门为您提供帮助。这是一个开源库，可在以下网址获得：https://github.com/aws-geospatial/ amazon-location-utilities-auth-helper-js。 GitHub

注意

身份验证帮助程序中的 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>

导入

要在 JavaScript 应用程序中使用特定函数，必须导入该函数。以下代码用于将 withIdentityPoolId 函数导入到您的应用程序中。

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

身份验证函数

Amazon Location 身份验证帮助程序包括以下返回 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 对象的此函数返回一个 JavaScript 对象credentials，其中的可用于初始化 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',
});

示例：使用 Amazon Cognito 从 AWS 适用于 JS 的软件开发工具包初始化定位客户端 AuthHelper

此示例使用 AWS 适用于 JavaScript v3 的 SDK。

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

示例：使用 API 密钥从 AWS 适用于 JS 的 SDK 初始化位置客户端 AuthHelper

此示例使用 AWS 适用于 JavaScript v3 的 SDK。

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

GeoJSON 转换帮助程序

Amazon Location GeoJSON 转换帮助程序提供了将 Amazon Location Service 数据类型与行业标准 GeoJSON 格式相互转换和转换的工具。例如，使用 GeoJSON 在 MapLibre 地图上呈现地理数据。这是一个开源库，可在以下网址获得：https://github.com/aws-geospatial/ amazon-location-utilities-datatypes-js。 GitHub

安装

你可以在本地安装中使用这些库，比如 webpack，也可以在 html 中加入带有<script>标签的预建 JavaScript 捆绑包。

  • 使用以下命令通过 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>

导入

要在 JavaScript 应用程序中使用特定函数，必须导入该函数。以下代码用于将 placeToFeatureCollection 函数导入到您的应用程序中。

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

GeoJSON 转换函数

Amazon Location GeoJSON 转换帮助程序包括以下函数：

  • placeToFeatureCollection(place: GetPlaceResponse | searchPlaceIndexForPositionResponse | searchPlaceIndexForTextResponse, keepNull: boolean): Feature— 此函数将来自地点搜索功能的响应转换为具 FeatureCollection 有 1 个或更多点要素的 GeoJSON。

  • devicePositionToFeatureCollection(devicePositions: GetDevicePositionResponse | BatchGetDevicePositionResponse | GetDevicePositionHistoryResponse | ListDevicePositionsResponse, keepNull: boolean)— 此函数将来自跟踪器设备位置函数的响应转换为具 FeatureCollection 有 1 个或更多点要素的 GeoJSON。

  • routeToFeatureCollection(legs: CalculateRouteResponse): FeatureCollection— 此函数将来自计算路径函数的响应转换为 FeatureCollection 具有单个 MultiStringLine 要素的 GeoJSON。路径的每一段都由中的一个 LineString 条目表示 MultiStringLine。

  • geofenceToFeatureCollection(geofences: GetGeofenceResponse | PutGeofenceRequest | BatchPutGeofenceRequest | ListGeofencesResponse): FeatureCollection— 此函数将地理围栏函数的请求或响应转换为具有 Polygon 功能的 GeoJSON FeatureCollection 。它可以在响应和请求中转换地理围栏，从而允许您在使用或上传地理围栏之前在地图上显示地理围栏。 PutGeofence BatchPutGeofence

    此函数会将圆形地理围栏转换为具有近似多边形的特征，但也具有“中心”和“半径”属性，以便在必要时重新创建圆形地理围栏（参见下一个函数）。

  • featureCollectionToGeofences(featureCollection: FeatureCollection): BatchPutGeofenceRequestEntry[]— 此函数将具 FeatureCollection 有 Polygon 特征的 GeoJSON 转换为 BatchPutGeofenceRequestEntry 对象数组，因此结果可用于创建对的请求。 BatchPutGeofence

    如果中的要素具 FeatureCollection 有 “中心” 和 “半径” 属性，则会将其转换为圆形地理围栏请求条目，忽略多边形的几何形状。

示例：将搜索结果转换为点图层 MapLibre

此示例使用 AWS 适用于 JavaScript v3 的 SDK。

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

这些实用程序可帮助您在通过安卓应用程序调用 Amazon Location Service API 时进行身份验证。这在使用 Amazon Cognito 或 API 密钥作为身份验证方法时特别有用。

安卓移动身份验证 SDK 可在 github 上找到：适用于安卓的 Amazon Location Service 移动身份验证 SDK。此外，M AWS aven 存储库中还提供了移动身份验证 AWS SDK 和 SDK。

安装

要使用移动身份验证 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 密钥。

  • 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

在创建身份验证帮助程序和位置客户端提供程序实例时，您有两个选项。你可以使用 Amazon Location API 密钥或 Amazon Cognito 创建实例。

  • 要使用 Amazon Location 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 Location 客户端实例，然后调用亚马逊定位服务。以下示例搜索靠近指定纬度和经度的地方。

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 移动身份验证软件开发工具包

这些实用程序可帮助您在通过 iOS 应用程序调用 Amazon Location Service API 时进行身份验证。这在使用 Amazon Cognito 或 API 密钥作为身份验证方法时特别有用。

iOS 移动身份验证 SDK 可在 github 上找到：适用于 iO S 的 Amazon Location Service 移动身份验证 SDK。

安装

在 Xcode 项目中安装软件开发工具包：

  1. 转到 “文件”，然后在 XCode 项目中选择 “添加 Package 依赖关系”。

  2. 在搜索栏中键入包裹网址：https://github.com/aws-geospatial/ amazon-location-mobile-auth-sdk-ios/，然后按回车键。

  3. 选择amazon-location-mobile-auth-sdk-ios包裹，然后按 Add Packag e。

  4. 选择AmazonLocationiOSAuthSDK套餐产品并按 Add Packag e。

身份验证函数

身份验证助手 SDK 具有以下功能：

  • authHelper.authenticateWithApiKey("My-Amazon-Location-API-Key"): LocationCredentialsProvider：此函数返回LocationCredentialsProvider初始化后的 API 密钥。

  • authHelper.authenticateWithCognitoIdentityPool("My-Cognito-Identity-Pool-Id"): LocationCredentialsProvider：此函数返回LocationCredentialsProvider初始化后的，以便与 Amazon Cognito 身份池配合使用。

使用量

要使用移动身份验证 SDK，请在您的活动中添加以下语句：

import AmazonLocationiOSAuthSDK
import AWSLocationXCF

在创建身份验证帮助程序和位置客户端提供程序实例时，您有两个选项。你可以使用 Amazon Location API 密钥或 Amazon Cognito 创建实例。

  • 要使用 Amazon Location 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 Location 客户端实例，然后调用亚马逊定位服务。以下示例搜索靠近指定纬度和经度的地方。

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 提供的实用程序可帮助轻松进行身份验证、捕获设备位置以及向亚马逊位置追踪器发送位置更新。SDK 支持使用可配置的更新间隔对位置更新进行本地筛选。这可以降低数据成本，并优化您的 Android 应用程序的间歇性连接。

Android 追踪 SDK 可在以下网址获得 GitHub：适用于安卓的亚马逊定位移动追踪 SDK。此外，M AWS aven 存储库中还提供了移动身份验证 AWS SDK 和 SDK。安卓追踪 SDK 专为与通用 AWS SDK 配合使用而设计。

本节涵盖亚马逊定位移动追踪 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，因为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 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())

安卓移动 SDK 追踪功能

适用于 Android 的 Amazon Location 移动追踪 SDK 包括以下功能：

  • 班级:LocationTracker

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

    这是一个用于创建LocationTracker对象的初始化函数。它需要的实例 LocationCredentialsProvidertrackerName，也可以需要一个实例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 移动追踪软件开发工具包

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

iOS 追踪软件开发工具包可在以下网址获得 GitHub：适用于 iOS 的亚马逊定位移动追踪软件开发工具包。

本节涵盖亚马逊定位移动追踪 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包裹，然后单击 Add Packag e。

  4. 选择AmazonLocationiOSTrackingSDK套餐产品并点击 Add Packag e。

使用量

以下过程向您展示如何使用来自 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 软件开发工具包一起使用。

    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对象的初始化函数。它需要的实例 LocationCredentialsProvidertrackerName，也可以需要一个实例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 定位移动追踪 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)
    }
})
}