マップ ビューとの統合の有無、初期化オプション、マップ キャッシュの効率的な管理など、HERE SDK エンジンの操作の基本コンセプトを確認します。

エンジンの操作方法

HERE SDK には、RoutingEngine を使用したルートの計算や SearchEngine 経由での検索結果のリクエストなど、特定のタスクを実行するいくつかのモジュール (HERE ではエンジンと呼ぶ) が含まれています。HERE SDK で使用できるエンジンは他にもたくさんあります。詳細については、以下の各章を参照してください。ただし、ほとんどのエンジンは共通の概念を共有しているため、簡単に使用できます。例：

• すべてのエンジンは、タスクを非同期的に実行し、メイン スレッドで結果を受け取ります。
• すべてのエンジンは、類似するインターフェース、コールバック、エラー処理を共有しています。
• 1 つのエンジンの複数のインスタンスを並行して開始できます。
• オンライン接続が必要です。

以下に、HERE SDK の最も一般的なエンジンの概要を示します。

• SearchEngine：ジオコーディングやリバースジオコーディングなど、場所、候補、位置情報を検索するすべての機能が含まれています。
• OfflineSearchEngine (Navigateでのみ使用可能)：ダウンロード済みのマップデータを使用してローカルでリクエストを実行する、オフラインバージョンの検索です。
• RoutingEngine/TransitRoutingEngine：さまざまなオプションや交通機関タイプを含むルートを計算できます。
• OfflineRoutingEngine (Navigateでのみ使用可能)：ダウンロード済みのマップデータを使用してルートを計算するオフラインバージョンです。
• LocationEngine (Navigateでのみ使用可能)：高度なHERE Positioningのソリューションです。
• ConsentEngine (Navigateでのみ使用可能)：LocationEngineなどを使用する前にユーザーの同意を集約するのに役立つサポートエンジンです。
• Navigator / VisualNavigator (Navigateでのみ使用可能)：名前に「エンジン」は含まれていませんが、これらのクラスはエンジンとして機能し、ターン・バイ・ターンナビに関連するすべての機能を制御します。
• DynamicRoutingEngine (Navigateでのみ使用可能)：現在の交通状況に基づいて、より短いルートやより速いルートを定期的に検索するエンジンです。これは、ドライバーに代替ルートを通知するガイダンス中に役立ちます。
• TrafficEngine：交通事案を検索できるエンジンです。
• MapDownloader / MapUpdater/ RoutePrefetcher (Navigateでのみ使用可能)：これらのクラスは、マップデータのダウンロードまたは更新を実行し、オフラインモードをサポートするアプリケーションで重要な役割を果たします。
• VenueEngine (Navigateでのみ使用可能)：アプリへの非公開施設の統合をサポートする専用エンジンです。
• SDKNativeEngine：資格情報をプログラムで設定するために必要です。その他のいくつかの詳細設定を行うことができます。
• MapView：マップ データを視覚化するビューです。実際にはエンジンではありませんが、完全を期すためにこちらに掲載しています。

なお、SDKNativeEngine を除くすべての HERE SDK エンジン は互いに独立して動作でき、データをリクエストするには HERE Credentials が必要です。

注

HERE SDK は、インスタンス化時に資格情報を検証しません。これは、認証を必要とする機能が使用された場合にのみ実行されます。失敗した場合は、専用のエラー メッセージが表示されます。たとえば、SearchEngine は SearchError.authenticationFailed エラーを返します。他のエンジンでも同様のエラー コードが表示されます。

すべての資格情報がすべての機能で有効なわけではありません。資格情報が無効な場合、ログには次の内容が含まれます。 error次のようなテキストを含むメッセージ Failed to get the authentication token: Authentication failed, error code: 1です。これは、サービスを使用した際に資格情報が受け入れられなかったことを示しています。資格情報が正しく設定されていることを確認するには、専用エンジンの機能を使用して、エンジンがエラー値で応答するかどうかを確認します。

パラメーターレス コンストラクタを使用して、任意のエンジンを作成できます。例：

do {
    try searchEngine = SearchEngine()
} catch let engineInstantiationError {
    fatalError("Failed to initialize engine. Cause: \(engineInstantiationError)")
}

このデフォルトのコンストラクタを使用するには、HERE SDK がすでに初期化されており、SDKNativeEngine の共有インスタンスが SDKNativeEngine.sharedInstance = sdkNativeEngine を呼び出すことで直接的に設定されているか、SDKNativeEngine.makeSharedInstance(options: options) を呼び出すことで暗黙的に設定されている必要があります。

次のセクションに示すように、ごく一部のユースケースでは、個別に作成された SDKNativeEngine エンジンを受け取る、オーバーロードされたコンストラクタを使用できます。

マップ ビューの有無にかかわらずエンジンを使用する

エンジンが動作するのにマップ ビューは必要ありません。そのため、アプリケーションにマップ ビューを追加しなくても、エンジンをそのまま実行できます。このようにすることで、特定のエンジンのみを中心にアプリを構築できます。マップ ビューの有無を問わず、新しいエンジンを作成する手順はまったく同じです。必ず事前に HERE SDK を初期化してください。

初期化オプション

HERE SDK は、さまざまなオプションを使用して初期化できます。これらのオプションは、SDKNativeEngine に直接設定するか、SDKOptions を使用してエンジンを初期化するときに設定できます。

「API リファレンス」に特に注記がない限り、どのオプションも保持されません。つまり、HERE SDK を再度初期化するたびに、以前のオプションを引き続き利用する場合は再設定する必要があります。

同じことは、さまざまな機能エンジンに設定するオプションや Route を計算する RoutingEngine などの機能を使用する場合のオプション (例：RoutingOptions) にも当てはまります。

HERE SDK 4.12.1.0 以降では、HERE SDK を手動で初期化する必要があります。詳細については、「HERE SDK を統合する」を参照してください。

• アプリを起動したらすぐにマップ ビューが表示されるようにするには、ほとんどのユースケースでは、「HERE SDK を統合する」のガイドに従うだけで十分です。例外：
• アプリでマップ ビューを後の時点で表示する必要がある場合、または初期化を遅らせる場合は、後の時点で HERE SDK を初期化することも可能です。

SDKOptions を作成し、これを使用して新しい SDKNativeEngine を作成することで HERE SDK を初期化します。

SDKNativeEngine およびその他の SearchEngine などのエンジンは、ごく短時間で同期的に作成されます。

HERE SDK は、次の 2 つの方法で初期化できます。

• SDKNativeEngine.makeSharedInstance(options: options) を使用して、SDKNativeEngine の共有インスタンスを作成します。
• SDKNativeEngine​(options: options) を介して、SDKNativeEngine の個別のインスタンスを作成します。

SDKNativeEngine.makeSharedInstance(options: options) を呼び出すことで、HERE SDK で使用できる SDKNativeEngine の共有インスタンスが作成されます。このシングルトン アプローチでは、パラメーターを必要としないデフォルトのコンストラクタ (SearchEngine()) を使用できるため、SearchEngine などのエンジンを簡単に作成できます。内部的には、SearchEngine は初期化時に作成した SDKNativeEngine の共有インスタンスを使用します。そのため、HERE SDK を再度初期化する場合は、このパラメーターレス コンストラクタを使用して作成されたすべてのエンジンも再度作成する必要があります。

注

再初期化の場合は、MapView インスタンスもその onCreate(..) メソッドを呼び出して再度初期化する必要があります。SDKNativeEngine が破棄されると、MapView の状態は無効になります。mapView.isValid() を呼び出して、MapView が正しく初期化されたかを判断します。

または、ごく一部のユースケースでは、各機能エンジンのインスタンスに個別の SDKNativeEngine インスタンスを設定できます。

try searchEngine = SearchEngine(sdkNativeEngine)

一般的には、SDKNativeEngine を複数回初期化する必要はありません。同時に設定できる共有インスタンスは 1 つだけです。この設定は、SDKNativeEngine.makeSharedInstance(options: options) を呼び出したときに暗黙的に行われます。または、利用可能なコンストラクタを使用して、SDKNativeEngine のインスタンスを直接作成できます。複数のインスタンスを個別に作成する場合、共有インスタンスは設定されません。上に示したように、SDKNativeEngine のインスタンスをコンストラクタ パラメーターとして使用して、各機能エンジンを作成する必要があります。この方法により、SearchEngine または RoutingEngine のような機能エンジンを、異なる SDKOptions を持つさまざまな SDKNativeEngine のインスタンスと一緒に使用できます。

個々のインスタンスは、SDKNativeEngine.sharedInstance = sdkNativeEngine を呼び出すことで明示的に共有インスタンスとして設定できます。注意：この場合は、SDKNativeEngine.sharedInstance = nil を呼び出して以前のインスタンスを破棄するようにしてください。なお、SDKNativeEngine.makeSharedInstance(options: options)を呼び出してグローバルインスタンスを作成する場合には、この操作は不要です。便宜上、この呼び出しによって、以前に共有されたインスタンスは内部的に破棄されます。

注

ほとんどのユースケースでは、複数のインスタンスを作成することはお勧めしません。不明な点がある場合は、「HERE SDK を統合する」ガイドに示されているように、SDKNativeEngine.makeSharedInstance(options: options) を介してのみ HERE SDK を初期化することをお勧めします。この初期化メソッドは、HERE SDK が必要になるたびに使用し、その後、各ビューなどの SDKNativeEngine を破棄できます。ただし、ほとんどの場合、HERE SDK はアプリケーションのライフタイム中に 1 回のみ初期化される方が効率的です。

複数の SDKNativeEngine インスタンスが同じアクセス キー ID を持つことはできません。また、キャッシュ パスはアクセス キー ID ごとに一意であることが保証されます。すでに使用されているアクセス キー ID を使用して 2 つ目のインスタンスが作成された場合は、InstantiationException がスローされます。一般的に、複数のインスタンスが必要な場合は、それぞれに異なる資格情報のセットも必要です。

注

資格情報のアクセス キー ID 部分は、キャッシュ パスに関連付けられています。実行時に資格情報が変更されると、以前のキャッシュがなくなったように見えることがあります。しかし、キャッシュはまだ存在しており、SDKNativeEngine の破棄後や新しい資格情報の設定後、自動的には消去されません。新しい資格情報が設定されたため、キャッシュ パスが変更されただけのことです。たとえば、以前の資格情報が復元されると、以前のキャッシュを再度使用できるようになります。

キャッシュの詳細については、以下を参照してください。

マップ キャッシュを操作する

オンラインおよびオフラインのユースケースをより適切にサポートするために、HERE SDK はダウンロードされたベクター マップ データのキャッシュをサポートしています。これはバックグラウンドで実行されます。地図を操作し、マップ ビューの有無にかかわらずナビゲーションをプリフェッチまたは使用すると、データはデバイスにローカルに保存され、デバイスの接続が失われたり、オフライン モードで操作している場合でもアクセスできます。

注

HERE SDK は、マップ タイルの一部として任意のデータを格納します。そのため、マップ ビューを表示しなくても、マップ キャッシュが使用されます。たとえば、ナビゲーション中に、必要なすべてのデータがマップ タイル内のマップキャッシュに保存されます。ただし、すべてのライセンスがプリフェッチやナビゲーションなどの機能をサポートしているわけではありません。

統合されたマップキャッシュメカニズムは、標準のベクターベースのマップスキームをサポートしています。衛星画像やその他のラスタータイルもキャッシュに保存されますが、設定できない別のキャッシュに格納されます。

キャッシュに保存されるデータ量には限りがあり、マップの使用中は新しいマップ データに上書きされることに注意してください。ほとんどの場合、これはユーザーに起動時間が短縮されたという印象を与えるのに十分です。以前と同じ場所でアプリを再度起動するときに追加のデータをダウンロードする必要がないためです。

キャッシュがいっぱいになると、LRU (least recently used) 方式が適用されます。

パスとキャッシュ サイズを変更する

• SDKOptions を使用して HERE SDK を手動で初期化する場合は、絶対キャッシュ パスと最大サイズを指定できます。詳細については、「エンジン」セクションを参照してください。
• SDKOptions を使用して、希望する cacheSizeInBytes を指定し、キャッシュの上限をバイト単位で定義できます。利用可能なプラットフォーム API を使用して、デバイス上の使用可能なディスク容量を照会してください。

カスタム ラスター レイヤー には、個別のキャッシュを定義できます。

次の方法でマップ キャッシュを消去します。

SDKCache.fromEngine(SDKNativeEngine.sharedInstance!).clearCache { (error) in
    if error == nil {
        // ...
    }
}

SDKNativeEngine の共有インスタンスを nil に設定しても、キャッシュは消去されません。

空の文字列をキャッシュパスとして設定することで、デフォルトのキャッシュパスを保持します。このパスは、次のようにSDKNativeEngine.sharedInstance?.options.cachePathを使用してアクセスできます。

// Specify credentials programmatically and keep default cache path by setting an empty string.
let cachePath = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first?.path ?? ""
let authenticationMode = AuthenticationMode.withKeySecret(accessKeyId: "YOUR_ACCESS_KEY_ID", accessKeySecret: "YOUR_ACCESS_KEY_SECRET")
var sdkOptions = SDKOptions(authenticationMode: authenticationMode)
sdkOptions.cachePath = cachePath

Navigateでマップキャッシュを操作する

注

ターン・バイ・ターンナビにはキャッシュが必要なため、SDKNativeEngine を作成するときは有効なキャッシュ パスが必須です。

オフライン マップとは別に、マップ キャッシュを新しいマップ バージョンに更新できます。mapUpdater.performMapUpdate() を呼び出すと、Region が一度もインストールされていなくても、マップ キャッシュが新しいバージョン (利用可能な場合) に更新されます。オフライン マップが使用可能な場合は、以前と同様に、マップ キャッシュとともに更新されます。キャッシュの更新後にオフライン マップをインストールした場合、同じマップ バージョンが使用されます。マップ キャッシュとオフライン マップで異なるバージョンを使用することはできません。

マップ ビューのパン中に最新のマップ データを取得するには、更新が利用可能かどうかを確認してからインストールすることができます。オフラインの Region マップがインストールされていなければ、これはわずか数秒しかかかりません。MapVersionHandle は現在使用されているマップ バージョンを示します。

注

アプリケーションを新規にインストールする場合、必ずしも最新のマップ バージョンが使用されるわけではありません。通常、各 HERE SDK リリースには特定のマップ バージョンが付属しています。ただし、(カスタム) CatalogConfiguration を使用している場合は、DesiredCatalog で最新のマップ バージョンを指定するなどして、アプリのインストール直後に使用するマップ バージョンを指定できます。

マップバージョン、キャッシュ、オフライン マップの詳細については、「オフライン マップ」セクションを参照してください。

注

SDKOptions を使用して、キャッシュの有効期限を指定することもできます。時間を「0」に設定すると、アプリでデータがキャッシュに保存されなくなります。この場合、オフライン地域がインストールされていなければ、デバイスの接続が失われたときは、デバイスが再びオンラインになるまで地図は表示されません。このため、常に最新で最良の地図データが表示されるわけではありません。この場合は、地図の更新が利用可能かどうかを確認する必要があります。

マップキャッシュに関する質問と回答

Navigate

• **マップタイルとは何ですか？**マップタイルはマップキャッシュに格納されます。マップタイルには、検索とルート検索に関連するデータと、視覚的表現のベクターデータが含まれています。これは最適化されたクライアントマップ (OCM) 形式で保存されます。マップタイルは、さまざまなズームレベルで使用できます。マップタイルには、ズームレベルによって異なるデータが含まれている場合があります。

• **マップタイルはどのくらいの期間キャッシュに保存されますか？**マップ タイルは、キャッシュがいっぱいになったときにのみ削除されます。古いタイルが失効したり、時間に基づいて古いタイルが自動的に削除されたりすることはありません。これは衛星画像には適用されないのでご注意ください (下記参照)。

• **キャッシュの削除ポリシーについて教えてください。**HERE SDK は LRU (Least Recently Used) ロジックを使用して、マップ キャッシュがいっぱいになったときにタイルを削除します。たとえば、現在の場所から遠く離れたタイルを削除するなどの高度なロジックはありません。ユーザーが次に世界のどの領域を訪問する可能性があるかは予測できないためです。ただし、マップ キャッシュはセッション固有のものではありません。前回デバイスが使用されたとき (つまり前回の電源サイクル) のキャッシュ データは、次にアプリが使用されるときにまだ残っています。キャッシュはデバイスごとではなく、アプリごとに固有であることに注意してください。

• **マップ キャッシュにデータがない場合、どのような影響がありますか？**通常、マップ キャッシュは完全であることは想定されず、周囲の領域では常にタイルが欠落している可能性があります。これは、マップ タイルがレンダリングされている間に、オンデマンドでのみ読み込まれるためです。マップ キャッシュに不足しているタイルがある場合、たとえば OfflineSearchEngine は不足しているタイルの一部である POI や道路名を検出できず、HERE Rendering Engine はそのようなデータをレンダリングできません。また、不足しているタイルの周りにルートが見つからなければ、OfflineRoutingEngineが失敗することがあります。

Explore

• **マップタイルとは何ですか？**マップタイルはマップキャッシュに格納されます。マップタイルには、検索とルート検索に関連するデータと、視覚的表現のベクターデータが含まれています。マップタイルは、さまざまなズームレベルで使用できます。マップタイルには、ズームレベルによって異なるデータが含まれている場合があります。

• **マップタイルはどのくらいの期間キャッシュに保存されますか？**マップ タイルは 1 日後には使用できなくなり、削除されます。新しいイメージは、LRU方式に基づいて、1日後すぐにダウンロードされます。

• **キャッシュの削除ポリシーについて教えてください。**HERE SDK は、LRU (Least Recently Used Tile) ロジックを使用して、1 日後にタイルを削除します。マップ キャッシュはセッション固有のものではありません。前回デバイスが使用されたとき (つまり前回の電源サイクル) のキャッシュ データは、次にアプリが使用されるときにまだ残っています。キャッシュはデバイスごとではなく、アプリごとに固有であることに注意してください。

ExploreとNavigate

• **マップキャッシュのサイズはどれくらいですか？**マップ キャッシュのサイズは、アプリケーションによって変更できます。256 MB 以上を使用してください (デフォルト)。512 MB 以上または 1 GB を推奨します。 ターン・バイ・ターンナビ (Navigate などで利用可能) には、ズーム レベル 14 のマップ タイルが必要です。これは、約 2 km の円に相当します。ただし、これは場所によって多少異なる場合があります。

• **以前にキャッシュに保存されたマップ タイルはオフラインで検索できますか？**はい。OfflineSearchEngine を使用していつでも検索できます。ただし、すべてのマップタイルにすべてのズームレベルで同じ検索結果が含まれているとは限りません。OfflineSearchEngineはすべてのライセンスで使用できるわけではありません。

• **一度にキャッシュに保存されるマップタイルは1つだけですか？**はい。その場所が 2 つのタイルの端に位置しない限り、一度に 1 つのタイルのみが追加されます。ズーム レベルによっては、マップ ビューのレンダリングに複数のタイルが必要になります。これは自動的には行われず、ズーム レベルが変更された場合にのみ行われます。

• **衛星画像はキャッシュに保存されますか？**はい。衛星写真のマップ スキームが設定されている場合は対応する画像もキャッシュに保存されますが、衛星画像は (契約上の理由により) 1 日過ぎると使用できず、削除されます。新しいイメージは、LRU方式に基づいて、1日後すぐにダウンロードされます。

• **地球儀ビューなどの「ベース マップ」は常に利用できますか？**HERE SDK は、世界のタイル、つまり地球の最大ズーム レベルのタイルを自動的にダウンロードします。これは、レンダリング上の理由で情報量が非常に限定的な地球の地図を、常に利用できることを意味します。国や大陸の形状を確認でき、首都がテキスト ラベルで表示されます。

• **キャッシュは自動的に消去されますか？**いいえ。フル キャッシュは LRU 方式に基づいてのみ消去されます (上記を参照)。接続の中断によりタイルが完全にダウンロードされなかった場合、これらのタイルは保持され、接続が再開されるとダウンロードが続行されます。

• **接続性が確保されている場合は、ルート全体が事前にキャッシュに保存されますか？**いいえ。これは自動的には行われません。ただし、RoutePrefetcher を使用して、小道ルート沿いのマップ データをキャッシュにダウンロードできます。詳細については、「ターン・バイ・ターンナビ」セクションを参照してください。RoutePrefetcherはすべてのライセンスで使用できるわけではありません。