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` システムが自動的に付与するNormalパーミッション。	ステータスバー通知を表示することで、アプリがフォアグラウンドの状態を維持できるようにします。詳細については、AndroidデベロッパードキュメントのForeground services（英語のみ）を参照してください。

一般的なガイドラインとして、リクエストするパーミッションはアプリに必要なものだけにしてください。アプリの機能に正確な位置情報が必要ない場合は、おおよその位置情報権限のみを使用することを検討してください。Android 12以降では、ユーザーがおおよその位置情報へのアクセスのみをアプリに許可する可能性があります。おおよその位置情報にのみアクセスできるパーミッションが付与された場合にも、アプリが期待どおりに動作することを確認してください。

A3LLocationProviderClientのインスタンスの作成

A3L Locationを使用するには、A3LLocationProviderClientクラスのインスタンスを作成します。A3LLocationProviderClientオブジェクトは、A3L Locationのコアメソッドを提供します。このクラスのインスタンスを作成するには、以下のコードに示すように、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()メソッドを使用します。利用できる位置情報の履歴がない場合、このメソッドはnullを返します。

// getLastLocation
Task<Location> lastKnownLocation = a3LLocationProviderClient.getLastLocation();

A3LLastLocationRequestを使用して最後に確認された位置情報を取得する方法

getCurrentLocation()メソッドと同様に、getLastLocation()リクエストは、複数のパラメーターを含むA3LLastLocationRequestオブジェクトを渡すことでカスタマイズできます。

最後に確認された位置情報のリクエストには、リクエストする位置情報の詳細度（正確またはおおよそ）を定義したり、返される位置情報の最大有効期間を追加したりできます。そのためには、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オブジェクトを無視します。

一般的なA3L Location API
A3L Location APIリファレンス（英語のみ）

Last updated: 2023年9月13日