利用開始
このガイドでは、 HERE SDK を使用してアプリを構築するための最初のステップについて説明します。 HERE SDK は、 HERE platform からモバイルアプリケーションに最適な最新のアセットを提供できるようにカスタマイズされています。
作業を開始する前に、以下の内容を確認してください。
情報
開発を開始するには、HERE SDK パッケージを取得する必要があります。 内容は次のとおりです。
- Android アーカイブ (AAR)。 これは、アプリに含める HERE SDK バイナリです。
- 複数のドキュメントアセットとサンプルアプリ。
- アプリ に含める必要がある here_notice ファイル。オープンソースに関する通知参照してください。
HERE SDK パッケージを取得するには、次の 2 つの方法があります。
次の手順では、計画を選択します。
HERE SDK の使用を自由に開始できます。 利用可能な基本プランの概要については、 HERE の [ 基本プランの価格設定 ] ページを参照してください。 プランの詳細 については、価格設定に関する FAQ を参照してください。
ご利用のプランに応じ て、 HERE SDK は、 1 か月あたりのトランザクション数および月間アクティブユーザー (MAU) などのその他のパラメータに基づいて請求されます。
詳細については、 商用利用規約を参照してください。
資格情報を入手してください
HERE SDK でアプリ を認証するには、次の 2 つの文字列が必要です。
- アクセスキー ID (
access_key_id
):アカウントの一意の ID 。 - アクセスキーシークレット (
access_key_secret
): 秘密キー。作成時に 1 回だけ表示されます。 ページから移動する前に、メモしておいてください。
HERE SDK を使用するために、他の資格情報 またはトークンは必要ありません。
You can register and manage your app as described in the Identity & Access Management guide. You can acquire credentials for you plan either from here-tech.skawa.fun or on the HERE platform portal:
- On here-tech.skawa.fun, after creating your project, generate an app to obtain an access key ID and access key secret. You can either choose an existing project or Select a plan for a new project. Then scroll down to the HERE SDK product family and click キーの作成.
- または、HERE Platform Portalでアプリのページに移動し、新しいアプリを登録します。登録が完了すると 、資格情報 を作成できます。
資格情報は、 GitHub にあるすべてのサンプルアプリで動作します。 Navigate Edition の 場合、 HERE の担当者に連絡して、一連の評価資格情報 を生成する必要があります。
資格情報 を取得すると、 HERE .client.id または アプリ ID も 表示されます。 これらの ID は、 HERE SDK の公開 API では必要ありませんが、 HERE サポートチームに連絡する場合に役立ちます。
アプリの資格情報の設定方法の詳細については、以下の「アプリケーションの認証」セクションも参照してください。
アプリ 資格情報 およびプロジェクトの範囲
複数のアプリに同じ資格情報を使用する予定の場合は 、システム内のアプリを差別化する範囲を設定する必要があります。 資格情報を単一のアプリにのみ使用する場合は、この操作は不要です。
サンプルアプリを試してください
利用開始をする最も簡単 な方法は、 HERE SDK で利用できる多くのサンプルプロジェクトのいずれかを試すことです。
好みの例を選択してから、次の操作を行います。
- HERE SDK フレームワークをアプリ
libs
のフォルダーに追加 - HERE Credentials (
access_key_id
および access_key_secret
) を MainActivity.java
ファイルに挿入
これで、 Android Studio でプロジェクトを開く準備 ができました。また、お使いのデバイスまたはシミュレータでアプリを即座に実行できます。
注
この開発者ガイドのほぼすべてのトピックが実行可能なアプリとして利用できることをご存知でしたか ?
サンプルのコードを自由に試用以下のガイドを参照して、 HERE SDK でアプリを開発する方法についてより詳細に説明することもできます。
新しい Android プロジェクトを作成します
最初のステップバイステップの例として、「 Hello Map 」 Android アプリケーションを開発します。このアプリには「はい」と表示されます。 - マップ。 SDK を既存のアプリケーションに統合する場合は、この手順を省略できます。 特定の SDK コードが ここには、含まれていません。 Android Studio を IDE として使用することをお勧めします。 Android の開発を初めてご利用 になる場合は、 developer.android.com のガイドに従って、利用開始の最初のステップをサポートしてください。
注
「 HelloMap 」のサンプルコードは、 こちらです。
Android Studio を起動し ( このガイドでは、バージョン Dolphin | 2021.3.1 パッチ 1 を使用しています ) 、次のいずれかを選択して新しいプロジェクトを作成します。
- 新しい Android Studio プロジェクトを開始
- [ 携帯電話とタブレット] を選択し、 [ 空のアクティビティ ] を選択して、 [ 次へ ] をクリック
- プロジェクト名を入力します ( 例 : ) 「 HelloMap 」と入力し 、言語として「 Java 」または「 Kotlin 」を選択します。 以下の例で は、 [( Java)] を選択しています。
- 「 Minimum API level 」の横にある API 21 を最小 Android SDK に設定します。
- 「保存場所」で適切なディレクトリが選択されていることを確認し、「 完了 」をクリックして続行します。
AndroidX サポートの libaries を使用することをお勧めします。 まだ行ってい ない場合は、 Android Studio でリファクタリング -> AndroidXに移行をクリックします。
ウィザードが完了したら、プレーンプロジェクトをビルドし、エミュレータ ( またはデバイス ) で実行します。 問題が解決した場合は、「 Hello World 」テキストが表示されます。
こんにちは地図を発声してください。
動作中の Android アプリケーションを作成したら、 HERE SDK を追加して、エミュレータまたはデバイスにマップを表示します。 次のステップの概要を示します。
- HERE SDK を統合するようにグラデーションスクリプトの調整
- 必要な資格情報 と権限を設定
- HERE SDK の初期化
- メインアクティビティのレイアウトファイルにマップ ビューの追加
- 最初のマップ シーンをロードするコードの追加
注 : HERE SDK のすべての機能にはエミュレータからアクセスできますが、実際のデバイスを使用することを強くお勧めします。 全体的なパフォーマンスが向上し、ジェスチャなどの一部の機能は、マルチタッチ対応ハードウェアで簡単に使用できます。 マップ ビューのレンダリングは、モバイル機器 GPU 用に最適化されています。
まず、最初のステップで、 HERE SDK をプロジェクトに追加する方法を確認しましょう。
HERE SDK の統合
On here-tech.skawa.fun you can find the latest release artifacts including the HERE SDK framework archive to include in your application (named xx.yy.zz.release_date).
情報
Artifactory のサポートはまだ提供されていません。 つまり、 HERE SDK ライブラリ (AAR) を手動でダウンロードして統合する必要があります。 今後のリリースでは、 Maven を介した、 SDK 依存関係管理を追加する予定です。
HERE SDK AAR ファイル( *.aar )をアプリケーションの フォルダapp/libs
(アプリケーション のファイル build.gradle
で指定されているとおり)にコピーします。
HERE SDK ではラムダ式の使用が推奨されているため、 Java 8 以降が必要です。 アプリレベルの build.gradle
ファイルの android
クロージャ内に次のコードを追加して、コンパイラjavac
の出力を元の構文に戻します。
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
通常は、新しい Android Studio プロジェクトを作成するときに既定で追加されます。 追加されていない場合は、手動で追加してください。
次に、以下のものを追加して、同じファイルbuild.gradle
内の依存関係の終了を拡張し、ファイル*.aar
が含まれていることを確認します。
implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
注
このガイドは、 HERE SDK バージョン 4.15.3.0 に基づいています。 お使いの AAR バージョンがこのマニュアルで使用されているバージョンと異なる場合は、手順が異なる可能性があり、アプリ のソースコードを適合させる必要があります。
ここで 、ボタンSync
("Sync Project with Gradle Files") をクリックして SDK を統合します。
HERE Credentials を設定します
HERE SDK を使用する場合は、一連の資格情報 でアプリケーションを認証する必要があります。
情報
ヒント : 「主な概念 」セクションでは、 HERE SDK を初期化するためのその他の方法を見つけることができます。
資格情報を手元に用意したら、HERE SDK を初期化する際に、プログラムで資格情報セットを追加します (次のステップを参照) 。
注 : 資格情報は 、アプリのパッケージ名またはアプリケーション ID には関連付けられていませんが、資格情報の取得に使用されたアカウントには関連付けられています。 複数のアプリに同じ資格情報を使用する予定の場合は 、システム内のアプリを差別化する範囲を設定する必要があります。
HERE SDK の初期化
HERE SDK は自動的には初期化されません。 代わりに、 HERE SDK を初期化する時点を自由に決定できます。 初期化はメインスレッドで同期的に行われ、約 100 ミリ秒かかります。
注
HERE SDK が無効であっても、資格情報の初期化に成功します。 資格情報が有効かどうかを確認するには、フィーチャエンジンを試すことをお勧めします。 資格情報が無効な場合、専用の 列挙型 (enum) 値エラーが発生します。 一部の機能では、他の機能よりも多くの権限が必要になる場合があります たとえば、 Explore Edition 用に取得した資格情報をOfflineSearchEngine と併用すると、Explore Edition のサブセットに含まれないエラーが発生します。
HERE SDK の機能を使用する前に、次のメソッドを実行して HERE SDK を初期化します。
private void initializeHERESDK() {
String accessKeyID = "YOUR_ACCESS_KEY_ID";
String accessKeySecret = "YOUR_ACCESS_KEY_SECRET";
SDKOptions options = new SDKOptions(accessKeyID, accessKeySecret);
try {
Context context = this;
SDKNativeEngine.makeSharedInstance(context, options);
} catch (InstantiationErrorException e) {
throw new RuntimeException("Initialization of HERE SDK failed: " + e.error.name());
}
}
キーとシークレットの正しい資格情報を入力してください。 を呼び出すことで、 makeSharedInstance()
HERE SDK を使用するために必要なものをすべて初期化できます。 HERE SDK のコアクラスが呼び出され SDKNativeEngine
ます。 ボンネットの下では、このインスタンスは HERE SDK によって提供される他のエンジンによって使用されます。
メインスレッドでこのコードを呼び出してください。
注
4.12.1.0 よりも前の古い HERE SDK バージョンから移行する場合は、AndroidManifest
から資格情報 タグも削除してください ( 存在する場合 )。
初期化では、android.content.Context
を設定する必要があります。 ApplicationContext
を設定することもできますが、必須ではありません。 Context
は 、マップキャッシュへのデフォルトパスを内部的に設定する場合にのみ必要です。
注
4.12.1.0 よりも前の古い HERE SDK バージョンから移行する場合 は、まずファイルAndroidManifest
から資格情報 タグ ( 存在する場合 ) を削除してください。 次に、初期化を上記の 2 つの手順に変更します。
以下に、レイアウトから MapView
にアクセスする前に、 MainActivity
の onCreate()
メソッドで initializeHERESDK()
を呼び出す方法の例を示します。
initializeHERESDK()
と同様に、 HERE SDK を廃棄してリソースを解放することもできます。
private void disposeHERESDK() {
SDKNativeEngine sdkNativeEngine = SDKNativeEngine.getSharedInstance();
if (sdkNativeEngine != null) {
sdkNativeEngine.dispose();
SDKNativeEngine.setSharedInstance(null);
}
}
以下に 、MainActivity
の onDestroy()
メソッドでdisposeHERESDK()
を呼び出す方法の例を示します。
情報
ヒント : 「主な概念 」セクションでは、 HERE SDK を初期化するためのその他の方法を見つけることができます。
マップ ビューを追加します
SDK がプロジェクトに統合され、必要な権限と資格情報が追加されたので 、新しいインスタンスMapView
を追加できます。
注
Explore Edition のマップ ビューが HERE Rendering Engine でレンダリングされます。 リソースに制約のあるデバイス用に最適化された特殊な軽量レンダリングアーキテクチャが、 Lite Edition の一部として利用できます。
MainActivity
のレイアウトファイル (通常はactivity_main.xml
という名前 )を開き、「 Hello World 」TextView
を削除します( Android Studio のウィザードを使用した場合)。 デフォルトでは、マップ ビューを配置できるConstraintLayout
が作成されました。 他のすべてのレイアウトの親も適しています。 次のコードの追加します
<com.here.sdk.mapview.MapView
android:id="@+id/map_view"
android:layout_width="match_parent"
android:layout_height="match_parent">
</com.here.sdk.mapview.MapView>
ConstraintLayout
には 、フラットなビューレイヤーを提供し、Android Studio のレイアウト エディターとうまく連携するという利点がありますが、これはすべてユーザー次第ですSDK MapView
は、他の Android View
とまったく同じように動作します。
レイアウトファイルからマップ ビューを作成します。 これも初期化する必要があります。 これを行うには、MainActivity
(またはマップ ビューを表示したい他の Activity
) の メソッドonCreate()
を次のように更新します。
private MapView mapView;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
initializeHERESDK();
setContentView(R.layout.activity_main);
mapView = findViewById(R.id.map_view);
mapView.onCreate(savedInstanceState);
}
MapView
が未解決のシンボルであるというエラーが表示されるため、Autocompleteホットキーを使用して com.here.sdk.mapview.MapView
をインポート リストに追加するか、手動で追加します
注 : 追加の初期化タスクを実行するには、mapView.onCreate()
を呼び出すことが重要です。 そうしないと、マップはレンダリングされません。 複数 のインスタンスMapView
を 1 つの画面に作成して、同じレイアウトの一部としてレンダリングできます。
initializeHERESDK()
では、setContentView()
が呼び出される前に HERE SDK を初期化します。 レイアウトでMapView
を使用するので、 HERE SDK を事前に初期化する必要があります。
マップ シーンをロードします
デバイスの画面にマップを表示する前に、マップ データのレンダリング方法を決定する必要があります。 そのため、マップの外観をカスタマイズできるようにするシーンを非同期でロードする必要があります。 シーンをロードすると、 SDK に付属しているデフォルトのマップスタイルのいずれかが使用されます。
マップ シーンの読み込みは 、いくつかのコード行を追加することで、クラスMainActivity
から行うことができます。 たとえば、次のメソッドを追加し、アクティビティが作成され、要求されたすべての Android 権限が付与されたときに呼び出します。
private void loadMapScene() {
mapView.getMapScene().loadScene(MapScheme.NORMAL_DAY, new MapScene.LoadSceneCallback() {
@Override
public void onLoadScene(@Nullable MapError mapError) {
if (mapError == null) {
double distanceInMeters = 1000 * 10;
MapMeasure mapMeasureZoom = new MapMeasure(MapMeasure.Kind.DISTANCE, distanceInMeters);
mapView.getCamera().lookAt(
new GeoCoordinates(52.530932, 13.384915), mapMeasureZoom);
} else {
Log.d("loadMapScene()", "Loading map failed: mapError: " + mapError.name());
}
}
});
}
onCreate()
で説明したように、上記のコードを追加した後で、未解決のパッケージを解決する必要があります。
Android 権限が付与されたら、onCreate()
内から loadMapScene()
を呼び出します (またはサンプル アプリに示されているように)。
...
loadMapScene();
...
注
この例のソース コードには、Android の権限処理に必要な定型コードを避けるためのPermissionsRequestor
という便利なクラスがあります。すでに説明したように、独自のアプリケーションの権限を別の方法で処理することもできます。 権限の処理方法については、 HERE SDK 固有の要件はありません。 ほとんどのアプリ例では特別な権限は必要ないため、権限の処理は必須ではありませんが、適切な習慣と考えられています。
HERE SDK で利用できるほとんどのコールバックと同様に、onLoadScene()
は、シーンの読み込みが完了するとメインスレッドで呼び出されます。 MapError
が null でない場合、エラー内容が示されます。
MapView
からCamera
にアクセスして、マップを中央に配置する場所などのカスタムマップパラメータを設定したり、カメラから地球までの距離で指定されたズーム レベルを設定したりできます。 インスタンスが使用可能になるとすぐにMapView
Camera
を設定できます。 ただし、変更内容は onLoadScene()
が完了した後にのみ有効になります。 一般的に、シーンがロードされるまでマップ操作を待機することをお勧めします。 とえば、カメラ操作はシーンがロードされるまでキューに入れられる一方、他の操作はマップ シーンがないとまったく効果がない可能性があります。
演習として、上記のマップスタイルを次のように置き換えることができます。 MapScheme.SATELLITE
何を手に入れますか? 通常 の夜間 の設定など、他の地図設定も試してみてください。
最後に、アクティビティの有効期間が終了した時点で清掃することをお勧めします。 HERE SDK for Android は mapView.onDestroy()
、 SDKNativeEngine.getSharedInstance().dispose()
上記の方法を提供し、残りのすべてのリソースを安全に解放します。
アプリが何らかの方法でシャットダウンしている場合 、 を廃棄する SDKNativeEngine
ことは必須ではありませんが、これを行っても害はありません。また、進行中の要求をキャンセルして HERE SDK サービスをシャットダウンすることをお勧めします。 一方、アクティビティの 1 つのみが削除され、アプリの他の部分がまだ HERE SDK を必要とする場合は、 HERE SDK を早期に廃棄しないように注意してください。 一般的に、 HERE SDK を Activity
個別に初期化 / 廃棄することもできます。
さらに、 Activity
が一時停止しているときにマップ ビューのレンダリングを一時停止し、マップ ビューインスタンスの状態を保存することをお勧めします。
@Override
protected void onPause() {
mapView.onPause();
super.onPause();
}
@Override
protected void onResume() {
mapView.onResume();
super.onResume();
}
@Override
protected void onDestroy() {
mapView.onDestroy();
disposeHERESDK();
super.onDestroy();
}
@Override
protected void onSaveInstanceState(@NonNull Bundle outState) {
mapView.onSaveInstanceState(outState);
super.onSaveInstanceState(outState);
}
mapView.onSaveInstanceState(outState)
を呼び出すと、マーカーやポリラインなど、マップに追加されたすべてのマップ アイテムは、画面の向きが変わっても、バンドルされた状態に基づいて維持されます。ただし、向きの変更ごとに新しいマップ ビュー インスタンスを作成する場合は、必ず HERE SDK を再初期化して mapView.onSaveInstanceState(null)
を呼び出してください。新しい HERE SDK インスタンスまたは同様に新しい インスタンスMapView
は、バンドルされた状態と併用することはできません。 以前のインスタンスに基づいて作成されます。
次に、アプリをビルドして実行します。 すべて問題が解決した場合は、ビューの領域全体をカバーする HERE マップが表示されます。 おめでとうございます。 HERE SDK for Android の使用に関する最初のステップを習得しました。 ありがとうございました。
スクリーンショット: メインマップ スキームの表示
スクリーンショット: 衛星マップ スキームの表示 Android の権限を処理します
HERE SDK では、マップ ビュー を表示するときに、アプリケーション側での権限の処理は必要ありません。 以下の権限が AndroidManifest.xml
に自動的にマージされます。
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
AndroidManifest.xml
では、必要な権限について上記の権限を明示的に付与するために、最上位の要素manifest
内に追加することもできます ( オプション ) 。
注
これらの権限は機密ではなく、システムのインストール時にただちに付与されます。 HERE SDK がインターネットに接続できるようにする必要があるため、これらの権限は常に必要です。 これらの権限を処理する必要はありません。また、権限の処理方法については、 HERE SDK 固有の要件はありません。
ただし、ユーザーは、インストール後にデバイスのアプリ設定を使用して任意の権限を拒否できます。 そのため、アプリの起動時にユーザーに通知するために、アプリに権限処理を追加することをお勧めします。
付属のサンプルアプリでは、 便利なクラス を使用してボイラープレートのコードから離れた場所でこれを行う方法を示しています。 もちろん、独自のアプリケーションの権限は別の方法で処理できます。また、権限を削除することもできます。 インターネット接続が利用できない場合、ほとんどの HERE SDK サービスがこのメッセージを適切なエラーメッセージで表示します。
ビデオチュートリアル
Twitch 用に録画されたライブ コーディング シリーズで HERE チームをフォローし、現在 YouTube で視聴できるようにしています。
YouTube で HERE SDK とコーディングを行っている様子をご覧ください。 ライブコーディングについては、次のトピックを参照してください。
一部のビデオは HERE SDK の以前のバージョンで作成されたものであるため、コードの一部が再コーディング時以降にわずかに更新されている可能性があります。 このガイドおよび付属のサンプルアプリを参照して、最新バージョンの HERE SDK を利用してください。
トラブルシューティング
問題が発生した場合 は、まず最小要件とサポートされているデバイスを確認してください。
- 空白の白いマップのみが表示されます。 ご利用の HERE Credentials が有効で、 上記の「利用開始 」セクションの説明に従って設定されていることを確認してください。 また、ご利用のデバイスがインターネットに接続できることを確認してください。 インターネット接続が遅い場合、最初にロードされたマップのタイルが表示されるまでにしばらくかかることがあります。 また、デバイスの時刻が正しく設定されていることを確認してください。 まれに、デバイスの時間が正しく設定されていないと、一部のバックエンドサービスで認証の問題が発生する可能性があります。
- ログに「No map content will be displayed until valid config is provided.」と表示されます。 コードが実際に
loadScene()
を呼び出していることを確認 - アプリがクラッシュし、ログに「 cl_magma - could not load the default shader」と表示されます。 お使いのデバイスは OpenGL ES 3.0 をサポートしている必要があります シミュレータを実行している場合は、 [ Setting ] 、 [ Advanced ] 、 [OpenGL ES API level ] の順に選択して、エミュレータの設定を編集します。 「Autoselect」に設定されている場合は、「 Renderer Maximum 」に変更してください。 この問題は主に Windows マシンで発生します。
- ':app@debug/compileClasspath' の依存関係を解決できません : 次のアイテムが見つかりませんでした : hersdk -your_sdc_version: HERE SDK AAR がアプリケーションのビルドグラデーションファイルの名前と一致することを確認してください。 注 : これ は、バージョンを明示的に参照している場合にのみ必要です。 上記の手順を実行する場合
*.aar
、任意のバージョンに一致するようにワイルドカードとして使用するため、この操作を行う必要はありません。 - 「パッケージの Android SDK プラットフォームのライセンスが受け入れられません」というエラーが表示されます。または、次のようなエラーが表示されます。 必要なツールをインストールし、ライセンスボタンをクリックするか 、または
sdkmanager --licenses
を呼び出して 端末からcd /d "%ANDROID_SDK_ROOT%/tools/bin"
などの操作を行って、すべての Android ライセンスを受け入れたことを確認してください。 - クラッシュログに次の内容が記録されています。 "Exception was thrown in Java and it was not handled " : HERE SDK は、コールバック内のアプリ側でスローされたランタイム例外を処理できません。 このような場合、このエラーログが表示されます。 つまり、アプリケーションが処理する HERE SDK コールバックの 1 つで、コードが例外をスローします。
- キャッシュのロックによりクラッシュが発生しています : エラー
Storage.LevelDB
またはエラー FAILED_TO_LOCK_CACHE_FOLDER
が原因でアプリケーションがクラッシュした場合 は、この指示に従って、このようなクラッシュが再度発生しないようにします。 - マップが表示されないか、 HERE SDK の呼び出しでは、何も起きない。 「 These credentials do not authorize access 」というログメッセージが表示された場合は、資格情報 が有効ではありません。 資格情報 のワーキングセットを使用していることを確認してください。 3.x エディションの資格情報 には互換性がありません。 Lite Edition またはExplore Edition の資格情報は、 Navigate Edition と互換性がありません。
- マップ ビューにグラフィカルな不具合が表示されます。 一部の Android バージョンでは、この問題が発生する可能性があり、
MapRenderMode.texture
を使用して修正できます。 詳細については、マップ ガイドを参照してください。
サポートが必要な場合
この HERE 製品またはその他の 製品についてサポートが必要な場合は、次のいずれかのオプションを選択します。