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

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

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

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

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

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

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

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

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

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

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

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

LayerConfiguration の設定では、SDKOptions.layerConfiguration を使った Feature 項目のリストの特定が必要です。このリストの機能のみが有効になり、その他の機能はすべて無効になります。1 つの機能を無効にする場合は、他のすべての必要な機能がリストに含まれていることを確認します。そうしないと、それらの機能が自動的に無効になります。

たとえば、機能リストに navigation と TRUCK が含まれている場合、ナビゲーションとトラック機能のみが有効になり、その他の機能はすべて無効になります。

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

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

注

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

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

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

LayerConfiguration を設定する

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

var features: [LayerConfiguration.Feature] = []
// With this layer configuration we enable only the listed layers.
// All the other layers including the default layers will be disabled.
features = [.detailRendering, .rendering, .offlineSearch]

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

options.layerConfiguration = LayerConfiguration(enabledFeatures: features)
// Now use this SDKOptions for initializing a new SDKNativeEngine instance.

レイヤー設定を更新する

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

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

注

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

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

更新の実行タイミングを決めるのは開発者です。「正規化」とも呼ばれる非同期更新プロセスは、インストールされているリージョンの数によっては時間がかかる場合があります。HERE SDK がこうした更新の実施時期を決定したり、通知したりすることはありません。開発者によって機能設定が変更されていない場合、これを呼び出す必要はありません。

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

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

1. HERE SDKの再初期化から開始し、新しいレイヤー設定を行います。

let authenticationMode = AuthenticationMode.withKeySecret(accessKeyId: accessKeyID, accessKeySecret: accessKeySecret)
var options = SDKOptions(authenticationMode: authenticationMode)
options.layerConfiguration = LayerConfiguration(enabledFeatures: features)

do {
    // Initialize the SDKNativeEngine
    try SDKNativeEngine.makeSharedInstance(options: options)
} catch let engineInstantiationError {
    showMessage("Failed to initialize the HERE SDK. Cause: \(engineInstantiationError.localizedDescription)")
    return
}
// Reset the map view
self.mapViewObservable.resetMapView()

// Initialize MapDownloader
initMapDownloader(sdkNativeEngine: SDKNativeEngine.sharedInstance!)

// Reinitialize other necessary engines as required.

2. 現在のMapViewインスタンスを更新して、makeSharedInstance()の呼び出しによって無効化されたレンダリングサーフェスを再作成します。

MapViewを再作成できるようにするには、MapViewObservable内でカプセル化します。このオブジェクトにより、SwiftUIはMapViewを監視できるようになり、
その結果、MapViewObservableが変更されると、MapViewおよびそのレンダリングサーフェスが再作成されます。

class MapViewObservable : ObservableObject {
    @Published var mapView: MapView?  

    init() {
        self.mapView = MapView()
    }

    func configureMapView() {
        self.mapView = self.mapView ?? MapView()
        let camera = self.mapView!.camera
        let distanceInMeters = MapMeasure(kind: .distanceInMeters, value: 1000 * 7)
        camera.lookAt(point: GeoCoordinates(latitude: 52.530932, longitude: 13.384915),
                      zoom: distanceInMeters)
        // Load the map scene using a map scheme to render the map with.
        self.mapView!.mapScene.loadScene(mapScheme: MapScheme.normalDay, completion: onLoadScene)

    }

    // Completion handler for loadScene().
    private func onLoadScene(mapError: MapError?) {
        if let mapError = mapError {
            print("Error: Map scene not loaded, \(String(describing: mapError))")
        }
    }

    func resetMapView() {
        self.mapView = nil
    }
}

MapViewObservableは、UIViewRepresentableラッパーを活用することでSwiftUIと統合できます。実装は次のようになります。

// The MapView provided by the HERE SDK conforms to a UIKit view, so it needs to be wrapped to conform
// to a SwiftUI view. The map view is created in the ContentView and bound here.
private struct WrappedMapView: UIViewRepresentable{
    @ObservedObject var mapViewObservable: MapViewObservable

     func makeUIView(context: Context) -> MapView {
         if mapViewObservable.mapView == nil{
             mapViewObservable.configureMapView()
         }

         return mapViewObservable.mapView!
     }

     func updateUIView(_ uiView: MapView, context: Context) {
         // Updates will automatically apply due to observable properties
     }
}

3. MapUpdaterを再初期化し、カタログを更新するために使用します。

// ReCreate MapUpdater in background to not block the UI thread.
MapUpdater.fromEngineAsync(SDKNativeEngine.sharedInstance!) { mapUpdater in
    self.mapUpdater = mapUpdater
    // Perform the map update ...
}

LayerConfigurationの更新方法およびマップデータの更新を実装する例については、GitHub上のOfflineMapsサンプルアプリを参照してください。

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

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

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

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

• detailRendering
• navigation
• offlineSearch
• offlineRouting
• rendering
• truck

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

var features: [LayerConfiguration.Feature] = [.detailRendering, .rendering, .offlineSearch]
options.layerConfiguration = LayerConfiguration(enabledFeatures: features)
options.layerConfiguration.implicitlyPrefetchedFeatures = features

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

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

次に、特定のユースケースに基づいてimplicitlyPrefetchedFeaturesを設定する方法の例をいくつか示します。

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

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

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