Cubeacon Sample Android Project
This repository is reserved for Android Cubeacon SDK Demos app.
Cubeacon SDK Overview
Cubeacon SDK for Android is a library to allow interaction with any beacons. The SDK system requirements are Android 4.3 or above and Bluetooth Low Energy.
Cubeacon SDK allows for :
- Integrating with Cubeacon BaaS
- Scanning any beacons on a foreground UI or on background as a service
- Showing alert (foreground) or notifications (background) when any beacons entered region (onEnter), exited region (onExit), nearest detected (onChange), onImmediate beacon, onNear beacon and onFar detected beacon.
- Showing campaign scenario based on beacons event
- Sending analytic to Cubeacon BaaS
Cubeacon Link :
Cubeacon SDK Installation
-
Register to Cubeacon BaaS and download
CubeaconSDK-Android-xxx.zip
. -
Extract
CubeaconSDK-Android-xxx.zip
, copyCubeacon.properties
to the root of your project’s Javaassets
folder. -
Then copy
CubeaconSDK-xxx.aar
to yourlibs
directory. -
On your
build.gradle
withinapp
module, add this lines below beforedependencies
tagrepositories{ flatDir { dirs 'libs' } }
Then add
compile 'com.eyro.cubeacon:CubeaconSDK:1.5.0@aar'
into yourdependecies
. -
Create custom application class and add the following code to the
onCreate()
method to initialize the Cubeacon SDK.@Override public void onCreate() { super.onCreate(); // Cubeacon SDK Initialization CBApp.initialize(this, "Cubeacon.properties"); }
Don’t forget to initialize your custom application class to
AndroidManifest.xml
(Optional) You can add some custom setup :
- Enable Cubeacon SDK debug logging when on development mode by calling
CBApp.enableDebugLogging();
before initialize SDK.
- Enable Cubeacon SDK debug logging when on development mode by calling
Usage and Demos
You can import Cubeacon Demos
that located in this repo to your Android Studio. After initialization, you must download all beacon data from Cloud first.
Quick start to download cloud data :
CBApp.getInstance().getDataInBackground(new RequestCallback() {
@Override
public void onCompleted(Exception e) {
if (e != null) {
// show error message
return;
}
// do something after download complete like showing main screen
}
});
(Info) CBApp.getInstance().getDataInBackground
are implemented using background AsyncTask
method.
Main Activity
1. Using SDK Abstract Activity
Then, extends your activity that used for detected beacon to CBAppCompatActivity
class and implement all abstract method :
public class MainActivity extends CBAppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
}
@Override
public void onEnterBeacon(CBBeacon beacon) {
// do something when beacon entered region
}
@Override
public void onExitBeacon(CBBeacon beacon, long timeInterval) {
// do something when beacon exited region
}
@Override
public void onNearestBeaconChanged(CBBeacon old, CBBeacon current) {
CBCampaignType campaign = current.getStoryline().getCampaign();
// do something when nearest beacon changed
if (campaign == CBCampaignType.IMAGE) {
// display a brochure image
} else if(campaign == CBCampaignType.HTML) {
// show html page via webview
} else if(campaign == CBCampaignType.URL) {
// open url in a webview/browser
} else if(campaign == CBCampaignType.VIDEO) {
// play a video streaming
}
}
@Override
public void onEmptyBeacon() {
// do something when no beacon detected
}
@Override
public void onImmediateBeacon(CBBeacon beacon) {
// do something when beacon proximity is immediate
}
@Override
public void onNearBeacon(CBBeacon beacon) {
// do something when beacon proximity is near
}
@Override
public void onFarBeacon(CBBeacon beacon) {
// do something when beacon proximity is far
}
}
2. Using Custom Activity
If you want to extend to your own abstract or parent activity, you can manually manage Cubeacon SDK Service into your activity.
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
CBApp.getInstance().setBeaconListener(this, new BeaconListener() {
@Override
public void onImmediateBeacon(CBBeacon cbBeacon) {
// do something when beacon in immediate proximity
}
@Override
public void onNearBeacon(CBBeacon cbBeacon) {
// do something when beacon in near proximity
}
@Override
public void onFarBeacon(CBBeacon cbBeacon) {
// do something when beacon in far proximity
}
@Override
public void onEnterBeacon(CBBeacon cbBeacon) {
// do something when beacon entering region
}
@Override
public void onExitBeacon(CBBeacon cbBeacon, long interval) {
// do something when beacon exiting region
}
@Override
public void onNearestBeaconChanged(CBBeacon cbBeacon, CBBeacon cbBeacon1) {
// do something when nearest beacon changed
}
@Override
public void onEmptyBeacon() {
// do something when there is no beacon detected
}
});
// create Cubeacon service after initializing beacon's listener
CBApp.getInstance().createService();
}
protected void onResume() {
super.onResume();
// Check all requirement service and permission.
if (SystemRequirementManager.checkAllRequirementUsingDefaultDialog(this)) {
// start Cubeacon service after all requirements complied
CBApp.getInstance().startService();
}
}
@Override
protected void onStart() {
super.onStart();
// Check if device supports Bluetooth Low Energy.
if (!SystemRequirementChecker.isBluetoothLeAvailable(this)) {
// do something if there is no BLE on smartphone
// like showing alert dialog or finish the activity
}
}
Improve Battery Life
By setting scan beacon period, we can improve battery life without losing scanning result. Especially on production application. This is how you can do:
For Production
// best on battery life with some delayed scanning result
CBApp.getInstance().setScanPeriod(ScanningMode.LOW);
// good on battery life and better scanning result
CBApp.getInstance().setScanPeriod(ScanningMode.NORMAL);
For Development
// draining battery life and fast scanning result
CBApp.getInstance().setScanPeriod(ScanningMode.HIGH);
// draining a lot of battery life, but provide best scanning result
CBApp.getInstance().setScanPeriod(ScanningMode.VERY_HIGH);
Meta Users
By improving analytics usage and user engagement, Cubeacon SDK enhanced with Meta User
module. This module is optional. So if you want to get user information like fullname
and email
, show a form with 2 textinput and you can save into cloud like this :
CBUser.currentUser()
.setName("Your fullname here...")
.setEmail("Your email here...")
.sendDataInBackground(new RequestCallback() {
@Override
public void onCompleted(Exception e) {
if (e != null) {
// show error message
return;
}
// show success message
}
});
Changelog
- 1.5.0 (January 23, 2016)
- New enhancement scanning method for a faster detecting beacons.
- New AAR package, comply with Android Studio.
- New feature, added scan period mode for better battery life.
- New System Requirements Checker, comply with Android M or higher.
- Comply with AppCompat library v7 for activity bundled with SDK.
- Add possibility to customize alert and notification.
- Fix some bugs and improve stability.
- 1.3.1 (April 18, 2015)
- Fix optional parameter when downloading data from cloud
- Add control to URL WebView Activity
- 1.3.0 (February 28, 2015)
- New storyline with custom campaign like showing Image, Video, Url web page and HTML formatted content.
- New analytic data based new storyline
- Comply with current Cubeacon SaaS v1.3.0
- Support Android 5.0 Lollipop
- 1.2.0 (January 17, 2015)
- Add meta user for analytics
- Add storyline for beacon scenario
- Comply with current Cubeacon SaaS v1.2.0
- 1.0.0 (November 10, 2014)
- Add new base CBActivity class
- Improve stability
- Comply with current Cubeacon SaaS v1.0.0
- Combine all required library into single file
- Fix automatic background and foreground scanning
- 0.5.0 (August 25, 2014)
- Initial release