Getting started

Adrian Crețu edited this page Dec 24, 2015 · 7 revisions

OneBeacon Android Cloud SDK

Do you need this?

You only need to read this if you plan to attach dynamic data to beacons, namespaced to your Android app package name. If you only need basic beacon monitoring in your Android app, please go to the main README of the project.

Setup

Easiest way to get started is to make a copy of the included cloud sample and then modify it to your needs. If you have an existing project you can just update your build.gradle to also include the OneBeacon android library, like in the samples. Make sure you add the local filesystem Maven repo where the library is located!

Create a new cloud project

You will need to create a new application using the OneBeacon cloud console, so you can get your own app identifier. Login into the developer console and create a new project. Make sure to go into the Settings to see your app ID and to include the correct Android app package name, and also your package signature hashes (for both the debug and release modes).

Update AndroidManifest.xml to include your app ID

Change the corresponding value for the <meta-data android:name="io.onebeacon.appKey" android:value="@string/beacons_app_id" /> to your own application ID.

## Enable the cloud and listen for AppBeacon events

When your app is ready to be notified for cloud beacon events, you must attach a listener like this:

OneBeacon.getCloud().addListener(mCloudListener);

Also, you need to make sure the cloud functionality is enabled, providing a context (e.g. the current Application, Activity or Service instance). You would want to call this after you added a listener, just to make sure you would not miss an event that occurs between the initialization call and the attachment of the above listener.

OneBeacon.enableCloudServices(this);

An example of how you listener might look like...

CloudListener mCloudListener = new CLoudListener() {
	@Override
	public void onPrepareEvents(AppBeaconEvents appBeaconsEvent) {

	}

	@Override
	public void onAppBeaconEvent(AppBeacon appBeacon, int flags) {
		if (flags == Beacon.Flags.REMOVED) {
			// signals that this beacon was internally removed, you should do that too
		}
		else {
			// an app beacons has been ranged!
		}
	}
}

So now you will receive a callback each time an AppBeacon was detected. The difference is that an AppBeacon was associated specifically to your project, either by you or automatically, if you chose so in the Beacons settings of your cloud project.

To listen for changes of an AppBeacon data, attach to the root of the beacon's data:

appBeacon.getData().addListener(new DataRefListener() {
	@Override
	public void onValueChanged(DataRef dataRef) {
		Log.d("MyApp", "value changed for " + dataRef);
	}

	@Override
	public void onChildAdded(DataRef dataRef, DataRef child) {
		Log.d("MyApp", "child added for " + dataRef + " child: " + child);

		// depending on your needs, catch events for child data changes
		// child.addListener(mChildListener);
	}

	@Override
	public void onChildRemoved(DataRef dataRef, DataRef child) {
		Log.d("MockApp", "child removed for " + dataRef + " child: " + child);
	}
});

Real-time beacon data changes

Each time your users will detect a beacon, and that beacon is attached to your project, the data for that beacon will be received by all users around that beacon. However, this is no just a one-time thing. While users are around that beacon, if you change (add, update, or delete) your data for that beacon, all users will instantly receive the new data. This allows you to build real-time applications using the same beacons, but changing their data on the fly.

Good luck!

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.