開発者コンソール
ログイン
ログイン
開発者コンソール

一般的なA3L Location API

一般的なA3L Location API

このページでは、A3L Location SDKの統合で説明されているA3L Locationの主な機能をサポートするためにアプリで使用できる、一般的なA3L Location APIについて説明します。

設定の確認

位置情報設定の現在の状態を取得するには、A3LLocationSettingsResponse.getLocationSettingsStates()メソッドを呼び出します。

ユーザーのデバイスのシステム設定をチェックして、位置情報サービスが位置情報リクエストを正常に実行できる状態になっていることを確認するには、checkLocationSettings() APIを使用します。必要な設定がデバイスで有効になっていないと判断された場合は、設定を有効にするように促すダイアログをユーザーに表示できます。

システム設定をチェックする前に、アプリで使用するA3LLocationRequestオブジェクトを含むA3LLocationSettingsRequest.Builderオブジェクトを作成する必要があります。次のコードは、2つの位置情報リクエストを含むA3LLocationSettingsRequest.Builderオブジェクトを作成する例を示しています。

A3LLocationSettingsRequest.Builder builder = new A3LLocationSettingsRequest.Builder()
        .addLocationRequest(mLocationRequestHighAccuracy)
        .addLocationRequest(mLocationRequestBalancedPowerAccuracy);

アプリで位置情報にBluetooth Low Energy（BLE）を使用する場合は、次のコードに示すように、setNeedBle()を使用してA3LLocationSettingsRequest.Builderオブジェクトを構築します。

builder.setNeedBle(true);

アプリでシステム設定をチェックするには、A3LLocationSettingsRequestオブジェクトを構築し、それをA3LSettingsClientクラスのcheckLocationSettings()メソッドに渡します。次に例を示します。

Task<A3LLocationSettingsResponse> result =
        A3LLocationServices.getSettingsClient(this).checkLocationSettings(builder.build());

結果を処理するには、完了時に呼び出されるリスナーをTaskに追加します。結果として例外がスローされた場合は、アプリでステータスコードを条件別にチェックして、問題を解決できるかどうかを判断できます。ステータスコードがRESOLUTION_REQUIREDの場合は、必要な設定を許可するように求めるダイアログをユーザーに表示できます。そのためには、ResolvableApiException.startResolutionForResult()を呼び出します。次に例を示します。

result.addOnCompleteListener(new OnCompleteListener<A3LLocationSettingsResponse>() {
    @Override
    public void onComplete(Task<A3LLocationSettingsResponse> task) {
        try {
            A3LLocationSettingsResponse response = task.getResult(ApiException.class);
            // システム設定は位置情報サービスを許可できます。
            ...
        } catch (ApiException exception) {
            switch (exception.getStatusCode()) {
                case A3LLocationSettingsStatusCodes.RESOLUTION_REQUIRED:
                    // システム設定は位置情報サービスを許可する状態ではありませんが、
                    // 解決できます。
                    try {
                        // 解決可能な例外にキャストします。
                        ResolvableApiException resolvable = (ResolvableApiException) exception;
                        // 解決を促すダイアログをユーザーに表示します。結果はonActivityResult()で検証します。
                        resolvable.startResolutionForResult(
                                OuterClass.this,
                                REQUEST_CHECK_SETTINGS);
                    } catch (SendIntentException e) {
                        // 無視します。
                    } catch (ClassCastException e) {
                        // 無視します。
                    }
                    break;
                case A3LLocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
                    // システム設定は位置情報サービスを許可する状態ではなく、
                    // 解決できません。
                    ...
                    break;
            }
        }
    }
});

ステータスコードの詳細については、A3LLocationSettingsStatusCodesのAPIドキュメント（英語のみ）を参照してください。

次の例では、onActivityResult()メソッド内でstartResolutionForResult()の結果を検証する方法を示します。

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    switch (requestCode) {
        case REQUEST_CHECK_SETTINGS:
            switch (resultCode) {
                case Activity.RESULT_OK:
                    // ユーザーが必要な設定を変更しました。
                   ...
                    break;
                case Activity.RESULT_CANCELED:
                    // ユーザーは必要な設定を変更しませんでした。
                    ...
                    break;
                default:
                    break;
            }
            break;
    }
}

位置情報が利用可能かどうかを取得する方法

位置情報データが利用可能かどうかを判断するには、getLocationAvailability()メソッドを使用します。Taskが正常に完了すると、結果としてA3LLocationAvailabilityオブジェクトが返されます。位置情報データを取得できる可能性を示すブール値を得るには、isLocationAvailable()メソッドを使用します。trueが返された場合、位置情報が利用可能であることを保証するものではありませんが、位置情報データを利用できる可能性が高いことを示します。同様に、falseが返された場合、位置情報が利用不可能であることを確定するものではありませんが、位置情報データを利用できない可能性が高いことを示します。次のコードは、位置情報が利用可能かどうかを取得する方法の例を示しています。

// getLocationAvailability
Task<A3LLocationAvailability> a3LLocationAvailability = a3LLocationProviderClient.getLocationAvailability();
a3LLocationAvailability.addOnCompleteListener(new OnCompleteListener<A3LLocationAvailability>() {
    @Override
    public void onComplete(@NonNull Task<A3LLocationAvailability> task) {
        // 完了時に実行するコード
        // ...
        if(task.isSuccessful()) {
            // isLocationAvailable()を使用して、位置情報APIが位置情報を取得できるかどうかを確認します。
            // 結果はAPIが位置情報を取得できることを保証するものではありませんが、取得できる可能性が高いことを示します。
            Boolean locationAvailable = task.getResult().isLocationAvailable();
        }
    }
});

Google Play開発者サービスのないAndroidデバイスでは、getLocationAvailability()メソッドは位置情報が有効か無効かを確認するだけの動作になります。

位置情報の継続的な更新をリクエストする方法

requestLocationUpdates()メソッドを使用すると、アプリで位置情報の更新を繰り返し取得することができます。アプリでユーザーの位置情報を経時的に追跡する場合、このAPIでそのユースケースに対応できます。requestLocationUpdates()メソッドは、A3LLocationRequest、A3LLocationListener、Looperを受け取ります。このAPIは、指定されたルーパー上でリスナーに結果を配信します。アプリで位置情報の更新リクエストを実行すると、以前に同じリスナーを使用して位置情報の更新リクエストを実行していた場合は、以前のリクエストが新しいリクエストで置き換えられます。次のコードは、位置情報の更新をリクエストする方法の例を示しています。

// 位置情報の更新をリクエストします。
A3LLocationListener a3lLocationListener = new A3LLocationListener() {
    @Override
    public void onLocationChanged(@NonNull Location location) {
        // 位置情報を受け取ったときに実行するカスタムコード。

    }
};
// 1000Lという値は一例です。A3LLocationRequestのintervalMillisには任意の値を使用できます。または、ほかのビルダー
// コンストラクターを使用することもできます。ほかのオプションについては、JavadocのAPIリファレンスを参照してください。
A3LLocationRequest a3lLocationRequest = new A3LLocationRequest.Builder(1000L).build();
// 別のルーパーを指定することもできます。looperがnullの場合、呼び出し元スレッドに関連付けられているルーパーが使用されます。
Task<Void> locationUpdates = a3LLocationProviderClient.requestLocationUpdates(a3lLocationRequest, a3lLocationListener, null);

位置情報の更新を停止する方法

リスナーへの位置情報の更新を停止するには、次のコードに示すように、removeLocationUpdates()メソッドを使用します。removeLocationUpdates()はA3lLocationListenerオブジェクトを受け取ります。

// 位置情報の更新を削除します。
Task<Void> removeLocationUpdatesTask = a3LLocationProviderClient.removeLocationUpdates(a3lLocationListener);

Last updated: 2023年9月13日