カスタムマップカタログはNavigateライセンスでのみ使用できます。

HERE SDKは、カスタムマップカタログを使用するように設定できます。このため、カスタマイズされたマップ データで HERE SDK を使用できます。たとえば、カスタム道路ネットワークや施設情報を含めることができます。

HERE SDK では、標準の地図カタログと同様に、オンライン モードとオフライン モードの両方でカスタム マップ データを使用できます。

カスタム マップ形状や POI (施設情報) を使用してカスタム地図カタログを作成するには、HERE のサポートと、HERE との追加契約が必要です。詳細については、HERE担当者にお問い合わせください。

この手順が完了したら、次のコード例を使用して、カスタム マップ データをアプリケーションに読み込んで使用できます。

CatalogConfiguration を使用してマップ データをカスタマイズする

デフォルトでは、HERE SDK は特殊なマップ フォーマットにコンパイルされたマップ データを使用します。このデータは、その場でマップキャッシュにダウンロードされるか、オフライマップを使用して事前にダウンロードできます。HERE SDK (Navigate) では、OCMマップカタログ形式を使用します。

地図カタログは、HERE Resource Name (HRN) によって識別されます。デフォルトでは、HERE SDK には HRN が「hrn:here:data::olp-here:ocm」の OCM カタログが含まれています。カタログはすべて、道路形状と属性を持つマップオブジェクトを含むレイヤーのコレクションです。レイヤーのコンテンツは、効率的な検索、マップ表示、ルート検索、マップ マッチング、運転者への警告およびその他のデータのためにタイルに分割されています。コアマップコンテンツは地域マップに分割されていますが、常に単一のグローバルマップとして使用できます。その他のコンテンツは、主に世界各地の専用マップで提供されます。

このデータは、HERE と一緒にカスタマイズでき、カスタム カタログを介してアクセスできるようなります。カタログの準備ができたら、HRN の値と範囲を指定して、カタログにアクセスできます。HRN カタログ ID とスコープの設定について、詳しくはこちらを参照してください。

さらに、ルート検索や検索などの特定の HERE オンライン サービスを、オフライン マップ データのデータと一致させることもできます。この場合、HERE はお客様の会社のためだけに調整された HERE サービスをホストする、カスタム バックエンドの設定を支援します。このようなカスタムバックエンドは、Map[EngineBaseURL, ​EngineOptions]から指定できます。その結果、SearchEngineのようなクラスを使用して実行されたすべてのリクエストが、指定されたバックエンドを使用するようになります。

注

セルフホスティングによるカスタム バックエンドの設定は任意であり、カスタムルート設定やカスタム検索などのサービスをオンラインで使用する場合にのみ必要です。

• カスタムOCMデータがMapDownloaderを介してデバイスにインストールされている場合や、完全にキャッシュに保存されている場合、カスタムバックエンドのセルフホスティングを必要とせずに、OfflineRoutingEngineを介したカスタムルート設定などの機能がオフラインで完全にサポートされます。
• オンラインで使用するには、サービスにカスタム バックエンド URL を指定する必要があります (以下を参照)。カスタム バックエンドを使用した場合のみ、RoutingEngine を使用してカスタムのルートをオンラインで作成できます。SearchEngine を介したオンライン施設情報などの他のサービスでも同様です。

HERE プラットフォームでカスタム カタログが利用可能な場合は、カスタム CatalogConfiguration を使用してマップ データを読み込んで使用できます。CatalogConfiguration とオプションのカスタム バックエンド URL は、設定が保持されないため、HERE SDK を初期化するたびに、SDKOptions で指定する必要があります。

以下のコード スニペットは、その方法を示しています。

func initializeHERESDKWithCustomCatalogConfiguration() {
    // Note: Each catalog configuration may require special credentials.
    // For tips on how to secure setting credentials from code, please check our Developer Guide.
    let accessKeyID = "SET_YOUR_ACCESS_KEY"
    let accessKeySecret = "SET_YOUR_ACCESS_KEY_SECRECT"

    let authenticationMode = AuthenticationMode.withKeySecret(accessKeyId: accessKeyID, accessKeySecret: accessKeySecret)
    var options = SDKOptions(authenticationMode: authenticationMode)

    options.catalogConfigurations = getCustomCatalogConfiguration()

    // Optionally, specify a custom routing backend that matches the custom OCM map for use with the (online) RoutingEngine.
    options.customEngineOptions = getCustomBackends()

    do {
        try SDKNativeEngine.makeSharedInstance(options: options)
    } catch let e as InstantiationErrorCode {
        fatalError("Initialization of HERE SDK failed: \(e.localizedDescription)")
    } catch let error {
        fatalError("Initialization of HERE SDK failed: \(error.localizedDescription)")
    }

    SDKNativeEngine.sharedInstance?.setAccessScope(scope: getCustomCatalogScope())
    print("Activated custom OCM catalog.")
}

func getCustomCatalogConfiguration() -> [CatalogConfiguration] {
    var catalogConfigurations = [CatalogConfiguration]()

    // We want to start with the latest catalog version.
    let ignoreCachedData = true
    let versionHint = CatalogVersionHint.latest(ignoreCachedData: ignoreCachedData)

    let customHRN = "hrn:here:data::olp-namespace:your-company-ocm"
    let customOCMCatalog = DesiredCatalog(hrn: customHRN, version: versionHint)
    catalogConfigurations.append(CatalogConfiguration(catalog: customOCMCatalog))

    // Optionally, set a patch HRN to enable incremental map updates.

    return catalogConfigurations
}

// Note that self-hosting is optional.
func getCustomBackends() -> [EngineBaseURL: EngineOptions] {
    var engineOptions = EngineOptions()
    engineOptions.customBaseUrl = "https://your-company.router.hereapi.com"
    return [.routingEngine: engineOptions]
}

private func getCustomCatalogScope() -> String {
    return "hrn:here:authorization::olp-here:project/your-company-hsdk";
}

最初に、開始するカタログ バージョンを指定する必要があります。DesiredCatalog は、HERE プラットフォームでカタログを識別する方法を示します。開発者は、カタログのHERE Resource Name (HRN) と、希望するバージョンのCatalogVersionHintも指定できます。設定が完了すると、MapUpdaterを使用して定期的な地図更新を利用できます (すべてのライセンスで使用できるわけではありません)。すると、このカタログバージョンが、MapVersionHandleの一部として表示されます。

カスタム OCM マップの地図の差分更新を有効にする場合は、オプションで catalogConfiguration.patchHrn = "hrn:here:data::olp-namespace:__your-patch-hrn-123__" を設定するようにしてください。プロジェクトに適したパッチ HRN 値を使用します。通常、地図の差分更新はデフォルトで有効になっていますが、CatalogConfigurationが設定されている場合は動作が異なります。patchHrnをnullに設定すると地図の差分更新は無効になり、新しく作成されたCatalogConfigurationの場合は、これがデフォルトの状態になります。

カスタム マップ データの詳細については、HERE Map Attributes API を参照してください。HERE Map Attributes API を使用すると、すべての HERE Map Data と顧客のプライベート マップ データにアクセスできます。

セルフホスト型サービス

customEngineOptions (上記を参照) を使用すると、HERE SDKのサービスをセルフホストできます。たとえば、HEREサービスのバックエンドを独自のサーバーにミラーリングし、Map[EngineBaseURL, ​EngineOptions]からURLを設定してアクセスできます。

独自のバックエンドへのアクセスは、認証やプロキシ サポートを含む、設定可能なエンドポイント (こちらを参照) を使用して、完全にカスタマイズできます。

この手順は、HERE SDK のオンライン機能エンジンを使用できるようにする場合にのみ必要です。たとえば、カスタム POI レイヤーを挿入する場合は、すでに OfflineSearchEngine を使用してこのカスタマイズされたマップ データを検索できます。または、MyPlaces APIを使用して、実行時にデータを挿入したり、独自の REST コードと独自の (リモート) データベースまたはサーバーを使用してアプリ内でリクエストを処理したりすることができます。一方、たとえば SearchEngine を活用する場合は、セルフホスティングを検討します。これは、各オンライン リクエストはセルフホストされたバックエンドで処理する必要があるためです。ただし、セルフホスティングの最も一般的なユースケースは、HERE SDK が開始するリスエストに応答するサーバーへのアクセスを完全に制御することです。

これにはかなりの労力が必要であることに注意してください。HERE SDK のサポート チームに連絡して、設定と可能な代替案について話し合うことをお勧めします。

注

ここで選択したオンライン サービスを独自のバックエンドでホスティングしていても、カスタム OCM マップ カタログをバックエンド (オンプレミス) でホストすることも可能です。セルフホスト型マップは、すべての HERE サービスをファイアウォールの内側にある独自のネットワークに移動する必要がある場合に役立ちます。これには、DS プロキシを使用する必要があります (以下を参照)。このようなオプションの詳細については、HERE 担当者にお問い合わせください。

DS プロキシの設定

デフォルトでは、データ サービス プロキシ (dsProxy) は https://direct.data.api.platform.here.com/direct/v1 に設定されており、HERE プラットフォーム リクエストの前置表記として使用されます。カスタム カタログを使用する場合、HERE SDK は内部的に Lookup リクエストを実行して、カタログにアクセスするための対応する URL を検索します。この追加リクエストを回避するには、HERE SDK を初期化するときに事前に URL を設定することをお勧めします。

たとえば、カスタム カタログの有効な dsProxy は、「https://data.api.platform.yourcompany.com/direct/v1」のようになります。

Map[EngineBaseURL, ​EngineOptions]を使用してカスタムプロキシを設定し、HERE SDKを初期化するときにcustomEngineOptionsとしてSDKOptionsに渡します。

さらに、/orセルフホスト型バックエンドやセルフホスト型地図 (オンプレミス) の場合は、Authentication.authenticate(…)を呼び出して認証トークンを手動で取得する必要があります。HERE SDK を初期化する前に、AuthenticationMode.withToken(…) を介してトークンを設定します。

注

dsProxy はネットワーク プロキシ設定ではありません。カタログにアクセスするための URL のみを指定します。カスタム カタログ設定 (上記を参照) を読み込まない場合は、この設定を無視してかまいません。

カスタム カタログを日本と一緒に使用する

日本の HERE チームが資格情報を有効にすると、日本地図の HRN 文字列 "hrn:here:data::olp-here:ocm-japan" を DesiredCatalog インスタンスに設定できるようになります。次に、上で示したように新しい CatalogConfiguration を作成して sdkOptions.catalogConfigurations に渡します。

以下の手順はカスタム カタログを使用している場合にのみ関連します。カスタム カタログを使用しない場合、詳細な日本地図を表示するには有効化された資格情報のみが必要です。

日本のカタログは単独で設定することも、全世界をカバーするデフォルトの地図と一緒に設定することもできます。デフォルトでは、これは HRN 値 ("hrn:here:data::olp-here:ocm") で識別される OCM です。これをカタログのカスタム HRN に置き換えます。日本のカタログと全世界のカタログを一緒に使用する方法を以下に示します。

func getDefaultCatalogConfigurationWithJapan() -> [CatalogConfiguration] {
    var catalogConfigurations = [CatalogConfiguration]()

    // We want to start with the latest catalog version.
    let ignoreCachedData = true
    let versionHint = CatalogVersionHint.latest(ignoreCachedData: ignoreCachedData)

    // An OCM catalog is required, typically, use your own catalog HRN here.  
    let defaultOCMHRN = "hrn:here:data::olp-here:ocm"
    let defaultOCMCatalog = DesiredCatalog(hrn: defaultOCMHRN, version: versionHint)
    let defaultCatalogConfiguration = CatalogConfiguration(catalog: defaultOCMCatalog)
    catalogConfigurations.append(defaultCatalogConfiguration)

    // Specify a rich Japan map, requires special HERE credentials.
    // If the credentials are not enabled for access, the map falls back to the Japan base map.
    let japanOCMHRN = "hrn:here:data::olp-here:ocm-japan"
    let japanOCMCatalog = DesiredCatalog(hrn: japanOCMHRN, version: versionHint)
    let japanCatalogConfiguration = CatalogConfiguration(catalog: japanOCMCatalog)
    catalogConfigurations.append(japanCatalogConfiguration)

    // Optionally, set a patch HRN to enable incremental map updates.

    return catalogConfigurations
}

日本地図について地図の差分更新を有効にする場合は、オプションで catalogConfiguration.patchHrn = "hrn:here:data::olp-here:ocm-japan-patch" を設定するようにしてください。通常、地図の差分更新はデフォルトで有効になっていますが、CatalogConfiguration が設定されている場合は動作が異なります。.
patchHrn を nil に設定すると地図の差分更新は無効になり、新しく作成された CatalogConfiguration の場合は、これがデフォルトの状態になります。

便宜的に、次のようにデフォルト設定を取得することもできます。

var catalogConfigurations = [CatalogConfiguration]()

// By calling getDefault() you will automatically get the latest version
// at the time when the HERE SDK was built.

let defaultConfiguration = CatalogConfiguration.getDefault(catalogType: CatalogType.optimizedClientMap)
catalogConfigurations.append(defaultConfiguration)

// Specify a rich Japan map, requires special HERE credentials.
// Note: If the credentials are not enabled for access, the map falls back to the Japan base map.
let japanConfiguration = CatalogConfiguration.getDefault(catalogType: CatalogType.optimizedClientMapJapan)
catalogConfigurations.append(japanConfiguration)

次に示すように、デフォルト カタログの詳細を取得することもできます。

let catalogJapan = CatalogConfiguration.getDefault(catalogType: CatalogType.optimizedClientMapJapan)
let catalogIdentifier = catalogJapan.catalog.id

print("Japan HRN: \(String(describing: catalogIdentifier.hrn))")
print("Japan version: \(String(describing: catalogIdentifier.version))")