主な概念

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

このガイドの使用方法

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

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

表記規則

このガイドでは 、 コールバックやリスナー名など、すべての種類の情報およびその他の詳細情報を表示するために、ラムダ表記を使用しないことを推奨します。 Android Studio で は匿名クラスと lambdas の間のワンクリック変換がサポートされているため、個人的な好みに合わせてサンプルを簡単に変更できます。

オブジェクトを廃棄します

インスタンスが参照されなくなった場合、または null に設定された場合、すべての HERE SDK クラスが Android によってガベージコレクションされます。

アプリの有効期間が終了すると、を呼び出し SDKNativeEngine.getSharedInstance().dispose()てリソースを解放できます。 また、へのすべての参照 SDKNativeEngine をに設定する必要が null あります ( 存在する場合 ) 。 呼び出し dispose() によって保留中のリクエストが停止され、まだ実行中の開いているファイルおよびデータベースが閉じられます。 dispose() 関連する HERE SDK 機能を呼び出した後は、 HERE SDK を再度初期化しない限り、使用しないでください。 既定のコンストラクタSearchEngine()RoutingEngine() などのエンジンを作成した場合、または既定のコンストラクタを使用した場合は、これらのインスタンスも再作成する必要があります。 基本 SDKNativeEngine 的に、の同じインスタンスを使用したすべてのエンジンは、廃棄後に再作成する必要があります。

コールバックとリスナー

• HERE SDK は 、検索結果などの単一のイベント通知のコールバックを公開します。
• ジェスチャイベントなどの繰り返し発生するイベント通知に は、リスナー が使用されます。 複数のリスナを設定できる場合 は、メソッドパターンadd_x()remove_x()となり、命名規則として使用されます。 一度に設定できるリスナーが 1 つだけの場合は、プロパティパターンが使用されます。 null リスナを停止するには、 listener プロパティをに設定します。
• 開発者は、コールバック の範囲内のエラーを適切に処理する責任があります。 ガイドラインとして、例外をスローできるコードを処理する必要があります。

デバッグログ

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

コードスニペット

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

設計原則

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

一般的な POJO (plain-old-java-Object) の原則に従って、サンプルコードはほとんどの Android の依存関係から解放されます。代わりに、ほとんどの場合、 HERE SDK の使用方法を示す純粋な Java コードです。

非推奨とベータ版

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

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

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

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

依存関係管理

現在、たとえば Gradle を使用した依存関係管理はまだサポートされていません。 つまり、 HERE SDK AAR バイナリは 、「はじめに 」の項で説明されているように、アプリケーションプロジェクトにローカルにコピーする必要があります。

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

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

• Xamarin ： HERE SDK は Xamarin をサポートしていませんが、 HERE SDK が提供するパブリック API の上に Xamarin のラッパーを実装できます。 Xamarin の関連するテストツールをサポートするために、 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 を使用するアプリロジックの単体テストを簡単に記述できます。 リリースパッケージに heresdk-mock は、すべての HERE SDK クラスのモンクを有効にする JAR ファイル が含まれています。 以下に、 Mockito を使用した例を示します。 これは、分岐されたオブジェクトを作成できる他のほとんどのフレームワークとも連携します。

@RunWith(MockitoJUnitRunner.class)
public class TestExample {

    @Test
    public void testNonStaticMethod() {
        Angle angleMock = mock(Angle.class);

        when(angleMock.getDegrees()).thenReturn(10.0);

        assertEquals(10.0, angleMock.getDegrees());
        verify(angleMock, times(1)).getDegrees();
        verifyNoMoreInteractions(angleMock);
    }

    ...
}

アプリ build.gradle の設定で次の依存関係を使用します。

def getHereSdkArtefactName() {
    def aarFile = fileTree(dir: 'libs', include: ['heresdk-*.aar']).first()
    // Filename without extension is necessary.
    return org.apache.commons.io.FilenameUtils.getBaseName(aarFile.name)
}

// Exclude HERE SDK's aar from unit test's dependencies.
configurations.testImplementation {
    exclude module: getHereSdkArtefactName()
}

dependencies {
    implementation(name: getHereSdkArtefactName(), ext:'aar')

    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.android.support.constraint:constraint-layout:1.1.3'

    // Keep in mind that the original HERE SDK aar must be excluded from
    // the test dependency, see above.
    testImplementation fileTree(dir: 'libs', include: ['*mock*.jar'])
    testImplementation 'junit:junit:4.12'
    testImplementation 'org.mockito:mockito-core:3.1.0'
}

この設定では、 HERE SDK は単体テストの実行時に模擬 JAR を使用し、アプリの構築時に実際のアプリ AAR を使用します。heresdk-edition-mock-version.jarを heresdk-edition-version.aarと同じapp/libsフォルダに配置 します。

UnitTestingExampleアプリで 、その他のユースケースの例を確認してください。

カバレッジ

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

範囲の定義

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

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

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

<!-- Optionally, set a project scope. -->
<meta-data
   android:name="com.here.sdk.access_scope"
   android:value="YOUR_PROJECT_SCOPE" />

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

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

エンジン

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

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

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

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

try {
    searchEngine = new SearchEngine();
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization of SearchEngine failed: " + e.error.name());
}

この既定のコンストラクタを使用するには、 HERE SDK が既に初期化されており、SDKNativeEngineの共有インスタンスがSDKNativeEngine.setSharedInstance(sdkNativeEngine)を直接呼び出して設定されているか、またはSDKNativeEngine.makeSharedInstance(context, options)を呼び出して暗黙的に設定されている必要があります。

まれ SDKNativeEngine なユースケース シナリオでは、次のセクションに示すように、の個々に作成されたインスタンスを受け取るオーバーロードされたコンストラクタを使用できます。

初期化中です

HERE SDK 4.12.1.0 以降では、 HERE SDK を手動で初期化する必要があります。 はじめに ガイドに従って、この方法を確認してください。

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

HERE SDK を初期化する手順は、次のとおりです。

1. 廃止されたを非アクティブ化 InitProvider します ( このステップは HERE SDK 4.15.0 で廃止されます ) 。
2. HERE SDK を作成し SDKOptions て初期化 SDKNativeEngineし、新しいを作成するために使用します。

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

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

• SDKNativeEngine との共有インスタンス SDKNativeEngine.makeSharedInstance(context, options)を作成します。
• SDKNativeEngine 経由地の個々のインスタンスを作成 SDKNativeEngine​(context, options)します。

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

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

SearchEngine searchEngine = new SearchEngine(sdkNativeEngine);

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

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

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

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

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

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

資格情報 を安全に保つ 1 つのオプションは、 SSL 接続を使用して、それらを安全なサーバーに保存し、要求によって取得することです。

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

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

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

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

HERE SDK オプション

HERE SDK は、の直接設定、 SDKNativeEngine またはでエンジンを初期化する際に設定できるさまざまなオプションで初期化 SDKOptionsできます。

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

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

オフラインスイッチ

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

SDKNativeEngine.getSharedInstance().setOfflineMode(false);

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

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

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

HERE SDK がオフラインになると、進行中およびキューに入っているすべてのリクエストが停止します。

HERE SDK がオフライン モード で動作するように切り替えられると、でレンダリングされたすべてのマップ データ MapView がキャッシュから取得さ れるか 、または永続ストレージから取得されます。 後者の場合は、 Navigate Edition などのエディションでのみ利用可能な、事前にダウンロードされたマップ データ が必要です。

HERE SDK がオフライン モード で動作するように切り替えられ、VEHICLE_RESTRICTIONSなどの一部のマップレイヤーがMapFeatures最上位で有効 になっている場合、このデータは、永続化されたストレージの一部としてすでにキャッシュされているか、またはRegionダウンロードされている場合にのみレンダリングされます。 このルールは、使用可能なすべての地図機能に適用されます。

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

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

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

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

バグが発生した場合のサポート

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

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

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

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

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