集成A3L Location SDK

请按照本指南将您的应用与A3L Location SDK集成。

权限
创建A3LLocationProviderClient的实例
获取设备的当前位置
获取设备上个已知位置
- 使用A3LLastLocationRequest获取上个已知位置
相关资源

权限

要使用位置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参考。

注：没有Google Play服务的Android设备将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参考。

注：没有Google Play服务的设备将A3LLastLocationRequest视为无操作。在这些设备上，getLastLocation()方法会忽略A3LLastLocationRequest对象。

Last updated: 2023年9月13日