一般的な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日