主な概念

次のユースケースのセクションでは、最も一般的な使用シナリオについて説明し、 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 は、リスニングを停止するように設定できるプロパティが使用されます。
  • 開発者は、完了ハンドラまたはデリゲートの範囲内のエラーを適切に処理する責任があります。 ガイドラインとして、例外をスローできるコードを処理する必要があります。

デバッグログ

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 コードが主に使用されます。

依存関係管理

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

他のフレームワークでの HERE SDK の使用

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

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

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

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 、 As immediate の戻り値を提供しますが、操作の最終結果は遅延のある完了ハンドラで返されます。 は 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.")
}

カバレッジ

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

範囲の定義

任意で、アプリケーションに複数のスコープを定義できます。たとえば、アプリをテストするための 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 エンジン SDKNativeEngineは、相互に独立して動作でき、データを要求するには HERE Credentials が必要です。

メモ

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

フリーミアム資格情報はほとんどの機能で動作し ますが、Navigate Edition などのエディション専用のオフライン マップなどの機能では動作しません。 資格情報 が無効な場合、ログには「 Failed to get the authentication トークン : 認証に失敗しました。エラーコード : 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 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 経由地の個々のインスタンスを作成 SDKNativeEngine​(options: options)します。

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

また、まれな使用例で SDKNativeEngine は、各機能エンジンに個別のインスタンスを設定できます。

try searchEngine = SearchEngine(sdkNativeEngine)

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

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

メモ

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

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

メモ

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

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

ヒント : 資格情報 を保護します

資格情報 を使用することを意図していない他の当事者に悪用を提供するために、お客様のを保護する必要があります。

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

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

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

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

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

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

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

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

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

」に一致する結果は 件です

    」に一致する結果はありません