ガイド変更履歴HERE SDK API references
ガイド

データとOTAコストを管理する

データとOTAコストの管理は、Navigateライセンスでのみ使用できます。

このガイドでは、HERE SDKのサイズを縮小し、読み込みまたは処理が必要なデータ量を最小限に抑えることで、ランタイムパフォーマンスを強化する戦略について説明します。

OCMレイヤーをデータ負荷を最小限に抑えるように設定する

レイヤー構成を設定するには、機能項目のリストを指定する必要があります。このリストの機能のみが有効になり、その他の機能はすべて無効になります。1つの機能を無効にするには、他のすべての必要な機能がリストに含まれていることを確認します。そうしないと、それらの機能が自動的に無効になります。

HERE SDK のいくつかの機能は、OCM マップ データ形式 (最適化されたクライアント マップ) で保存されます。

LayerConfiguration を利用して、次を制御できます。

  • MapViewのオンラインパン中にキャッシュに読み込まれるマップデータの量。
  • オフラインでの使用で、新しい Region を追加するときにダウンロードされるデータ量。

たとえば、ターン・バイ・ターンナビがアプリケーション内で使用されていない場合、対応する機能の設定 NAVIGATION を省略できます。この調整により、MapView のパン中にキャッシュにダウンロードされるデータが少なくなります。また、新しい Region を追加するときにダウンロードされたデータのサイズが大幅に削減されます。

現在、以下の機能を指定できます。この表にはデフォルトで有効になっている機能も掲載されています。

フィーチャー 有効 説明
DETAIL_RENDERING はい 建物などの追加のレンダリングの詳細。マップビューでのみ使用されます。設定されていない場合、オフライン地域をダウンロードするときや、そのようなデータを含む領域をプリフェッチするときに、このデータは除外されます。ただし、オンラインで使用している間は、このデータがキャッシュにダウンロードされて表示される場合があります。
NAVIGATION はい ナビゲーション中に地図照合に使用されるマップ データ。設定されていない場合、オンラインまたはオフラインでの使用時にナビゲーションが正しく動作しない可能性があります。
OFFLINE_SEARCH はい 検索に使用されるマップ データ。設定されていない場合、OfflineSearchEngineの使用時に正しく動作しない可能性があります。
OFFLINE_SEARCH_GLOBAL いいえオフライン検索用のマップデータを改善し、パフォーマンスとメモリフットプリントを向上させます。検索範囲を拡張し、検索の中心の外にある場所も検索できるようにします。この機能を使用する場合は、不要なレイヤーのダウンロードを避けるため、offlineSearchを無効にすることを推奨します。現時点では、インストール済みのリージョンのみサポートされます。キャッシュまたはプリフェッチ済みのマップデータは、現時点ではサポートされません。
OFFLINE_ROUTING はい ルートの計算に使用されるマップ データ。設定されていない場合、OfflineRoutingEngine を の使用時に正しく動作しない可能性があります。
TRUCK はい トラック ルートの計算に使用されるマップ データ。設定されていない場合、OfflineRoutingEngine をトラックのルート計算に使用するときに正しく動作しない可能性があります。トラック ナビゲーション時の地図照合にも使用されます。設定されていない場合、オフラインでの使用時にトラック ナビゲーションが正しく動作しない可能性があります。デバイスがオンライン接続されている場合でも、オンライン トラック ナビゲーションは引き続き機能します。
LANDMARKS_3D はい テクスチャ付きの3Dランドマークをレンダリングするために使用されるマップデータ。設定されていない場合、オフライン地域をダウンロードするときや、そのようなデータを含む領域をプリフェッチするときに、このデータは除外されます。LANDMARKS レイヤーが MapScene に表示されるように設定されている場合、3D ランドマークはオンラインで使用されている間も表示されます。
JUNCTION_VIEW_3X4JUNCTION_VIEW_16X9 いいえ 複雑な合流地点の 3D ビジュアル。このアセット データは、ガイダンス中に SVG 画像を表示するために使用できます。有効にすると、ダウンロードされた地域には、対応する JunctionViewWarning イベントで使用されるジャンクション ビューの画像が含まれます。この機能は、旅行を開始する前にアセットをダウンロードするのに役立つ可能性があります。有効にしない場合、必要なデータが必要なときにダウンロードされます。各画像は最大 15 MB を占有する可能性があります。HERE SDK の今後のリリースでは、リアリズムのレベルを下げることによってサイズが最適化されます。デフォルトでは、このレイヤーは有効になっていません。
JUNCTION_SIGN_3X4JUNCTION_SIGN_4X3JUNCTION_SIGN_3X5JUNCTION_SIGN_5X3JUNCTION_SIGN_16X9 いいえ 標識のビジュアル。このアセット データは、ガイダンス中に SVG 画像を表示するために使用できます。有効にすると、ダウンロードされた地域には、対応する SignpostWarning イベントで使用される合流地点ビューの画像が含まれます。有効にしない場合、必要なデータが必要なときにダウンロードされます。各画像は最大 300 KB を占有する可能性があります。有効にしない場合、必要なデータが必要なときにダウンロードされます。デフォルトでは、このレイヤーは有効になっていません。
RENDERING はい Carto POI などの基本的なレンダリング機能のセット。ベース レイヤーのため、この機能は無効にできません。
RDS_TRAFFIC いいえ RDS-TMC 形式を使用してトラフィック ブロードキャスト機能を提供するマップ データ。インターネット接続がないときに使用し、ルート検索モジュールが無線チャネル経由で受信するトラフィックデータを利用して、OfflineRoutingEngineでルートを作成できるようにします。
EV いいえ EV充電ステーションのオフラインマップデータ。
TRUCK_SERVICE_ATTRIBUTES いいえ トラック関連の属性が OfflineSearchEngine によって返されるようにします。
FUEL_STATION_ATTRIBUTES いいえ 燃料属性が OfflineSearchEngine によって返されるようにします。
OFFLINE_BUS_ROUTING いいえ バス ルートの計算に使用されるマップ データ。設定されていない場合、OfflineRoutingEngineBusOptions を使用してルートを計算できない可能性があります。
TERRAIN いいえ 地形データを表すために使用されるマップ データ。

掲載されている各機能は 1 つ以上の OCM レイヤー グループに関連しています。OCM レイヤー グループの名前は、API リファレンスで機能ごとに確認できます。ただし、ほとんどのユースケースでは、関連するOCMレイヤー名を知らなくても問題ありません。

また、ADASEHORIZON (Electronic Horizon) という2つのレイヤーがありますが、これらは現時点ではHERE SDKでの使用に関連していないため、今のところ無視できます。デフォルトでは、これらはすでに無効になっています。

Regionが初めてダウンロードまたはキャッシュに保存されたときに、グローバルに設定されたLayerConfigurationのみが使用されます。すでにダウンロードされているリージョンのLayerConfigurationを更新するには、リージョンを削除してから再ダウンロードするか、MapUpdaterを再度初期化してmapUpdater.updateCatalog(..)を呼び出します。

機能が無効になっている場合、その機能に必要なデータはキャッシュ内やRegionダウンロードの一部としてスペースを占有していません。この機能はオフラインでは使用できません。場合によっては、エラーが発生することがあります。たとえば、OFFLINE_SEARCHが無効になっているにもかかわらず、OfflineSearchEngineを使用しようとした場合などです。詳細については、以下を参照してください。

SearchEngineRoutingEngine などのエンジンは、キャッシュに保存されたマップ データやダウンロードされたマップ データを利用しません。OfflineSearchEngineOfflineRoutingEngineは、関連する機能が無効になっていない場合にのみ、そのようなデータを使用します。たとえば、アプリがオンラインで完全に動作することが確実であれば、オフライン検索機能を無効にしても問題ありません。ただし、一時的な接続切断時にもアプリで POI (施設情報) を検索できるようにする場合、そのような切断が検出されたときに OfflineSearchEngine に切り替えることができます。そのためには、関連する機能を無効にしないようにします。

上記のように、無効にした機能の一部については、デバイスがオンライン接続されており、その機能が必要な場合、対応するデータをデバイスがダウンロードすることがあります。たとえば、「Landmarks_3D」機能が無効でも、対応する MapScene レイヤーが有効であれば、3D ランドマークが MapView ビューポートに表示されるときに、デバイスはそれをレンダリングするために必要なテクスチャをダウンロードします。

上記の OFFLINE_SEARCHOFFLINE_ROUTING を除くすべての機能について、HERE SDK はまず必要なデータがキャッシュにあるかどうかを確認します。キャッシュにない場合は、オフラインで使用するためにダウンロードされた Region があるかどうかを調べます。見つからない場合、HERE SDK は必要なデータを Over The Air (OTA) でダウンロードしようとします。OFFLINE_SEARCHOFFLINE_ROUTING については動作は同じですが、データが Over The Air (OTA) でリクエストされることはありません。

LayerConfiguration を設定する

最初に、目的のレイヤー設定を指定します。

// With this layer configuration we enable only the listed layers.
// All the other layers including the default layers will be disabled.
ArrayList<LayerConfiguration.Feature> features = new ArrayList<>();
features.add(LayerConfiguration.Feature.DETAIL_RENDERING);
features.add(LayerConfiguration.Feature.RENDERING);
features.add(LayerConfiguration.Feature.OFFLINE_SEARCH);
LayerConfiguration layerConfiguration = new LayerConfiguration();
layerConfiguration.enabledFeatures = features;
// With this layer configuration we enable only the listed layers.
// All the other layers including the default layers will be disabled.
val features = ArrayList<LayerConfiguration.Feature>()
features.add(LayerConfiguration.Feature.DETAIL_RENDERING)
features.add(LayerConfiguration.Feature.RENDERING)
features.add(LayerConfiguration.Feature.OFFLINE_SEARCH)
val layerConfiguration = LayerConfiguration()
layerConfiguration.enabledFeatures = features

作成したlayerConfigurationオブジェクトをSDKOptionsに設定し、通常どおりHERE SDKを初期化します。

AuthenticationMode authenticationMode = AuthenticationMode.withKeySecret(accessKeyID, accessKeySecret);
SDKOptions options = new SDKOptions(authenticationMode);
options.layerConfiguration = layerConfiguration;
// Now use this SDKOptions for initializing a new SDKNativeEngine instance.
val authenticationMode = AuthenticationMode.withKeySecret(
    accessKeyID, accessKeySecret
)
val options = SDKOptions(authenticationMode)
options.layerConfiguration = layerConfiguration
// Now use this SDKOptions for initializing a new SDKNativeEngine instance.

レイヤー設定を更新する

レイヤー設定は新しい SDKOptions を設定して SdkNativeEngine の新しいインスタンスを作成することでいつでも更新できます。

mapUpdater.retrieveCatalogsUpdateInfo(..)を呼び出して、新しいバージョンが利用可能なすべてのカタログのリストをクエリします。これにより、新しいLayerConfigurationが適用され、以前のものが上書きされます。次に、すべてのカタログのリストから、それぞれのCatalogUpdateInfoを使用してmapUpdater.updateCatalog(catalogUpdateInfo, CatalogUpdateProgressListener())を介して地図の更新を実行します。次に、MapViewを使用している場合は、SdkNativeEngineMapViewなどのすべてのエンジンを再初期化する必要もあります。

mapUpdater.updateCatalog(..)を呼び出してもリージョンがダウンロードされていない場合、このメソッドはマップキャッシュのみを更新します。利用可能な更新がない場合は、MapUpdateProgressListener.onComplete()コールバックが即座に呼び出され、MapLoaderErrorが返されます。マップデータキャッシュはLRU (Least Recently Used) の削除ポリシーに準拠するため、更新は新たにダウンロードされたデータのみに適用され、キャッシュ済みの既存データには遡って適用されません。キャッシュを即座に無効化するには、手動でキャッシュをクリアします。そうしないと、たとえば OfflineSearchEngine を使用している場合などに、古いキャッシュ データが引き続き HERE SDK にアクセスされる可能性があります。

変更されたLayerConfigurationを適用するには、地図更新の確認に使用するコードと同じコードを使用することをお勧めします。ただし、新しいMapUpdaterインスタンスでそのコードを実行してください。checkForMapUpdates()の実装例は、「地図の更新」ガイドに記載されています。

更新の実行タイミングを決めるのは開発者です。「正規化」とも呼ばれる非同期更新プロセスは、インストールされているリージョンの数によっては時間がかかる場合があります。

MapView使用時にレイヤー設定を更新する

MapViewを表示中に、レイヤー設定を実行時に有効または無効にするには、mapUpdater.updateCatalog(..)を呼び出すだけでは不十分です。SdkNativeEngineMapViewを含むすべてのエンジンを再初期化する必要があります。

例:

  1. HERE SDKの再初期化から開始し、新しいレイヤー設定を行います。
try {
    AuthenticationMode authenticationMode = AuthenticationMode.withKeySecret(accessKeyID, accessKeySecret);
    SDKOptions options = new SDKOptions(authenticationMode);
    options.layerConfiguration = layerConfiguration;
    // Invoking makeSharedInstance will invalidate any existing references to the previous instance of SDKNativeEngine.
    // It will also destroy the previous SDKNativeEngine.
    SDKNativeEngine.makeSharedInstance(context, options);
    // Update the current MapView instance to recreate the rendering surface that was invalidated by the invocation of makeSharedInstance.
    updateMapView(savedInstanceState);
    // Reinitialize the map updater and perform feature update internally to "normalize" the new layer configuration.
    // Normalization, in this context, is the process of aligning the currently downloaded layer group configuration in the map data with the requested one.
    // Layer groups that are not in the requested layer configuration are removed and layer groups that were added to the requested configuration are downloaded.
    initMapUpdater(SDKNativeEngine.getSharedInstance());

    // Reinitialize other necessary engines as required.

} catch (InstantiationErrorException e) {
    throw new RuntimeException("Reinitialization failed: " + e.error.name());
} catch (Exception e) {
    e.printStackTrace();
}
try {
    val authenticationMode = AuthenticationMode.withKeySecret(
        accessKeyID, accessKeySecret
    )
    val options = SDKOptions(authenticationMode)
    options.layerConfiguration = layerConfiguration

    // Invoking makeSharedInstance will invalidate any existing references to the previous instance of SDKNativeEngine.
    // It will also destroy the previous SDKNativeEngine.
    SDKNativeEngine.makeSharedInstance(context, options)

    // Update the current MapView instance to recreate the rendering surface that was invalidated by the invocation of makeSharedInstance.
    updateMapView(savedInstanceState)

    // Reinitialize the map updater and perform feature update internally to "normalize" the new layer configuration.
    // Normalization, in this context, is the process of aligning the currently downloaded layer group configuration in the map data with the requested one.
    // Layer groups that are not in the requested layer configuration are removed and layer groups that were added to the requested configuration are downloaded.
    initMapUpdater(SDKNativeEngine.getSharedInstance())

    // Reinitialize other necessary engines as required.

} catch (e: InstantiationErrorException) {
    throw RuntimeException("ReInitialization of HERE SDK failed: " + e.error.name)
} catch (e: Exception) {
    e.printStackTrace()
}
  1. 現在のMapViewインスタンスを更新して、makeSharedInstance()の呼び出しによって無効化されたレンダリングサーフェスを再作成します。
private void updateMapView(Bundle savedInstanceState) {
    // Needs to be called after recreation of SDKNativeEngine, even when savedInstanceState is null.
    // Otherwise, the map view will keep using the previous SDKNativeEngine instance.
    mapView.onCreate(savedInstanceState);
    // Since mapview.onCreate() results in a new rendering surface, the map scene must be reloaded to ensure proper rendering.
    mapView.getMapScene().loadScene(MapScheme.NORMAL_DAY, new MapScene.LoadSceneCallback() {
        @Override
        public void onLoadScene(@Nullable MapError mapError) {
            ...
        }
    });
}
private fun updateMapView(savedInstanceState: Bundle?) {
    // Needs to be called after recreation of SDKNativeEngine, even when savedInstanceState is null.
    // Otherwise, the map view will keep using the previous SDKNativeEngine instance.
    mapView.onCreate(savedInstanceState)

    // Since mapview.onCreate() results in a new rendering surface, the map scene must be reloaded to ensure proper rendering.
    mapView.mapScene.loadScene(
        MapScheme.NORMAL_DAY
    ) { mapError ->
        ....
    }
}
  1. MapUpdaterを再初期化し、カタログを更新するために使用します。
private void initMapUpdater(SDKNativeEngine sdkNativeEngine) {
    MapUpdater.fromEngineAsync(sdkNativeEngine, new MapUpdaterConstructionCallback() {
        @Override
        public void onMapUpdaterConstructe(@NonNull MapUpdater mapUpdater) {
            OfflineMapsExample.this.mapUpdater = mapUpdater;
            // Checks and updates in cases of map feature configuration changes.
            // Perform the map update ...
        }
    });
}
private fun initMapUpdater(sdkNativeEngine: SDKNativeEngine) {
    MapUpdater.fromEngineAsync(sdkNativeEngine, object : MapUpdaterConstructionCallback {
        override fun onMapUpdaterConstructe(mapUpdater: MapUpdater) {
            [email protected] = mapUpdater
            // Checks and updates in cases of map feature configuration changes.
            // Perform the map update ...
        }
    })
}

LayerConfigurationの更新とマップデータの更新を実装する例については、GitHubで提供されているJava版およびKotlin版のOfflineMapsサンプルアプリを参照してください。

オンライン使用時の暗黙的なプリフェッチ機能

layerConfiguration.enabledFeaturesの他に、layerConfiguration.implicitlyPrefetchedFeaturesを設定することもできます。

  • enabledFeaturesは、オフラインで使用するリージョンをダウンロードするときに、リストのレイヤーをすべて有効にします。
  • implicitlyPrefetchedFeaturesは、たとえばオンライン使用中にMapViewをパンするときなど、マップコンテンツをマップキャッシュにダウンロードする場合に、リスト内のすべてのレイヤーを有効にします。

デフォルトでは、暗黙的なプリフェッチに対して次の機能が有効になっています。

  • DETAIL_RENDERING
  • NAVIGATION
  • OFFLINE_SEARCH
  • OFFLINE_ROUTING
  • RENDERING
  • TRUCK

暗黙的なプリフェッチをカスタマイズするには、LayerConfigurationimplicitlyPrefetchedFeaturesフィールドを使用します。

以下に、オンライン使用とオフライン使用の両方で同じ機能を設定する方法を示します。

ArrayList<LayerConfiguration.Feature> features = new ArrayList<>();
features.add(LayerConfiguration.Feature.DETAIL_RENDERING);
features.add(LayerConfiguration.Feature.RENDERING);
features.add(LayerConfiguration.Feature.OFFLINE_SEARCH);
LayerConfiguration layerConfiguration = new LayerConfiguration();
layerConfiguration.enabledFeatures = features;
layerConfiguration.implicitlyPrefetchedFeatures = features;
// With this layer configuration we enable only the listed layers.
// All the other layers including the default layers will be disabled.
val features = ArrayList<LayerConfiguration.Feature>()
features.add(LayerConfiguration.Feature.DETAIL_RENDERING)
features.add(LayerConfiguration.Feature.RENDERING)
features.add(LayerConfiguration.Feature.OFFLINE_SEARCH)
val layerConfiguration = LayerConfiguration()
layerConfiguration.enabledFeatures = features
layerConfiguration.implicitlyPrefetchedFeatures = features

LayerConfigurationの設定時に、同じ機能のリストをenabledFeaturesおよびimplicitlyPrefetchedFeaturesの両方に割り当てることで、オンライン使用とオフライン使用の両方で同じ機能セットを有効にできます。これにより、アプリケーションがオンラインで動作しているかオフラインで動作しているかに関係なく、利用可能な機能の一貫性が確保されます。

implicitlyPrefetchedFeaturesを無効にするには、空のリストをlayerConfiguration.implicitlyPrefetchedFeaturesに割り当てます。特定の機能に対して暗黙的なプリフェッチを無効にすると、ネットワーク消費を削減できますが、オフライン機能が制限される場合があります。すでにダウンロードされているキャッシュ済みのマップデータは、すぐには削除されません。

次に、implicitlyPrefetchedFeaturesを設定する方法の例をいくつか示します。

  • オンライン操作中にネットワーク使用量を最小限に抑えることが主な目的である場合は、空のリストをlayerConfiguration.implicitlyPrefetchedFeaturesに設定します。これにより、MapViewをパンまたは操作するときに必要最小限のマップデータのみがダウンロードされるようになります。トレードオフとして、キャッシュ内のデータが少なくなるため、必要なリージョンがインストールされていない限り、オフライン機能を使用できなくなります。

  • アプリケーションでオフラインルーティングが必要でも、どのリージョンを事前にダウンロードすべきかわからない場合は、OFFLINE_ROUTINGの暗黙的な機能のみを有効にします。これは、オンラインモードで地図をパン操作する際にダウンロードされるデータ量を削減しますが、キャッシュに保存されたデータに対し、OfflineRoutingEngineを使用することも試みることができます。十分なデータがキャッシュに保存されているという保証はないことに注意してください。十分なデータがあることを確認する場合は、必要なリージョンをインストールすることをお勧めします。

  • アプリケーションが無線封止の状態でオフラインルーティングを必要とする場合は、前述したとおり、OFFLINE_ROUTINGの暗黙的な機能のみを有効にし、さらにそれをSDKNativeEngineを介してPassThroughFeatureとして設定します。


EN 日本語

HERE documentation

Find answers to your product and technical questions

Documentation

What's new

Videos

EN 日本語

HERE ドキュメント

製品や技術に関する質問の答えを見つけましょう。より多くの内容と最新の情報については、英語版をご覧ください。

ドキュメント

ダイナミックマップ

動的コンテンツ関連のAPIをアプリやサービスに活用して、ドライバーが安全・快適かつ予定どおりに目的地へ到着できるよう支援します。

地図とデータ

世界中を走行する多数のマッピング車両から得られる最新の位置情報データを活用し、精度の高い地図やカスタムレイヤーを構築できます。

最新情報

動画

(function () { const input = document.querySelector('input[data-typeahead]'); if (!input) return; // Prevent the form from submitting/navigating input.closest('form')?.addEventListener('submit', e => e.preventDefault()); input.addEventListener('input', function () { const q = this.value.trim().toLowerCase(); document.querySelectorAll('.nav-group-name').forEach(group => { let anyVisible = false; group.querySelectorAll('.nav-group-task').forEach(task => { const text = task.textContent.trim().toLowerCase(); const show = !q || text.includes(q); task.style.display = show ? '' : 'none'; if (show) anyVisible = true; }); // Hide the whole group header if nothing matches group.style.display = anyVisible || !q ? '' : 'none'; }); }); })(); (function () { function onTokenClick(event) { var link = event.target.closest('.sdk-for-ios .item .token'); if (!link) return; event.preventDefault(); console.log('token clicked', link.textContent.trim()); var item = link.closest('.item'); if (!item) return; var content = item.querySelector('.height-container'); if (!content) { console.log('no .height-container found for item', item); return; } var isHidden = window.getComputedStyle(content).display === 'none'; content.style.display = isHidden ? 'block' : 'none'; link.classList.toggle('token-open', isHidden); var href = link.getAttribute('href'); if (href) { if (history.pushState) history.pushState({}, '', href); else location.hash = href; } } function openHashTarget() { var hash = window.location.hash.slice(1); if (!hash) return; var anchor = document.querySelector('.sdk-for-ios a[name="' + hash + '"]'); if (!anchor) return; var item = anchor.closest('.item'); if (!item) return; var link = item.querySelector('.token'); var content = item.querySelector('.height-container'); if (!link || !content) return; content.style.display = 'block'; link.classList.add('token-open'); } function init() { console.log('HERE SDK accordion init'); openHashTarget(); } document.removeEventListener('click', onTokenClick); document.addEventListener('click', onTokenClick); if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', init); } else { init(); } window.addEventListener('hashchange', openHashTarget); window.addEventListener('pageLoad', init); })();