基本概念

函式庫提供兩種方式與現有Android App整合。其一為在既有App中,加入一個所提供的 SPOT Activity 元件,讓使用者在原本的 Activity 和 SPOT Activity之間切換。另一種則是僅僅使用原本的 Activity ,加入一個 SPOT Fragment 元件,也可以在原本的 Fragment 與 SPOT Fragment 中切換。

第一種方式,在使用者沒有切換到SPOT Activity 時,與beacon 的互動是中斷的。

將 SpotActivity/Fragment函式庫所需檔案加入專案中

將 libs 下 SpotCloudLibrary.jar / SpotBeaconLibrary.jar 兩個檔案加入專案的 libs 目錄中。
將 assets 下 html5inc 目錄,加入專案的 assets目錄中。如果使用 Android Studio,這個目錄位於 /src/main/assets
將 layout 下的 activity_spot.xml 與 fragment_spot.xml 兩個檔案,加入專案的 res/ layout 目錄中

於 AndroidManifest.xml 加入以下權限:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-feature android:name="android.hardware.bluetooth_le"
android:required="false"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

修改 AndroidManifest.xml

將 minSdkVersion 設為至少 14 (Android 4.0), targetSdkVersion 設為至少18 (Android 4.3)

建立新 Activity Class 或 Fragment Class

以下兩種方式視需要擇一即可:

1. 使用 Activity Class

建立一新的 Class,繼承自 SpotActivity
例如:

public class SpotActivityExt extends SpotActivity

將這個新的 Activity ,加入 AndroidManifest.xml 中

2. 使用 Fragment Class (推薦)

建立一個新的 Class,繼承自 SpotFragment 或 SpotFragment14
如果App中使用的是 android.support.v4.app.Fragment ,新建的 Class 應繼承自 SpotFragment
如果App中使用的是 android.app.Fragment ,新建的 Class 應繼承自 SpotFragment14 (API Level 14)

例如:

public class SpotFragmentExt extends SpotFragment14

完成SPOT class 的初始參數設定與 override method

Override onCreate method,提供 API Key

	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		APIKey="78059b8d8f543db8d198ffaf";
		sharedUUID = true;	    
}

 

@override public void didRangBeaconNearBy(JSONArray beaconJson)
當偵測到SPOT Beacon 時被呼叫,傳回周圍的beacon 資訊

@override public void didChangedBeaconDetectionStatus (int status)
當 Beacon 偵測功能有異常時被呼叫,會回傳狀態代碼 

@override public void didRangeBeaconContentWithEid(String eid) Method
當偵測到符合的SPOT Beacon Campaign時被呼叫,同時傳入該 campaign 的 id

@override public void callbackOrigin()
使用者點擊Activity / Fragment左上角的返回按鈕

 

使用API

public void setBeaconDetectionEnable(boolean enable)
啟動與關閉beacon 偵測。
傳入值:true – 啟動, false – 關閉 

public JSONArray getNearByBeaconArray()
取得最後一次周圍Beacon 的偵測資料
回傳 JSONArray,內容說明請參考Beacon Array 欄位說明

public int getBeaconDetectionStatus()
取得目前 Beacon 偵測功能的狀態
回傳狀態代碼相同於didChangedBeaconDetectionStatus

public void setCustomUserId(String uid)
將App使用者ID傳送給iBeacon HTML5 網頁應用
uid:使用者ID,可於 HTML5 網頁中,透過 spot-jsbelib 函式庫接收

自訂起始頁面設定

尚未進入SPOT beacon 的範圍前,Activity 或 Fragment 所顯示的內容。

設定在: html5inc/welcome_screen.js 當中。
json 格式說明:imageLink: 圖檔的陣列。

 

Beacon Array 欄位說明

JSONObject物件。在非Smart City Edition,僅idname,px,description三個欄位有資料。

key

Type

名稱

說明

idname

String

Beacon識別編號

 

px

int

距離

1: < 50cm

2: 50cm ~ 2m

3: 2m ~ 30m

0: unknown

description

String

描述

店名, 地標名

loctype

String

地點類型

 

lat

double

座標緯度

 

lng

double

座標經度

 

floor

int

樓層

室外一律為0

 

Beacon偵測工作狀態代碼

static final

Int

說明

BEACON_DETECTION_OK

0

運作正常

BEACON_DETECTION_ERROR_NO_BLE

1

未支援BLE

BEACON_DETECTION_ERROR_BLE_OFF

2

藍芽選項關閉

BEACON_DETECTION_ERROR_NO_NETWORK

3

無法連結Cloud伺服器

BEACON_DETECTION_ERROR_LOCATION_SERVICE_OFF

4

使用者關閉/未授權定位服務(僅限iOS)

 

範例程式說明

spot_sdk_demo1 示範如何用 SpotActivity
spot_sdk_demo2 示範如何用 SpotFragment

Attachments:
Download this file (SPOT SDK Android _en.pdf)SPOT SDK Android _en.pdf[ ]269 kB

Official iBeacon Licensee

© 2014 KKlabs Inc., All rights reserved

Add 1F., No. 16-1, Ln. 106, Songjiang Rd.,
Taipei City 10459, Taiwan
Email service@kkbooks.tw
Tel +886 2 2563 2260