アンドロイド 用 BeaconPlus SDK ドキュメンテーション バージョン 1.1 2014 年 11 月 PinMicro 株 式 会 社 機 密 専 有 配 布 制 限 :このドキュメントは PinMicro 株 式 会 社 の 財 産 である PinMicro 株 式 会 社 の 書 面 に よる 事 前 の 承 諾 なしに 文 書 の 全 部 あるいは 一 部 を 使 用 すること 複 製 すること 複 写 する こと あるいは 第 三 者 にいかなる 方 法 によっても 開 示 することは 禁 じられている 質 問 がある 場 合 には 当 社 (support@pinmicro.com)までご 連 絡 ください
改 訂 履 歴 日 時 バージョン 内 容 担 当 者 2014 年 8 月 13 日 0.4 初 版 Jithin 2014 年 8 月 22 日 1.0 レビューポイント 反 映 Jithin 2014 年 11 月 3 日 1.1 エラーコード 更 新 Jithin 1
レビュー 詳 細 日 時 バージョン 担 当 者 レビュー 担 当 者 2014 年 8 月 13 日 0.4 Jithin Nidheesh 2014 年 8 月 22 日 1.0 Jithin Nidheesh 2014 年 11 月 3 日 1.1 Jithin Nidheesh 2
目 次 1 はじめに... 4 1.1 本 文 書 の 目 的... 4 1.2 本 文 書 のスコープ... 4 2 アクロニム... 4 3 BeaconPlus SDK 概 要... 4 4 SDK のセットアップ... 5 4.1 要 件... 5 4.2 BeaconPlus SDK を Eclipse プロジェクトに 統 合 する 方 法... 5 5 SDK の 使 用 方 法... 9 6 アクセストークンによる 認 証... 11 6.1 アクセストークンの 入 手... 11 7 コールフロー ダイヤグラム... 13 8 エラーコード... 14 9 文 献... 15 3
1 はじめに 1.1 本 文 書 の 目 的 本 BeaconPlus SDK ドキュメントは BeaconPlus SDK およびこれを Android のアプリに 統 合 する 方 法 に 関 して その 概 要 を 説 明 するものです 詳 細 な API の 仕 様 およびその 他 の 実 装 方 法 の 詳 細 については BeaconPlus API spec(http://pinmicro.com/docs/android-sdk/index.html)をご 参 照 ください 1.2 本 文 書 のスコープ Android 用 コンテクスト アウェアネス( 文 脈 認 識 )アプリケーションの 開 発 者 は まず 最 初 に 本 文 書 をお 読 みください 2 アクロニム 本 文 書 では 以 下 のアクロニムを 使 用 します アクロニム 詳 細 SDK API BLE ソ フ ト ウ ェ ア 開 発 キ ッ ト ( Software Development Kit) アプリケーションプログラムインターフェ ース(Application Programming Interface) Bluetooth Low Energy 3 BeaconPlus SDK 概 要 BeaconPlus SDK により 幅 広 い 自 由 度 をもってコンテクスト アウェアネスのアプリケーションを 開 発 することができます BeaconPlus SDK は クライアントアプリと BeaconPlus クラウドサービス 間 の 橋 渡 しとしての 役 割 を 持 ちます APP API コール BeaconPlus SDK サーバ API request API レスポンス レスポンス Beacon アッフ テ ート BeaconPlus Cloud Beacon 4
SDK は 定 期 的 にクラウドと 同 期 しており プロジェクトに 対 して 適 切 なタイミングでの 正 確 な 情 報 を 保 持 しています またすべての 内 部 ロジックを 処 理 してデバイスを 検 出 し 特 定 の 領 域 で エントリ ー と エクシット の 事 象 が 発 生 するたびにアプリに 通 知 します 4 SDK のセットアップ 本 節 では Android のアプリを 利 用 するための SDK セットアップ 方 法 を 説 明 します 4.1 要 件 BeaconPlus SDK は BLE プロトコルを 利 用 してビーコンを 特 定 するので 最 低 限 Android のバージョン 4.3 が 必 要 です ハードウェアの 仕 様 としては SDK が 以 下 のデバイス 上 だけで 動 作 していることが 必 要 です ブルートゥース 4.0 による Android 電 話 ブルートゥース 4.0 による Android タブレット 4.2 BeaconPlus SDK を Eclipse プロジェクトに 統 合 する 方 法 お 手 元 の Android アプリケーションに BeaconPlus SDK の 機 能 を 統 合 するためには Eclipse の Android プロジェクトを 設 定 する 必 要 があります Android 用 の BeaconPlus SDK は Android ライブラリープ ロジェクトとして 提 供 されています ユーザは BeaconPlus SDK をインポートして 参 照 し JAVA ビル ド パスとライブラリを 設 定 する 必 要 があります a. Eclipseを 立 ち 上 げる b. Eclipseにおいて 新 規 にAndroidアプリ プロジェクトを 作 成 し たとえば GetMeShoes などの ように 命 名 する c. BeaconPlus SDK > Import >Android > Existing Android Code Into Workspace を 選 択 してNextをクリ ック 5
d. Browseを 選 択 BeaconPlus SDKの 場 所 を 確 認 し copy project into workspace option を 選 択 し て Finishをクリックする 6
e. プロジェクトのプロパティを 更 新 する e.1. Projectを 右 クリックしてPropertiesを 選 択 project propertiesのダイアローグが 表 示 される 7
e.2. Androidを 選 択 し ライブラリセクションでAddをクリック BeaconPlus SDK projectを 選 択 してOKをクリックする f. オプション:Project > Clean とクリックして プロジェクトが 意 図 通 りに 設 定 されているかどうか 確 認 する 8
5 SDK の 使 用 方 法 a. パーミッションを 宣 言 する SDKはAndroidのいくつかの 特 色 ある 機 能 を 全 面 的 に 活 用 しているので 以 下 に 示 すパーミッシ ョンブロックがユーザのアプリであるAndroidManifest.xml に 含 まれているかどうかか 確 認 し てください <uses-permission android:name="android.permission.bluetooth" /> <uses-permission android:name="android.permission.bluetooth_admin" /> <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.write_external_storage" /> <uses-permission android:name="android.permission.read_external_storage"/> <uses-permission android:name="android.permission.access_network_state"/> <uses-permission android:name="android.permission.access_coarse_location"/> b. サービスとレシーバを 宣 言 する BeaconPlus SDKが 正 常 に 動 作 するためには ユーザのアプリであるAndroidManifest.xml 中 に 以 下 のサービスとレシーバを 追 加 しておく 必 要 があります 同 期 プロセス ネットワーク ブルートゥース 状 態 の 特 定 のために 以 下 のレシーバを 利 用 し ます <receiver android:name="com.innovature.beaconplussdk.beaconplussdk" android:enabled="true" > <intent-filter> <action android:name="com.innovature.beaconplussdk.alarm_sync_service" /> <action android:name="android.net.conn.connectivity_change" /> <action android:name="android.bluetooth.adapter.action.state_changed" /> </intent-filter> </receiver> ビーコン 検 出 プロセスには 以 下 のサービスを 利 用 します <service android:name="com.innovaturelabs.ibeacon.service.ibeaconservice" android:enabled="true" android:isolatedprocess="false" android:label="ibeacon"> </service> <service android:name="com.innovaturelabs.ibeacon.ibeaconintentprocessor" android:enabled="true"> </service> 最 後 に ユーザ アプリ 中 に 次 のメタデータを 入 れておいてください <meta-data android:name="com.google.android.gms.version" android:value="4242000"/> 9
c. SDKの 初 期 化 BeaconPlusSDKクラスは アプリとBeaconPlus SDKのインタフェースのことです a.1. ユーザがSDKに 関 係 したアクションを 実 装 する 予 定 のクラスに BeaconPlusSDKクラスをイ ンポートする import com.innovature.beaconplussdk.beaconplussdk; a.2. 以 下 のいずれかの 方 法 を 利 用 してSDKを 初 期 化 する BeaconPlusSDK sdkmanager = BeaconPlusSDK.initialize(<CONTEXT>, <SERVERURL>,<ACCESSTOKEN>,<ONINITIALIZATIONLISTNER>); BeaconPlusSDK sdkmanager = BeaconPlusSDK.initialize(<CONTEXT>, <SERVERURL>,<ACCESSTOKEN>,<LOCALE>,<ONINITIALIZATIONLISTNER>); BeaconPlusSDK sdkmanager = BeaconPlusSDK.initialize(<CONTEXT>, <SERVERURL>,<ACCESSTOKEN>,<LOCALE>,<ONINITIALIZATIONLISTNER>,<CACHEPLACE>) ; BeaconPlusSDK sdkmanager = BeaconPlusSDK.initialize(<CONTEXT>, <SERVERURL<ACCESSTOKEN>,<LOCALE>,<ONINITIALIZATIONLISTNER>,<CACHEPLACE>, <MAXCACHELIMIT>); b. OnInitializationListnerを 実 行 する OnInitializationListnerを 実 行 して SDKからの 初 期 化 コールバックを 入 手 してください OnInitialization コールバックを 実 行 することにより SDKメソッドのいくつかを 上 書 きする 必 要 があります @Override public void oninitializationerror(int arg0, String arg1) { // TODO Auto-generated method stub } @Override public void oninitializationsuccess() { // TODO Auto-generated method stub 10
} c. スキャンを 開 始 する コールによりSDKが 初 期 化 された 後 ユーザはビーコンのスキャンを 開 始 することができます boolean scanstatus = sdkmanage.startscanning(<spotnotifier>); d. SpotNotifierを 実 行 する SDKからのスキャンコールバックを 入 手 するためにSpotNotifierを 実 行 してください SpotNotifier コールバックを 実 行 することにより SDKメソッドのいくつかを 上 書 きする 必 要 があります @Override public void onspotexit(spot spot) { // TODO Auto-generated method stub } @Override public void onspotentry(spot spot) { // TODO Auto-generated method stub } @Override public void onscanerror(int errorcode, String message) { // TODO Auto-generated method stub } 6 アクセストークンによる 認 証 BeaconPlus SDK は BeaconPlus クラウド 中 に 自 分 のアカウントを 作 成 した 後 各 組 織 に 提 供 されてい るアクセストークンにより 各 ユーザを 特 定 します その 後 SDK は クラウドからのアプリ 用 のマッ チング 情 報 を 引 き 出 して タスクを 実 行 します 主 要 な 特 徴 アクセストークンは 開 発 者 を 特 定 する 鍵 の 役 割 を 果 たし クラウドからどのデータにア クセスすべきかをシステムに 知 らせます そのため 開 発 者 はログインや 認 証 のためだけに 特 別 なロジックを 実 装 する 必 要 はありません 同 一 組 織 内 では 複 数 のアプリに 対 して 同 じアクセストークンを 使 用 することができます アプリの 利 用 可 能 情 報 は 同 じであっても 無 くてもよく アプリ 開 発 者 は 自 らの 要 件 に 合 うよ うにアプリのロジックを 実 装 することができます 6.1 アクセストークンの 入 手 Innovature Technologies にお 問 い 合 わせの 際 には 下 記 の 事 項 も 併 せてお 知 らせください 組 織 名 11
住 所 連 絡 先 の 番 号 電 子 メール 12
7 コールフロー ダイヤグラム 初 期 化 アクセストークンの 認 証 Configuration API コールを 入 手 認 証 失 敗 エラーリターン 認 証 成 功 config 詳 細 のリターン スホ ットリスト API コールを 入 手 初 期 化 成 功 / 失 敗 JSON レスホ ンス スキャン 開 始 /ストッフ ヒ ーコン アッフ テ ート リターン 成 功 /エラー サーハ との 同 期 のトリカ ー スホ ットエントリ エクシット 同 期 用 に configuration API を 入 手 configuration の 詳 細 をリターン テ ータ 更 新 の 際 に getspotlist API をコール ロク 送 付 のトリカ ー JSON レスホ ンス ロク を 送 付 成 功 / 失 敗 のレスホ ンス 13
8 エラーコード 以 下 に SDK からアプリに 返 すエラーコードを 示 します エラーコード エラー 理 由 738 ネットワークエラー 723 アプリがブロックされた 724 組 織 がブロックされた 733 アプリの 有 効 期 限 切 れ 740 組 織 の 有 効 期 限 切 れ 702 SDK が 初 期 化 されていない 732 無 効 なアクセストークン 731 無 効 な 時 間 768 デバイスがサポートされていない 744 ファイルダウンロードに 失 敗 した 701 コンテキストは 空 白 でないこと 703 OnInitializationListner は 空 白 でないこと 764 リージョンが 追 加 されていない 765 デバイスが 追 加 されていない 734 サーバへの 接 続 不 能 721 サーバ 詳 細 が 設 定 されていない 725 アクセストークンが 見 つからない 726 サーバの url が 見 つからない 743 キャッシュの 最 小 基 準 を 満 たしていない 739 一 時 的 なリンク 発 生 に 失 敗 した 781 無 効 なパラメータ 765 デバイスが 未 登 録 761 SpotNotifier は 空 白 でないこと 736 アプリにスポットが 未 追 加 766 スキャン 時 間 超 過 767 スキャン 時 間 が 不 十 分 769 ブルートゥースが 有 効 になっていない 768 Bluetooth low energy はサポートされていない 14
9 文 献 初 めての Android 開 発 用 に https://developer.android.com/training/basics/firstapp/index.html ライブラリ プロジェクトの 参 考 として http://developer.android.com/tools/projects/projects-eclipse.html BLE の 参 考 ガイド https://developer.android.com/guide/topics/connectivity/bluetooth-le.html 15