智石时空可视化-API文档

Appearance

智石科技Beacon扫描及配置 Android API ​

简介 ​

智石科技 Beacon扫描及配置 Android API，是由 Java 语言编写的应用程序接口。它能够帮助您在移动端应用添加Beacon设备扫描功能，以及智石Beacon产品的参数配置功能。本开发包支持的Android版本为19或更高的系统。

开发指南 ​

AndroidStudio项目配置 ​

创建AndroidStudio项目 ​

在Android Studio中创建一个Android项目。

集成SDK ​

1. 下载开发包 ​

https://github.com/BrightBeacon/BrightBeacon_Android_SDK

2. 添加库到项目 ​

复制SDK内的库文件到{工程}/app/libs 目录里，如下图示：

3. 配置 build.gradle ​

在app目录下的build.gradle文件中 dependencies 块中配置库引用

java
implementation fileTree(include: ['*.jar'], dir: 'libs')

配置权限 ​

1. 添加权限声明 ​

在工程AndroidManifest.xml文件中添加权限声明：

java
<!-- 用于在线校验智石开发密钥(可选 用于连接配置智石Beacon信标) -->
<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" />

<!-- 蓝牙扫描权限,用于扫描蓝牙Beacon信标. -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- 安卓6.0及以后系统需要声明以下权限，才能扫描到蓝牙Beacon信标 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- 如果APP编译targetSdk>=31(即安卓12及以上版本),需声明以下权限 -->
<!-- 蓝牙扫描权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<!-- 蓝牙连接权限 (可选 用于连接配置智石Beacon信标) -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
2. 申请运行时权限 ​

在APP运行期间需要检查并申请相关的权限，请参考以下示例代码检查并申请相关权限：

java
private static final int REQUST_PERMISSION_CODE = 1000;

private void checkPermissions() {
	if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
		List<String> permissions = new ArrayList<>();
		// 安卓6及以上版本需要申请的相关权限
		permissions.add(Manifest.permission.WRITE_EXTERNAL_STORAGE);
		permissions.add(Manifest.permission.READ_EXTERNAL_STORAGE);
		
		if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
			// 安卓12及以上版本需要申请的相关权限
			permissions.add(Manifest.permission.BLUETOOTH_CONNECT);
			permissions.add(Manifest.permission.BLUETOOTH_SCAN);
		} else {
			// 安卓11以下版本需要申请的相关权限
			permissions.add(Manifest.permission.ACCESS_FINE_LOCATION);
			permissions.add(Manifest.permission.ACCESS_COARSE_LOCATION);
    	}
		requestPermissions(permissions.toArray(new String[0]), REQUST_PERMISSION_CODE);
	}
}

扫描周边Beacon ​

以下代码演示在Activity中添加扫描功能：

java
private BRTBeaconManager beaconManager;

@Override
protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	
	//获取单例
	beaconManager = BRTBeaconManager.getInstance(this);

	// 通过设置 BRTBeaconManagerListener 接口实现，来检测Beacon的出现,显示以及更新。
	BRTBeaconManager.setBRTBeaconManagerListener(beaconManagerListener);
	
	// 开启扫描功能
	BRTBeaconManager.startRanging();
}

// BRTBeaconManagerListener 接口实现。
private BRTBeaconManagerListener beaconManagerListener = new BRTBeaconManagerListener() {

	@Override
	public void onUpdateBeacon(ArrayList<BRTBeacon> beacons) {
		// 扫描到的周边Beacon数据列表                  
	}

	@Override
	public void onNewBeacon(BRTBeacon beacon) {
		// 扫描到新的Beacon        
	}

	@Override
	public void onGoneBeacon(BRTBeacon beacon) {
		// 扫描到的Beacon消失     
	}
};

监控Beacon ​

通常我们进入或离开某些Beacon设备时需要进行一些操作。下面是判断是否进入和离开MacAddress为"000000000001"的Beacon的样例代码：

java
BRTBeaconManagerListener beaconManagerListener = new BRTBeaconManagerListener() {

	@Override
	public void onUpdateBeacon(ArrayList<BRTBeacon> beacons) { }

	@Override
	public void onNewBeacon(BRTBeacon beacon) {
	//新设备出现
	public void onNewBeacon(BRTBeacon beacon) {
    	if (beacon.getMacAddress().equals("000000000001")){
        	// 进入 MacAddress 为"000000000001 的Beacon
    	}
	}

	@Override
	public void onGoneBeacon(BRTBeacon beacon) {
        //设备信号消失，默认有8s缓存
    	if (beacon.getSerialNumber().equals("000000000001")){
        	// 离开 MacAddress 为"000000000001 的Beacon
    	}      
	}
};

BRTBeaconManager.setBRTBeaconManagerListener(beaconManagerListener);

读取和配置Beacon参数 ​

注意：该功能仅用于智石的Beacon信标，不支持其它三第方的Beacon设备。

当前我要获取和配置Beacon设备的参数时，首先需要连接到目标Beacon，然后根据需要读取或者更新Beacon的配置参数。

连接Beacon设备 ​

以下代码演示如果连接到Beacon信标：

java
//  创建Beacon连接对象，并连接Beacon设备。
BRTBeaconConnectionV2 conn = new BRTBeaconConnectionV2(this, null, beacon, connectionListener);

//	Beacon连接监听器
BRTBeaconConnectionListener connectionListener = new BRTBeaconConnectionListener() {

	void onConnectedState(int newState, int status) { 
		if (newState == BRTBeaconConnection.CONNECTED) {
        	// 连接设备成功, 可以进行Beacon参数读取和更新功能;
        }
	}
	
	void onBeaconRead(BRTBeacon beacon) { 
		// Beacon配置读取完成;
	}
	
	void onBeaconWrite(BRTBeacon beacon, int status) {
		// Beacon配置更新完成;
	}
	
	void onError(BRTThrowable throwable) { }
	
	void onCharacteristicChanged(String uuid, int status, byte[] value) { }
	
	void onCharacteristicWrite(String uuid, int status, byte[] value) { }
	
	void onCharacteristicRead(String uuid, int status, byte[] value) { }
}

读取Beacon参数 ​

读取Beacon参数，需要调用 BRTBeaconConnectionV2 对象的 readBeacon()方法：

java
conn.readBeacon();

当读取成功后会回调 BRTBeaconConnectionListener监听器的 onBeaconRead 方法。

**注意：**只有在成功连接Beacon后才能读取Beacon参数。

更新Beacon参数 ​

更新Beacon参数，需要调用 BRTBeaconConnectionV2 对象的 writeBeacon()方法：

java
BRTBeaconConfig config = new BRTBeaconConfig();
config.setName("BrtBeacon");
config.setMajor(1234);
config.setMinor(5678);
conn.writeBeacon(config);

当更新成功后会回调 BRTBeaconConnectionListener监听器的 onBeaconWrite 方法。

**注意：**只有在成功连接Beacon后才能更新Beacon参数。

常见问题 ​

合规使用指南 ​

SDK如何处理个人信息请参见隐私政策：隐私政策

您集成和使用我们的SDK时需要遵从个人信息保护基本要求，详情请参见：合规使用指南

关于 ​