主な概念

次のユースケースのセクションでは、最も一般的な使用シナリオについて説明し、 HERE SDK for iOS を最大限に活用するためのヒントとわかりやすいガイドラインを示します。

このガイドの使用方法

このガイドは、任意の順序で読むことができます。 すべてのセクションが互いに独立しているので、任意のセクションをスキップして、最も関心のあるトピックに直接進むことができます。

• 使用例のセクションでは、このユーザー ガイドに付属するサンプルアプリを見つけることができます。
• HERE マップを表示する最初のアプリの作成に関心がある場合 は、利用開始セクションで最初の簡単な手順を確認してください。
• この開発者ガイドでカバーされている利用可能なユースケースの概要を参照できます。

表記規則

HERE SDK で は、完了ハンドラがコールバック関数として使用されます。 HERE SDK で使用できるすべての完了ハンドラで は、終了式 または 関数呼び出し式を使用できます。 このガイドでは、関数 呼び出し式を使用し て、メソッドやコールバック名などのすべての種類の情報やその他の詳細情報を表示することをお勧めします。 両方の例については 、 [ 検索 ] セクションを参照してください。

無料のリソース

アプリの有効期間が終了すると、 SDKNativeEngine.sharedInstance = nilを呼び出してリソースを解放できます。 また、SDKNativeEngine へのすべての参照をnil に設定する必要があります ( 存在する場合 ) 。 これを呼び出した後、関連する HERE SDK 機能は使用できなくなります。ただし、 HERE SDK を再度初期化する場合を除きます。 既定のコンストラクタを使って SearchEngine() や RoutingEngine() などのエンジンを作成した場合は、これらのインスタンスも再作成する必要があります。 基本的に、SDKNativeEngine の同じインスタンスを使用したすべてのエンジンは、 nil に設定した後で再作成する必要があります。

完了ハンドラとデリゲート

• HERE SDK では、検索結果などの単一のイベント通知に完了ハンドラが使用されます。
• ジェスチャイベントなどの繰り返し発生するイベント通知に は、デリゲート が使用されます。 複数のデリゲートを設定できる場合は、メソッドのパターン add_x() とremove_x() が命名規則として使用されます。 一度に設定できるデリゲートが 1 つだけの場合は、リスニングを停止するようにnilを設定できるプロパティが使用されます。
• ほとんどのデリゲートプロパティは 、弱い参照として宣言されています。 したがって 、適合するオブジェクトとそれぞれのデリゲート変数の間の保持サイクルを解除するように、これらのデリゲートを手動でnilに設定する必要はありません。
• 開発者は、完了ハンドラまたはデリゲートの範囲内のエラーを適切に処理する責任があります。 ガイドラインとして、例外をスローできるコードを処理する必要があります。

デバッグログ

LogAppender プロトコルを使用して、に独自のログクラス SDKNativeEngineを挿入できます。 この方法では、 HERE SDK のリリースビルドの場合でも、さまざまな事前定義ログレベルのアプリメッセージをログに記録できます。

iOS シミュレータを実行している場合、ターミナルから次のコマンドを実行することで、 Xcode を実行せずにログを取得できます。

xcrun simctl spawn booted log stream --level debug

コードスニペット

表示されているコードスニペットは、自分のアプリケーションで使用できるベストプラクティスのサンプルコードをカバーしています。 ただし、このガイドの説明的なアプローチを単純化し、影を付けないようにするために、特にエラー処理や堅牢なスレッド処理については、すべてのエッジシナリオが処理されるわけではありません。 明らかなコードが残っている場合も ありますが、付属のサンプルアプリで確認できます。このアプリは、有効な HERE Credentials のセットを使用して、サポートされている任意のデバイスで即座に構築および展開できます。 Swift と同様に、 HERE SDK が安全に行うことを設計によって保証する場合を除き、オプションの強制的なアンラッピングは回避されます。

設計原則

付属の サンプル アプリは同じ構造に従います。 HERE SDK のサンプルコードは、できるだけ周囲のプラットフォームコードから分離されます。 表示されている API の関連する部分を簡単に確認できるようにしてください。 各例のアプリは、 HERE SDK の初期化元と同じエントリポイントに従います。 各アプリは HERE SDK のさまざまな側面に焦点を当てているため、そのコードは、クラス名に "...example.swif" を付けてポストフィックスされた 1 つのクラスに含まれています。 ほとんどの場合、このクラスは、作業を開始するためにMapViewへの参照を取得します。

一般的なプラットフォーム分離の原則に従って、サンプルコードはほとんどの iOS の依存関係から解放されます。代わりに、 HERE SDK の使用方法を示す純粋な Swift コードが主に使用されます。

非推奨とベータ版

HERE SDKの開発チームは、一貫したインターフェイスとともに、最も柔軟でありながら最も使いやすいAPIを提供するために、利用可能なAPIを常に見直し、改善しようとしています。

同時に、通常隔週で発生するリリース全体で安定したAPIを確保したいと考えています。 したがって、非推奨プロセスに従います。 私たちのポリシーは、 リリースノートで非推奨が発表された後の次のメジャーバージョンから数えて2つのメジャーバージョンまでの非推奨APIを維持することです。つまり、6か月から9か月の間です。 APIリファレンスでは、インターフェイスが非推奨としてマークされたときに、影響を受けるバージョンを常に確認できます。

新しいAPIや最終的には不安定なAPIの一部は 、APIリファレンスで「ベータ」と表示されています。 ベータ版リリースでは、特に明記されていない限り、非推奨プロセスは実行されません。 ベータAPIを使用する場合は、いくつかのバグや予期しない動作が発生する可能性があることに注意してください。

もちろん、改善の可能性についてのフィードバックには常に興味があります。

依存関係管理

現在 、 CocoaPod による依存関係管理 はまだサポートされていません。 これは、「利用開始」セクションで説明されているように、HERE SDK フレームワークをアプリケーション プロジェクトにローカルにコピーする必要があることを意味します。

HERE SDK を他のフレームワークと併用

HERE SDK は他のフレームワークと併用可能 たとえば、開いている道路マップをSearchEngineと結合することもできます ( 結合する場合 ) 。

• Xamarin ： HERE SDK は Xamarin をサポートしていませんが、 HERE SDK が提供するパブリック API の上に Xamarin のラッパーを実装できます。 Xamarin の関連するテストツールをサポートするために、 HERE SDK に変更を加えることはありません。

• React Native: React Nativeはサポートされていません。 ただし、お客様ご自身でラッパーを実装することはできますが、このようなタスクに対するサポートは提供していません。

Objective-C のサポート

現在、 HERE SDK は Objective-C をサポートしていません。また、ブリッジングヘッダーを使用することはできません。 コードベースが Objective-C で記述されている場合は、 Swift への移行を検討してください。

ただし、既存の Objective-C プロジェクトに統合されている Swift ファイルから直接 HERE SDK にアクセスすることは可能です。 Swift と Objective-C を 1 つのプロジェクトに混在させることはできますが、現在は Objective-C から直接 HERE SDK にアクセスできません

トランザクションおよび使用状況の統計情報

HERE SDK では、アプリ が作成したリクエストまたはトランザクションの数を照会するためのダイレクト API は提供されていませんが、この目的で外部 REST API を使用できます。 HERE Usage API を使用 すると、このようなデータを要求できます。 組織 ID org123456789 と開始日と終了日の例 :

https://usage.bam.api.here.com/v2/usage/realms/org123456789?startDate=2022-07-01T10:39:51&endDate=2022-08-30T10:39:51

詳細については 、コスト管理のドキュメントを参照してください。

HERE SDK Thread Safe ですか ?

HERE SDK がスレッドセーフであることは保証されていません。また、メインスレッドから SDK を呼び出す必要があります。 内部的には、 HERE SDK はほとんどの作業をバックグラウンドスレッドにオフロードしますが、コードへのコールバックは常にメインスレッドで発生します。 一般に、呼び出し元はスレッドセーフであることに注意してください。 たとえば、コードが同期されていない限り、異なるスレッドでエンジンを再利用することは安全ではありません。

TaskHandles を使用して非同期操作をキャンセル

ほとんどの非同期メソッドは 、即時の戻り値としてTaskHandleを提供しますが、操作の最終結果は完了ハンドラで遅延して返されます。 TaskHandle はステータス情報を提供し、進行中の操作を中止できます。

ユニットテスト

すべてのクラスが完全にモックアップ可能であるため、 HERE SDK を使用するアプリ ロジックのユニットテストを簡単に記述できます。 以下に、XCTestを使用した例を示します。

func testAngle() throws {
    // Static creation of angle object.
    let angle = Angle.fromRadians(angle: 0.174533)

    let angleInDegrees = angle.degrees
    // Round the test angle to 1 significant decimal.
    let roundedAngleInDegrees = round(angleInDegrees)

    let expectedAngleInDegrees: Double = 10
    XCTAssertEqual(roundedAngleInDegrees, expectedAngleInDegrees, "This is a message for a failed test.")
}

ユニットテストのExampleアプリで 、その他のユースケースの例を確認してください。

カバレッジ

サポート対象の国および言語の詳細については、[カバレッジページ]を参照してください。

範囲の定義

任意で、アプリケーションに複数のスコープを定義できます。たとえば、アプリをテストするための debugScope を定義できます。アプリ のプロダクションバージョンでは、スコープを 空のままにすることができます。これが既定値です。 プロジェクト ID の設定方法の詳細については、『IAM ガイド』を参照してください。

各アプリ は、少なくとも 1 つのプロジェクトに属しています。 HERE platform アカウントを使用してプロジェクトマネージャーで 、「プロジェクト」を選択します。 これにより、使用可能なプロジェクト ID を表示できます。 さらに追加することもできます。 各プロジェクト ID に は、 HERE リソースネーム 値が表示されます。

HERE リソースネーム 値をファイルのスコープとして plist 次のように設定します。

<key>HERECredentials</key>
<dict>
    <key>AccessKeyId</key>
    <string>YOUR_ACCESS_KEY_ID</string>
    <key>AccessKeySecret</key>
    <string>YOUR_ACCESS_KEY_SECRET</string>
    <!-- Optionally, set a project scope. -->
    <key>Scope</key>
    <string>YOUR_PROJECT_SCOPE</string>
</dict>

このガイドに従って、プロジェクトの管理方法を確認してください。

プロジェクト ID は一意である必要があり、組織のアカウントの有効期間中は変更できません。 プロジェクト ID の長さは 4 ～ 16 文字である必要があります。 HERE リソースネーム 値にも影響があります。 スコープ /HRN がアプリケーションによって設定されている場合、そのスコープは認証およびアプリケーションの内部トークン 作成に使用されます。 不明なスコープが設定されている場合、認証の試行は失敗し、アプリケーションログにそのことが示されます。

エンジン

HERE SDK には、 複数のモジュール（またはエンジン）が含まれています。これらのモジュールは、RoutingEngineを使用してルートを計算する、またはSearchEngineを使用して検索結果を要求するなどの特定のタスクを実行するために呼び出されます。 HERE SDK で使用できるエンジンは他にも数多くあります。詳細については、以下の専用の章を参照してください。 ただし、ほとんどのエンジンで共通の概念が採用されているため、使いやすくなっています。 例 :

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

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

• SearchEngine: ジオコーディングや リバースジオ コーディングなど、場所、提案、場所を検索するすべてのフィーチャーが含まれています。
• OfflineSearchEngine: すでにダウンロードされているマップ データを使用してリクエストをローカルで作成するオフラインバージョンの検索。
• RoutingEngine / TransitRoutingEngine　： さまざまなオプションやトランスポートタイプを含むルートを計算できます。
• OfflineRoutingEngine: すでにダウンロードされているマップ データを使用してルートを計算するオフラインバージョン。
• LocationEngine: 高度な HERE Positioning ソリューション。
• ConsentEngine: 例 : LocationEngineを使用する前にユーザーの同意を集約するのに役立つサポートエンジン。
• Navigator / ： VisualNavigator 名前に「 engine 」は含まれていませんが、これらのクラスはエンジンとして機能し、ターン・バイ・ターンナビ　（矢印ナビ）のすべての機能を制御します。
• DynamicRoutingEngine: 現在の交通状況の確認に基づいて、より短いルートまたはより速いルートを定期的に検索するエンジン。 これは、ルートの代替案についてドライバーに通知するためのガイダンス中に役立ちます。
• TrafficEngine: 交通障害を検索できるエンジン。
• MapDownloader // ： MapUpdaterRoutePrefetcher これらのクラスは、マップ データのダウンロードまたは更新を実行し、オフライン モードをサポートするすべてのアプリケーションの重要な部分をマークします。
• VenueEngine: アプリへのプライベート施設 の統合をサポートする専用エンジン。
• SDKNativeEngine: 資格情報をプログラムで設定し、他のいくつかの詳細設定を許可するために必要。

SDKNativeEngineを除くすべての HERE SDK エンジン は、相互に独立して動作でき、データを要求するには HERE Credentials が必要です。

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

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 4.12.1.0 以降では、 HERE SDK を手動で初期化する必要があります。 利用開始 ガイドに従って、この方法を確認してください。

• アプリ がアプリ の開始後すぐにマップ ビュー を表示する場合は、ほとんどの使用例で利用開始 ガイドに従うだけで十分です。 ただし、
• アプリで後からマップ ビュー を表示する必要がある場合、または初期化を遅延する場合は、後で HERE SDK を初期化することもできます。
• 注 : HERE SDK の初期化時間は、トランザクションおよび月間アクティブユーザー (MAU) のカウント方法には影響しません。

HERE SDK で SDKOptions を作成して初期化 し、新しいSDKNativeEngineを作成するために使用します。

SDKNativeEngine およびSearchEngine などの他のエンジンの作成は、無視できる短時間で同期的に行われます。

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

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

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

また、まれな使用例で 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)を呼び出してグローバルインスタンスを作成する場合、この呼び出しは不要です。便宜上、この呼び出しによって、以前に共有されたインスタンスは内部的に破棄されます。

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

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

ヒント : 資格情報を保護

資格情報は、使用を意図していない第三者による悪用を防ぐために保護される必要があります。

資格情報 を安全に保つ 1 つのオプションは、 SSL 接続およびキーチェーンデータ保護などのデータ保護メカニズムを使用した要求によって、これらを安全なサーバーに保存して取得することです。

ベストプラクティスについては、次の点を考慮してください。

• 機密データがプレーンテキストで保持されないようにするため。
• 安全な通信チャネルを使用して資格情報を転送します。
• デバイスセキュリティ や強力な暗号化などの暗号化を使用して資格情報を保存します。
• 改ざん防止およびデバッグ防止のコードを追加して、動的なランタイム実行中に潜在的な攻撃者がデータを傍受できないようにします。
• アプリケーションの使用状況を追跡して異常を検出します。

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

エンジンの動作にマップ ビュー は必要ありません。 したがって、マップ ビュー をアプリケーションに追加せずに、エンジンをスタンドアロンで実行できます。 このようにして、特定のエンジンのみを中心にアプリ を作成できます。 マップ ビュー を使用する場合と使用しない場合 - 新しいエンジンを作成する手順はまったく同じです。 HERE SDK を事前に初期化してください。

HERE SDK オプション

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

API リファレンス に特にメモがない限り、どのオプションも永続化されません。 つまり、 HERE SDK を再度初期化する場合は、保持する場合に前のオプションを再度設定する必要があります。

同じことは、さまざまな機能エンジンまたは RoutingEngine などの機能を使用して Route を計算するときに CarOptionsに設定できるオプションにも当てはまります。

オフラインスイッチ

HERE SDK は、 HERE SDK 無線をサイレントにするためのグローバルオフラインスイッチを提供します。 このオフライン モード は、 HERE SDK がオンライン接続を開始できないようにします。

SDKNativeEngine.sharedInstance?.isOfflineMode = true

たとえば、このモードでは、新しいマップタイルがキャッシュにロードされません。 Navigate Edition を使用している場合でも、検索、ルーティング、ガイダンスなどの機能を使用できます。

デバイス自体がフライトモードに設定されているかどうかは問題ではありません。 スイッチがアクティブの場合、 HERE SDK からの要求の発信がすべてブロックされます。 そのため、オフライン モード を再度無効にするまで、オンラインデータは使用されません。

ただし、HERE SDKを初期化するときに、いくつかの要求が行われることがあります。 HERE SDKを初期化する前にアプリケーションをオフラインで起動したい場合は 、SDKOptionsでフラグofflineModeをtrueに設定 します。 実行時にこれを変更する予定がない場合は、このフラグだけで完全にオフラインで動作できます。

外部 REST API で使用するアクセストークンを取得

HERE SDK が初期化されるたびに、新しいアクセス トークン が内部的に生成されます。 複数 SDKNativeEngine のインスタンスがある場合、各インスタンスは独自のトークン を保持します。 コールバック がAuthentication.authenticate(SDKNativeEngine.sharedInstance, callback)経由でトークン を提供する経由でトークン authenticationData.token を更新および取得することもできます。このトークン を使用して、外部 HERE REST API にアクセスできます。

HERE SDK 自体を使用する場合 は、トークン を把握する必要はありません。これは内部のみに必要で、 HERE SDK がトークン 生成を自動的に処理します。

不正使用からバックエンドを保護 するために、生成されたトークン数が多すぎる場合、またはアクセスされたサービス数が多すぎる時間帯にレート制限が適用されることがあります。 このような場合、エンジンが requestLimitReached エラーまたは類似のもので応答します。 アプリ の使用率が非常に高いと思われる場合は、事前に HERE の担当者に連絡して、必要に応じて上限を調整してください。

バグ発生時にサポートを依頼

クラッシュや予期しない動作が発生した場合は、 問題 の再現方法の詳細をお知らせください。

HERE SDKのネイティブC++スタックでクラッシュが発生した場合、クラッシュログにはクラッシュが発生したアドレスのみが表示されます。 クラッシュが発生したスタックトレースを確認するには、これらのアドレスを記号化する必要があります。

弊社にご連絡していただく際は、少なくともHERE SDKのバージョン、プラットフォーム、エディション、ログを必ず含めてください。 以下に、迅速な対応に役立つバグレポートのチェックリストを示します。

• 問題の種類： たとえば、クラッシュや予期しない動作などです。
  • クラッシュが発生した場合は、次のようなクラッシュログを提供してください。 スタックトレース。
  • 予期しない動作が発生した場合は、予想される動作と実際の動作を説明します。
• 問題は回帰であり、「はい」の場合はいつから発生していますか？
• 問題の説明と再現手順の詳細： 問題は、サンプルアプリケーションのいずれかで再現可能ですか？または、問題を切り分けるコードを提供できますか？
• どのようなAPIが呼ばれていますか（該当する場合）。 すべてのパラメータとオプションをリストしてみてください。
• 再現率は？
• OS、IDE、デバイス/シミュレータ（OS、名前）などの環境に関する情報を提供します。
• マップデータバージョン/使用済みカタログ（該当する場合）。
• 使用されている他のフレームワークまたはプラグインを、バージョン情報を含めて列挙します（該当する場合）。
• スクリーンショットまたはビデオを追加します（該当する場合）。
• 検索またはルーティングの問題が発生した場合は、問題が発生した地理座標またはGPXトレースを提供します。

リリースノートでは、既知の問題をリストしています。 また、実装上の問題を回避するために、この開発者ガイドの関連セクションに記載されている最新の手順とコード例に従うようにしてください。