Mapbox Maps SDK for Android/iOSのサンプルの実行環境を作る

はじめに

この記事はMapbox Maps SDK for Android/iOSに同梱されているサンプルコードが実行できる環境を構築する方法について解説します。Android StudioおよびXcodeはインストール済みであることが前提です。また、Mac環境を想定しています。

なぜSDKのサンプルを手元で実行できる状態にするの？

SDKのサンプルを手元で実行できる状態にしていると嬉しいことがいくつかあります。

サイトには掲載されていないサンプルを試せる

以下のサイトでAndroid, iOSそれぞれのExamplesを参照することができます。

しかし、ここに掲載されているサンプルはSDKに同梱されているサンプルのごく一部です。手元で実行できる状態にすることですべてのサンプルを確認することができます。

SDKのコードにシームレスにアクセスできる

サンプルの気になる部分にブレークポイントを設定し、そのままステップインでSDKのコードに入れます。ある機能を使っていて、もっと便利な使い方はないかな？とかどうやって動いているんだろう？と思ったときに気軽にSDKのコードが確認できます。

スムーズにサポートを受けられる

思ったとおりに動かないとき、自分のアプリケーションと同じ機能を使っているサンプルで再現するかどうかが簡単に試せます。再現する場合、その再現方法をサポートに伝えると開発チームはスムーズにデバッグに取り掛かることができます。

前準備

シークレットトークンの作成

Mapbox Maps SDK for Android/iOSの依存関係のうち、Mapboxのプライペートリポジトリからダウンロードするものがあります。その際にアクセストークンが必要となるため作成します。

1. Mapboxアカウントを作成する
2. https://account.mapbox.com/ にアクセスする
3. Tokensを選択し、Access tokensページに移動
4. 「Create a token」ボタンをクリック
5. Nameに任意の名前を入力
6. Public scopesのチェックをすべて外し、Secret Scopesの「DOWNLOADS:READ」のみを選択
7. 「Create token」ボタンをクリック
8. トークン一覧画面にトークンが表示されているので、コピーして安全な場所に保存

Secret Scopesを含むアクセストークンは「シークレットトークン」と呼ばれます。アカウントに関する操作を許可するトークンであるため、外部に公開してはいけません。また、シークレットトークンは「sk.」で始まる文字列となるため、パブリックトークン（「pk.で始まる」）と区別できます。

シークレットトークンは作成直後にしか表示されないので、このタイミングで確実に保存してください。

パブリックトークンの取得

パブリックトークンはアプリケーションが地図データを取得する際に使用します。Default public tokenというデフォルトで用意されているものがあるので、Access tokensページで取得しましょう。

パブリックスコープのみをもつトークンを作成すると、パブリックトークンになります。実際にアプリケーションをリリースする際にはアプリケーションごとにスコープを限定した個別のトークンを準備することをおすすめします。分けておくとトークン毎に使用量等が参照できて便利です。何らかの問い合わせをMapboxに行う際も、どのアプリケーションでのアクセスかが判別しやすく問題解決がスムーズになる可能性があります。また、Mapbox GL JS向けにはリファラでアクセスを制限するURL restrictionsがトークン毎に設定できます。

手順

それではいよいよAndroid/iOSそれぞれのサンプルが実行できる状態にしてきます！

Android

シークレットトークンの設定

~/.gradle/gradle.propertiesに以下の行を追加します。

SDK_REGISTRY_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN

注意：Mapbox SDK for AndroidのInstallaionに記載されている手順（SDKを自分のアプリで使用する際の手順）ではMAPBOX_DOWNLOADS_TOKENという変数名が使用されており、名称が異なります。

コードの入手

GitHubからリポジトリをクローンします。今後自分のアプリケーションで使用する予定のバージョンをチェックアウトすると良いでしょう。ここでは執筆時点で最新の安定版のv10.13.0を使用します。

% git clone https://github.com/mapbox/mapbox-maps-android
% cd mapbox-maps-android
% git checkout v10.13.0

実行

とりあえず一旦実行します。以下のような画面が表示されます。

パブリックトークンの設定

この状態で、例えば「Creating a map view」をタップしても地図が表示されません。これはパブリックトークンが設定されておらず、地図データが読み込めないためです。

一度実行すると以下のようなapp/src/main/res/values/developer-config.xmlというファイルが作成されており、ここにパブリックトークンが設定できます。YOUR_MAPBOX_ACCESS_TOKEN_GOES_HEREという文字列を自分のパブリックトークンに置き換えてください。

<?xml version="1.0" encoding="utf-8"?>
    <resources xmlns:tools="http://schemas.android.com/tools">
    <string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN_GOES_HERE</string>
</resources>

再度実行すると地図が表示されます。

iOS

シークレットトークンの設定

~/.netrcに以下の内容を記述します。

machine api.mapbox.com
  login mapbox
  password YOUR_SECRET_MAPBOX_ACCESS_TOKEN

コードの入手

GitHubからリポジトリをクローンします。今後自分のアプリケーションで使用する予定のバージョンをチェックアウトすると良いでしょう。ここでは執筆時点で最新の安定版のv10.13.1を使用します。

% git clone https://github.com/mapbox/mapbox-maps-ios
% cd mapbox-maps-ios
% git checkout v10.13.1

実行

mapbox-maps-ios/Apps/Apps.xcworkspaceをダブルクリックするとXcodeが起動します。とりあえず一旦実行します。以下のような画面が表示されます。

パブリックトークンの設定

この状態で、例えば「Display a map view」をタップしても地図が表示されません。これはパブリックトークンが設定されておらず、地図データが読み込めないためです。

Androidとおなじくパブリックトークンを設定する必要がありますが、iOSは2通りの設定方法があります。

1. Info.plistで設定する方法
2. .mapboxを作成する方法

それぞれ見ていきましょう。

Info.plistで設定する方法

mapbox-maps-ios/Apps/Examples/Examples/Info.plistを開き、MBXAccessTokenに自分のパブリックトークンを入力します。

     <key>MBXAccessToken</key>
     <string></string>

Xcode上で入力するのもOKです。

.mapboxを作成する方法

~/.mapboxというテキストファイルを作成し、その中にパブリックトークンだけを記述して保存します。

いずれの方法でも以下のように表示されればOKです。

まとめ

この記事ではMapbox Maps SDK for Android/iOSのサンプルを動かす方法を解説しました。簡単に動かせて、たくさんのサンプルを試せるので非常にお得だと思います。

特にスムーズにサポートを受けられるという文脈では、SDKのバグと思しき場合にサンプルを使って再現環境をご提供いただけるとサポートチームは非常に助かります。一般にバグ発生状況をヒヤリングしてもなかなか再現が難しく、利用側で再現方法を確立してもらえると解析がスムーズに進みます。

また、サポートを受ける際には有償サポートへの加入をおすすめします。Mapboxは無償サポートプラン（ディベロッパープラン）もありますが、質問への回答時間に対するSLAがありません。つまり、ベストエフォート型なので、返信までに非常に時間が掛かるケースがあります。これに対し、一番安価なエッセンシャルプランに加入すると３営業日以内に一時応答というSLAがあるので安心です。サポートプランの内容やお問い合わせ先についてはこちらのサイトをご参照ください。