現在地を検索

マッピングアプリケーションを使用する主な理由の 1 つは、自分がどこにいるかを確認することです。

HERE SDK が提供するLocationEngineは、 GPS やその他のグローバル衛星ナビゲーションシステム（ GNSS ）受信機、モバイルネットワーク信号、 Wi-Fi ネットワーク信号などの複数の位置情報源と連携して正確な位置を判断する、包括的な位置情報ソリューションを実装しています。

Android デバイスでは、サブメーターの精度は、資格情報 が有効になっている場合にのみサポートされます ( 以下を参照 ) 。

必要な権限を追加

アプリでのLocationEngine の使用を開始する前に、アプリ AndroidManifest.xml のファイルに必要な権限を追加する必要があります。

...
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

このユーザー ガイドに付属 するすべてのサンプルアプリで、負担の大きいタスクを処理してユーザーの権限を要求するPermissionsRequestorという便利なクラスを使用しています。

GPS などのネイティブの位置情報サービスを使用するアプリは、ユーザーの許可を要求します。 すべてのデバイスが同じ機能を提供しているわけではありません。また、特定のハードウェアの制約があるため、結果が異なる可能性があります。

LocationEngineを使用する前に、ネイティブの位置情報サービスが有効になっているかどうかを確認することをお勧めします。 ほとんど の Android デバイスでは、ユーザーが位置情報サービスをオンにすることを選択できます。さらに、デバイスの [ 設定 ] を開き、 [ セキュリティと位置情報 ] セクションに移動することで、精度を上げることもできます。

情報収集の可否に関するユーザーの同意の処理

に LocationEngine は、 HERE SDK が使用する HERE サービスを改善するために、モバイル機器の周辺についての特定の情報を収集できる機能が含まれています。 そのような情報の例として、近くの Wi-Fi およびモバイルネットワークの信号の強度があります。

HERE SDK は ConsentEngine 、ユーザーがデータを収集することに同意したことを取得するためのフローを処理するを提供します。 さらに、現在のステータスを取得し、データを収集するかどうかを判断する前の決定を削除できます。 アプリケーションは、ユーザーがいつでもアクセスできるようにする必要があります。

LocationEngineを開始する前 に、前述の情報を収集するユーザーの同意が得られていることを確認する必要があります。 回答の内容に関係なく ( ユーザーがデータの収集を承諾したかどうかに関係なく ) 、承諾ダイアログが表示され、回答が提供されたことのみが該当します。 LocationEngineは、ユーザーの同意を得ずに開始しようとすると、LocationEngineStatus.USER_CONSENT_NOT_HANDLEDステータスを返します。

以下のコード スニペットは、 ConsentEngineのインスタンスを作成し、ユーザーの同意がすでに要求されているかどうかを確認します。要求されていない場合は、ユーザーに収集された情報の詳細を説明する UI ダイアログ ( 以下の図も参照 ) を呼び出します。 権限を付与または拒否することができます。

try {
    consentEngine = new ConsentEngine();
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization of ConsentEngine failed: " + e.getMessage());
}

// Check if user consent has been handled.
if (consentEngine.getUserConsentState() == Consent.UserReply.NOT_HANDLED) {

    // Show dialog.
    consentEngine.requestUserConsent();
}

// The execution can continue while the dialog is being shown.

マップ シーンのロード中は、requestUserConsent()を呼び出さないことをお勧めします。

このダイアログには、 HERE のプライバシープラクティスについて説明した Web ページへのリンクが含まれており、 37 言語をサポートしています。 表示されているダイアログは、デバイスの言語設定に従って表示されます。サポートされていない場合は、英語で表示されます。

ユーザーの応答は、アプリケーションの使用セッション間で保持され、メソッド getUserConsentState() を使用して取得できます。メソッドは 、次の値Consent.UserReply を返します。

switch(consentEngine.getUserConsentState()) {
    case GRANTED:
        //The user has previously given permission.
        consentStateTextView.setText(R.string.consent_state_granted);
        break;
    case DENIED:
        // The user has previously denied permission.
    case NOT_HANDLED:
        //The user has not been asked for consent.
    case REQUESTING:
        //The dialog is currently being shown to the user.
        consentStateTextView.setText(R.string.consent_state_denied);
        break;
    default:
        throw new RuntimeException("Unknown consent state.");
}

アプリケーションでは、メソッドgetUserConsentState() を呼び出して、ユーザーが以前に入力した応答を参照できるようにする必要があります。 上の図では、consentStateTextViewを使用して現在の状態を表示します。 また、 このアプリケーションでは、メソッドrequestUserConsent()を呼び出して承諾ダイアログを再度表示することで、いつでもユーザーが同意についての考え方を変更できるようにする必要があります。

requestUserConsent() が呼び出されると、 HERE SDK にダイアログを含む新しい Activity が表示されます。 ダイアログが閉じると、前のダイアログActivity が再開されます。 ダイアログを開く前にMapView が表示されている場合、MapView が再び表示されるまで一時停止されます。

承諾ダイアログのカスタマイズ

LocationEngineを使用するには、ユーザーの同意を要求する必要があります。 既定では、上記の API を使用してこの問題が発生します。

ダイアログの外観と内容をカスタマイズできます。 このためには、 HERE に、アプリケーション独自にカスタマイズしたユーザーの同意ダイアログを証明するよう依頼します。 証明書を受け取ると、アプリケーションは grantUserConsent() と denyUserConsent() のメソッドを使用して HERE SDK に対するユーザーの応答を伝達できます。HERE が、アプリケーションによってカスタムダイアログを開始できることを承認した場合、requestUserConsent() の呼び出しは不要になります。 通信したユーザーの応答は HERE SDK によって保持 getUserConsentState() され、メソッドを使用して以前に指定した応答を取得できます。

特定の事前要件の下で、別の方法で承諾の決定を要求または更新することも可能です。 たとえば、ユーザーがすでに外部の Web サイトで承諾を付与している場合です。 ただし、ソリューションについては、 HERE チームと個別に話し合う必要があります。

このオプションの詳細について確認 するか、または HERE の営業担当者またはヘルプページから HERE に連絡して認定プロセスを開始してください。

locationEngine の作成

LocationEngine の新規作成は簡単です。

try {
    locationEngine = new LocationEngine();
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization of LocationEngine failed: " + e.getMessage());
}

最後に確認した場所を取得

エンジンが初期化されると、少なくとも 1 回前にエンジンが始動し、少なくとも 1 つの位置を受信している限り、最後に確認された位置を取得できます。そうでない場合、null が返されます。 この情報は残ります。したがって、最後に確認された場所もアプリケーションセッション間で利用できます。

Location myLastLocation = locationEngine.getLastKnownLocation();

if (myLastLocation != null) {
    // Log the last known location coordinates.
    Log.d(TAG, "Last known location: " + myLastLocation.coordinates.latitude + ", " + myLastLocation.coordinates.longitude);
}

位置情報イベントに関する通知を受信

次に、LocationEngineを開始する前にLocationStatusListenerを登録して、エンジンのステータスの変更が通知されるようにすることをお勧めします。 そのためには LocationStatusListener 、インターフェイスを実装し、 Location Engine addLocationStatusListener() のメソッドに登録します。 さまざまなステータスの詳細については、 API リファレンス を確認してください。

private final LocationStatusListener locationStatusListener = new LocationStatusListener() {
    @Override
    public void onStatusChanged(@NonNull LocationEngineStatus locationEngineStatus) {
        Log.d(TAG, "LocationEngineStatus: " + locationEngineStatus.name());
    }

    @Override
    public void onFeaturesNotAvailable(@NonNull List<LocationFeature> features) {
        for (LocationFeature feature : features) {
            Log.d(TAG, "Feature not available: " + feature.name());
        }
    }
};

// ...

// Add the listener.
locationEngine.addLocationStatusListener(locationStatusListener);

また、リスナー onFeaturesNotAvailable() のコールバック を通じて 、利用できないものLocationFeature があれば通知されます。 必要な機能が利用できない場合は、HERE の担当者にご連絡ください。 注 : LocationFeature 列挙型 (enum) は現在保留中の機能です。

エンジンを始動する前に考慮すべき最後の作業は、LocationListenerを登録することです。これにより、新しいLocationが検出されたときに通知を送信するonLocationUpdated()コールバックが提供されます。 これは、前述のLocationStatusListenerと同様の方法で行うことができます。

private final LocationListener locationListener = new LocationListener() {
    @Override
    public void onLocationUpdated(@NonNull Location location) {
        Log.d(TAG, "Received location: " + location.coordinates.latitude + ", " + location.coordinates.longitude);
    }
};

// ...

// Add the listener.
locationEngine.addLocationListener(locationListener);

現在の地理座標とは別に Location 、インスタンスには現在の高度、方位、速度、精度など、より役立つ情報が多数含まれている場合があります。 詳細については、以下の「場所からのアクセス精度情報」セクションを参照してください。

それぞれのaddLocationStatusListener()メソッドおよびaddLocationListener()メソッドを呼び出して、必要なだけLocationStatusListenerおよびLocationListenerを追加できます。

受信地点の開始および停止

LocationEngineの start() メソッドを呼び出す準備ができました。

try {
    consentEngine = new ConsentEngine();
    locationEngine = new LocationEngine();
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization failed: " + e.getMessage());
}

if (consentEngine.getUserConsentState() == Consent.UserReply.NOT_HANDLED) {
    consentEngine.requestUserConsent();
}

// ...

startLocating();

// ...

private void startLocating() {
    locationEngine.addLocationStatusListener(locationStatusListener);
    locationEngine.addLocationListener(locationListener);
    locationEngine.start(LocationAccuracy.BEST_AVAILABLE);
}

エンジンを始動する最も簡単な方法は、上記のコード スニペットのように、定義済みのモードの 1 つLocationAccuracyを渡すことです。 使用可能なすべてのモードの詳細については、次の表を参照するか、 API リファレンス を確認してください。

LocationEngineが開始された後、最初にstop()をコールしないで、再度開始しようとすると、LocationEngineStatus.ALREADY_STARTEDが届きます。 このメソッドisStarted() を使用して、エンジンが始動しているかどうかを確認できます。 同様に、LocationEngineを開始し、最初のを停止せずに別のを開始しようとすると、LocationEngineStatus.ALREADY_STARTEDエラーが発生します。 一度に始動できるエンジンは 1 つだけです。

位置情報の更新をこれ以上受信したくない場合 stop() は、メソッドを呼び出してエンジンを停止できます。 不要になったリスナーは必ず削除してください。

public void stopLocating() {
    locationEngine.stop();
}

// ...

locationEngine.removeLocationListener(locationListener);
locationEngine.removeLocationStatusListener(locationStatusListener);

一般 に、アプリが廃棄された場合は、LocationEngine を停止することをお勧めします。

バックグラウンド更新を有効化

Android 10 （ API レベル 29 ）以上をターゲットにしており、アプリがバックグラウンドで実行されている間も位置情報の更新を引き続き受信する場合は AndroidManifest.xml 、アプリのファイルに次の権限を追加して、この機能を有効にする必要があります。

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Android 14 以降をサポートする FOREGROUND_SERVICE_LOCATION には、権限も必要です。

さらに、 Android API レベル 29 以上でアプリケーションをバックグラウンドで実行し続ける場合は、フォアグラウンドサービスまたは類似のサービスを開始する必要があります。 バックグラウンド位置のリクエストは、フォアグラウンド位置の権限のリクエストとは異なることに注意してください。 詳細については、Android のドキュメントを参照してください。 バックグラウンドで更新されたポジショニングアプリの例を参照することもできます。アプリ には、フォアグラウンドサービスの使用方法と、バックグラウンドで位置情報の更新を取得する方法が示されています。

さらに、ユーザーに自動化のリクエストが必要です。 [ 必要な権限を追加 ] セクションで、ユーザーに権限を要求する方法についての提案を確認します。

バックグラウンドで位置情報が更新されたことを示す完全な作業フローは 、 GitHub にある PositioningWithBackgroundUpdates サンプルアプリ で確認できます。 フォアグラウンドサービスを設定するために必要な手順の概要については、このチュートリアルを参照してください。

場所のオプションを指定

場所の生成時に考慮するオプションをより詳細に制御する場合は、 LocationOptionsは、オブジェクトを作成し、好みに合わせて設定して、そのオブジェクトを使用してエンジンを開始できます。

// ...

// Create a new LocationOptions object. By default all options are enabled.
LocationOptions locationOptions = new LocationOptions();

// Use WiFi and satellite (GNSS) positioning only.
locationOptions.wifiPositioningOptions.enabled = true
locationOptions.satellitePositioningOptions.enabled = true
locationOptions.sensorOptions.enabled = false;
locationOptions.cellularPositioningOptions.enabled = false

// Receive a location approximately every minute, but not more often than every 30 seconds.
locationOptions.notificationOptions.smallestIntervalMilliseconds = TimeUnit.SECONDS.toMillis(30);
locationOptions.notificationOptions.desiredIntervalMilliseconds = TimeUnit.SECONDS.toMillis(60);

locationEngine.start(locationOptions);

// ...

次の表に、使用可能 なモードLocationAccuracy の概要と、それらのモードの LocationOptionsへの内部変換方法を示します。

サブメーターナビゲーション

LocationEngine with LocationAccuracy.SUB_METER_NAVIGATION モードを開始すると、 HERE HD GNSS Positioning が有効になります。 HD GNSS（高解像度グローバルナビゲーション衛星システム）機能を使用すると、レーンアシスタンス、ターンバイターンガイダンス、拡張現実など、さまざまな用途に高解像度のポジショニングを行うことができます。 HD GNSS はクラウドベースのソリューションで、マスマーケットのデバイスが世界中でサブメーターの精度を達成できるようにします。

HD GNSS には、使用されている Android デバイスに特別な要件があります。 この機能が動作するには、 Android バージョンのデバイスが 12 （ API 31 ）以上である必要があります。 具体的には、デバイスが以下をサポートしている必要があります。

• 生の GNSS 測定値
• GNSS キャリア位相測定（ ADR ）
• デュアル周波数 GNSS 受信機（ L5 ）

詳細については、Android のドキュメントも参照してください。

使用しているデバイスで上記の条件が満たされていることを確認する責任はユーザーにあります。 そうでない場合は、目的の精度レベルに達していない可能性があります。

上記の条件は、古いバージョンの一部の Android デバイスでも保持されます。 LocationAccuracy.SUB_METER_NAVIGATION これらのバージョンの一部ではモードを正常に使用できますが、この操作は開発およびテストの目的でのみ行う必要があります。

この機能はデフォルトでは使用できませんが、個別にアクティブ化する必要があります。 HERE HD GNSS 補正データにアクセスするには、資格情報 が必要です。 詳細については、HEREにお問い合わせください。

位置情報から精度情報にアクセス

座標とタイムスタンプを除き、他のすべてのフィールド Location は、オプションです。 たとえば、受信 Location したオブジェクトには、ベアリング角度および現在の速度に関する情報が含まれている場合がありますが、この情報は利用できないことが保証されています。 使用できない値は、 nullとして返されます。 ポジショニングに使用されるソースの種類 LocationOptions( 上記で定義 ) およびデバイスの機能によって、利用可能なフィールドが異なります。

if (location.speedInMetersPerSecond != null) {
    Log.d(TAG, "Speed (m/s): " + location.speedInMetersPerSecond);
} else {
    Log.d(TAG, "Speed (m/s): Not available");
}

Locationオブジェクト内に存在する horizontalAccuracyInMetersフィールドは、「不確実性の半径」とも呼ばれ、68% の確率で真の地理座標が存在する可能性が高いエリアの推定値を提供します。これは、現在の位置の周囲にハローインジケータを描画するために使用されます。 下の図は、内側の緑色の円location.coordinatesに 、周囲の円を半径の精度の円horizontalAccuracyInMetersとして示し ています。 正確な地理座標は、精度円の内側（68%）または外側（32%）にあります。

同様に、高度の場合、 verticalAccuracyInMeters 値が10メートルの場合、実際の高度は 、 68%の確率で、高度-10mから高度+10mの範囲内にあると予想されます。 bearingAccuracyInDegrees およびspeedAccuracyInMetersPerSecondなどの他の精度値も同じ規則に従います。不確実性が小さいほど精度が向上します。

68% を超える確率で達成 (CEP68)

68% の確率 (CEP68) では不十分な場合、 99% の精度を達成できますか ? はい、次のとおりです。 与えられた円形誤差確率 (CEP) は自由度が 2 つのカイ （χ）２乗分布に続くため、次の式に基づいて望ましい確率を簡単に計算できます。

上の表を使用して、マップ上のハローインジケータのさまざまな確率レベルを表示できます。 たとえば、水平方向の精度が 20 メートルの場合、半径のほぼ 2 倍の確率で 99 ％を達成できます。 精度値は常に CEP68 として指定されます。つまり、次のことを意味します。

CEP99 = 2.01 x CEP68 = 2.01 x 20m = 40.2m

発見された場所の周囲に 40.2 メートルの半径を描画できるようになり ました。確率は 99% で、実際の場所はその円の内側にあります。 一方、半径 0 メートルの確率は 0% です。

法的要件

HERE SDK の位置情報機能を使用するには、前述のように、アプリケーションで HERE SDK の同意ダイアログを表示する必要があります。 ユーザーは、現在の承諾の決定を参照し、以前の承諾の決定を取り消すことができる必要があります。そうしないと、 HERE SDK の位置情報機能を使用できなくなり、代わりに Android の位置情報 API を参照する必要があります。

チュートリアル : 現在地を地図に表示

LocationIndicatorは 、マップ上のデバイスの現在位置を表すために使用されます。 インジケータが現在の位置の値で更新される前に、デフォルト Location が設定されます。デフォルトは、最後に確認された場所、または最初の位置更新が到着する前にユーザが表示する必要がある場所です。 デフォルトでは、水平精度は半径horizontalAccuracyInMetersのMapCircle で表示されます。

//LocationIndicator object to represent current location.
private LocationIndicator locationIndicator;

// ...

private void addMyLocationToMap(@NonNull Location myLocation) {
    //Create and setup location indicator.
    locationIndicator = new LocationIndicator();
    // Enable a halo to indicate the horizontal accuracy.
    locationIndicator.setAccuracyVisualized(true);
    locationIndicator.setLocationIndicatorStyle(LocationIndicator.IndicatorStyle.PEDESTRIAN);
    locationIndicator.updateLocation(myLocation);
    locationIndicator.enable(mapView);
    //Update the map viewport to be centered on the location.
    MapMeasure mapMeasureZoom = new MapMeasure(MapMeasure.Kind.DISTANCE, CAMERA_DISTANCE_IN_METERS);
    mapView.getCamera().lookAt(myLocation.coordinates, mapMeasureZoom);
}


// ...

private void updateMyLocationOnMap(@NonNull Location myLocation) {
    //Update the location indicator's location.
    locationIndicator.updateLocation(myLocation);
    //Update the map viewport to be centered on the location, preserving zoom level.
    mapView.getCamera().lookAt(myLocation.coordinates);
}

// ...

//Default start-up location.
private final static GeoCoordinates defaultLocation = new GeoCoordinates(52.520798, 13.409408);

final Location myLastLocation = locationEngine.getLastKnownLocation();

if (myLastLocation != null) {
    addMyLocationToMap(myLastLocation);
} else {
    final Location defaultLocation = new Location(defaultCoordinates);
    defaultLocation.time = new Date();
    addMyLocationToMap(defaultLocation);
}

// ...

private final LocationListener locationListener = location -> {
    updateMyLocationOnMap(location);
};

上記の実装に示されているように、updateLocation()を呼び出して、Locationオブジェクトを位置情報インジケータに渡すことができます。 この例では、ユーザーの現在の位置を追跡することを目的としています。そのため、マップビューポートの中心位置も更新されます。