集成A3L Location SDK
请按照本指南将您的应用与A3L Location SDK集成。
权限
要使用位置API，您的应用必须有权限访问精确或粗略位置。请在您应用的清单文件中声明这些权限。下表列出了您的应用可能请求的与位置服务相关的Android权限。
| 权限 | 描述 |
|---|---|
ACCESS_COARSE_LOCATION您的应用必须请求的运行时权限。 |
当应用在前台时，允许应用访问大致位置。 |
ACCESS_FINE_LOCATION您的应用必须请求的运行时权限。 |
当应用在前台时，允许应用访问精确位置。 |
ACCESS_BACKGROUND_LOCATION您的应用必须请求的运行时权限。 |
当应用在后台时，允许应用访问位置。必须结合ACCESS_COARSE_LOCATION或ACCESS_FINE_LOCATION使用。 |
FOREGROUND_SERVICE系统自动授予的普通权限。 |
通过显示状态栏通知，允许应用维持前台状态。有关详细信息，请参阅有关前台服务的Android开发者文档。 |
一般而言，只请求应用必须使用的权限。如果您的应用在工作时不需要确切的位置，可以考虑只使用粗略位置的权限。在Android 12及更高版本上，用户可以选择在应用中只允许访问粗略位置。确保您的应用在仅具有粗略位置的权限时能正常工作。
创建A3LLocationProviderClient的实例
要使用A3L Location，创建A3LLocationProviderClient类的实例。A3LLocationProviderClient对象提供了A3L位置的核心方法。要创建该类的实例，可如以下代码所示使用A3LLocationServices.getA3LLocationProviderClient()方法。
A3LLocationProviderClient a3LLocationProviderClient = A3LLocationServices.getA3LLocationProviderClient(context);
获取设备的当前位置
位置服务的主要用途是确定设备的当前位置。在A3L Location中，要获取设备的当前位置，可使用getCurrentLocation()方法。您可以选择获取当前位置并传递优先级指示器，或如果您的应用有多个需求，可以传递A3LCurrentLocationRequest对象。有关A3LCurrentLocationRequest对象的详细信息，请参阅使用A3LCurrentLocationRequest获取当前位置。
使用优先级获取当前位置
要将getCurrentLocation()结合优先级使用，可传递A3LPriority常量。下表列出了可用的A3LPriority常量。如果你选择在应用中优先考虑更高的精度，设备会消耗更多的电量。如果选择优先考虑减少耗电量，则位置的精度会较低。
| A3L优先级常量 | 描述 |
|---|---|
A3LPriority.PRIORITY_BALANCED_POWER_ACCURACY |
在耗电量和精度之间平衡优先级。 |
A3LPriority.PRIORITY_HIGH_ACCURACY |
优先考虑高精度。设备耗电量更大。 |
A3LPriority.PRIORITY_LOW_POWER |
优先考虑减少耗电量。位置精度较低。 |
A3LPriority.PRIORITY_PASSIVE |
应用不请求位置更新。 |
以下代码演示了以平衡的优先级获取当前位置的示例。或者，如果您希望能够取消位置请求，可以传递CancellationToken对象。有关取消令牌的更多信息，请参阅创建取消令牌。
//使用优先级的getCurrentLocation。
Task<Location> currentLocation = a3LLocationProviderClient.getCurrentLocation(A3LPriority.PRIORITY_BALANCED_POWER_ACCURACY, cancellationToken);
创建取消令牌（可选）
如果希望能够取消位置请求，可以在getCurrentLocation()方法中传递CancellationToken对象。以下代码演示了如何创建取消令牌的示例。使用取消令牌是可选的做法。
//注： CancellationToken是可选字段。
CancellationToken cancellationToken = new CancellationTokenSource().getToken();
cancellationToken.onCanceledRequested(new OnTokenCanceledListener() {
@Override
public void onCanceled() {
//一旦请求了令牌取消，即会执行代码。
}
});
使用A3LCurrentLocationRequest获取当前位置
要在getCurrentLocation()请求中传递一个以上的参数，可以构建使用多个参数的A3LCurrentLocationRequest对象。例如，若您希望设置优先级和请求间隔两者，则可以构建A3LCurrentLocationRequest并指明符合您应用需求的具体优先级和请求间隔。
以下代码示出了如何创建使用多个参数的A3LCurrentLocationRequest对象。该示例使用粒度、最长更新间隔、优先级和持续时间。
//使用A3LCurrentLocationRequest的getCurrentLocation。
//注： 此代码中的生成器构造函数和值为示例。在您的实现中，
//使用您的应用所需的生成器构造函数和值。
A3LCurrentLocationRequest a3LCurrentLocationRequest = new A3LCurrentLocationRequest.Builder()
.setGranularity(A3LGranularity.GRANULARITY_PERMISSION_LEVEL)
.setMaxUpdateAgeMillis(1000L)
.setPriority(A3LPriority.PRIORITY_BALANCED_POWER_ACCURACY)
.setDurationMillis(1000L)
.build();
Task<Location> currentLocation = a3LLocationProviderClient.getCurrentLocation(a3LCurrentLocationRequest, cancellationToken);
如果需要构建A3LCurrentLocationRequest对象时可使用的参数的完整列表，请参阅的A3LCurrentLocationRequest.Builder()的API参考。
A3LCurrentLocationRequest视为无操作，并且无论传递的参数为何，都会返回位置。获取设备上个已知位置
如果需要提供当前可用的最近历史位置，可以如以下代码所示使用getLastLocation()方法。如果没有可用的历史位置，则该方法返回空值。
// getLastLocation
Task<Location> lastKnownLocation = a3LLocationProviderClient.getLastLocation();
使用A3LLastLocationRequest获取上个已知位置
和getCurrentLocation()方法相似，您可以通过传递具有多个参数的A3LLastLocationRequest对象，自定义您的getLastLocation()请求。
在您的上个已知位置请求中，可以定义所请求位置的粒度（精确或粗略），或添加所返回位置的最长间隔。为此，可构建A3LLastLocationRequest对象并将其传递至getLastLocation()方法。以下示例示出了使用粒度以及最长更新间隔构建的对象。
//使用A3LLastLocationRequest的getLastLocation
//注： 此代码中的生成器构造函数和值为示例。在您的实现中，
//使用您的应用所需的生成器构造函数和值。
A3LLastLocationRequest a3LLastLocationRequest = new A3LLastLocationRequest.Builder()
.setGranularity(A3LGranularity.GRANULARITY_FINE)
.setMaxUpdateAgeMillis(1000L)
.build();
Task<Location> lastKnownLocation2 = a3LLocationProviderClient.getLastLocation(a3LLastLocationRequest);
如果需要构建A3LLastLocationRequest对象时可使用的参数的完整列表，请参阅的A3LLastLocationRequest.Builder()的API参考。
A3LLastLocationRequest视为无操作。在这些设备上，getLastLocation()方法会忽略A3LLastLocationRequest对象。相关资源
Last updated: 2023年9月13日
