iBeacon Android Documentation

Last updated: Jan 06th, 2017

Getting Started

Beacon module is one of Mesosfer module that has specific feature to manage beacon activities.

Storyline

This module used for showing a “story” when beacons are detected or in range e.g. museum, merchant shop, etc. Y0u can manage what “story” that need to show to the end users when detected beacon e.g. some alert text or notification, displaying an image campaign, playing a video campaign or maybe open some website. You can also choose when the “story” must displayed based on beacon’s event :

  • Enter, triggered when user entering region of a beacon
  • Exit, triggered when user exiting region of a beacon
  • Immediate, triggered when user range approximately <1 meter from beacon
  • Near, triggered when user range approximately within 1-3 meters from beacon
  • Far, triggered when user range approximately >3 meters from beacon

Besides, you can select what days to show when “story” was triggered. By using a storyline, you can manage multiple beacon’s “story”.

Presence

This module can be used to tracking any check-in and check-out data e.g. employee attendance, student presence, etc.

Notification

This module is the simple version of storyline, it can only manage a beacon for each notification e.g. show a greeting when user entering shop.

Microlocation

This module can be used for track indoor location using a mapped beacon in an area.

Module Beacon

Mesosfer provide a specialized bucket Beacon that automatically handles much of the functionality required for beacon management.

Objects and Types

Here is some predefined Beacon object :

  • name => String, define the name of a beacon.
  • uuid => UUID, define the proximity UUID of a beacon. Most commonly represented as a string, e.g. CB10023F-A318-3394-4199-A8730C7C1AEC.
  • major => Number, define the major number of a beacon. An unsigned short integer, i.e., an integer ranging from 1 to 65535, (0 is a reserved value).
  • minor => Number, define the minor number of a beacon. Also an unsigned short integer, like the major number.
  • metadata => Object, define custom object of a beacon.

Predefined Getters & Setters Method

  • getName() - setName(String name), getter and setter for name of beacon.
  • getProximityUUID() - setProximityUUID(UUID uuid), getter and setter for uuid of beacon.
  • getMajor() - setMajor(int major), getter and setter for major of beacon.
  • getMinor() - setMinor(int minor), getter and setter for minor of beacon.
  • getData(String key) - setData(String key, Object value), getter and setter for custom object metadata of beacon.

Saving Beacons

Let’s say you want to save the Beacon described above to the Mesosfer Cloud. The interface is similar to a Map, plus the saveAsync method:

// create new beacon object
MesosferBeacon beacon = MesosferBeacon.createBeacon();
// set beacon proximity UUID
beacon.setProximityUUID(UUID.fromString("CB10023F-A318-3394-4199-A8730C7C1AEC"))
// set beacon major number
beacon.setMajor(1);
// set beacon minor number
beacon.setMinor(284);
// set beacon name
beacon.setName("Cubeacon");
// set beacon custom objects
beacon.setData("identifier", "Beacon-Red-Front-Gate-1-284");
beacon.setData("timestamp", new Date());
beacon.setData("object", new JSONObject());
beacon.setData("array", new JSONArray());
// execute save async using callback
beacon.saveAsync(new SaveCallback() {
        @Override
        public void done(MesosferException e) {
            // check if there is an exception happen
            if (e != null) {
                Log.e(TAG, "Error saving Beacon, cause: " + e);
                return;
            }

            Log.d(TAG, "Beacon successfully saved);
        }
    });

Retrieve Beacons

If you need to fetch a Beacon with the latest data that is in the cloud, you can call the fetchAsync method like so:

// create beacon from existing objecId
MesosferBeacon beacon = MesosferBeacon.createWithObjectId("beaconObjectId");
// fetching the beacon data
beacon.fetchAsync(new GetCallback() {
    @Override
    public void done(MesosferBeacon beacon, MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // fetch beacon succeeded
    }
});

This will automatically update beacon with the latest data from cloud.

Querying Beacon

There are many other ways to retrieve data with Mesosfer Query. You can retrieve many data at once, put conditions on the data you wish to retrieve.

Basic Query

In many cases, there is a condition that need to specify which datas you want to retrieve. The MesosferQuery offers different ways to retrieve a list of beacons. The general pattern is to create a MesosferQuery, put conditions on it, and then retrieve a List of matching MesosferBeacons using the findAsync method with a FindCallback. For example, to retrieve Beacons data with a name, use the whereEqualTo method to constrain the value for a key:

MesosferQuery query = MesosferBeacon.getQuery();
query.whereEqualTo(MesosferBeacon.KEY_NAME, "Beacon-Red-Front-Gate-1-284");
query.findAsync(new FindCallback() {
    @Override
    public void done(List<MesosferBeacon> list, MesosferException e) {
        if (e != null) {
            // exception happen, handle the message
            return;
        } 

        // found the beacons, show in listview
    }
});

Query Constraint

Refer to this link to learn more about query constraint.

Update Beacon

After getting the beacon data, you can update your data that stored in cloud using method saveAsync.

MesosferBeacon beacon; // fetched beacon data
// update beacon data
beacon.setProximityUUID(UUID.fromString("11111111-2222-3333-4444-555555555555"));
beacon.setMajor(6);
beacon.setMinor(7);
beacon.setName("Beacon-Red-Waiting-Room-6-7");
beacon.setData("timestamp", new Date());
// execute save data
beacon.saveAsync(new SaveCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // beacon updated, show success message
    }
});

Delete Beacon

To delete a beacon from the Mesosfer Cloud, use method deleteAsync :

// the current beacon object to delete
MesosferBeacon beacon;
// execute delete beacon async
beacon.deleteAsync(new DeleteCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // beacon deleted successfully
    }
});

Module Presence

Mesosfer provide a specialized bucket Notification that automatically handles much of the functionality required for notification management.

Objects and Types

Here is some predefined Notification object :

  • beacon => MesosferBeacon, define the beacon object of a notification.
  • description => String, define the description of notification.
  • event => String, define the event name of a notification.
  • type => String, define the event type of a notification.
  • isEnabled => Boolean, define the state of notification whether it is enabled or not.
  • message => Object, define custom object of a notification.

Predefined Getters & Setters Method

  • getBeacon() - setBeacon(MesosferBeacon beacon), getter and setter for beacon of notification.
  • getDescription() - setDescription(String description), getter and setter for description of notification.
  • getEvent() - setEvent(MesosferBeacon.Event event), getter and setter for event of notification.
  • getType() - setType(Type type), getter and setter for type of notification.
  • getMessage() - setMessage(MesosferObject message), getter and setter for custom object message of notification.

Saving Notifications

Let’s say you want to save the Notification described above to the Mesosfer Cloud. The interface is similar to a Map, plus the saveAsync method:

// create new notification object
MesosferNotification notif = MesosferNotification.createNotification();
// set beacon
notif.setBeacon(beacon);
// set description
notif.setDescription("Monday-Notification");
// set event
notif.setEvent(MesosferBeacon.Event.ENTER);
// set type
notif.setType(Type.TEXT);
// set custom objects
notif.setData("alertTitle", "Hello, good morning.");
notif.setData("alertMessage", "How is your weekend? It's great, isn't it? Have a nice day.");
notif.setData("timestamp", new Date());
notif.setData("object", new JSONObject());
notif.setData("array", new JSONArray());
// execute save async using callback
notif.saveAsync(new SaveCallback() {
        @Override
        public void done(MesosferException e) {
            // check if there is an exception happen
            if (e != null) {
                Log.e(TAG, "Error saving Notification, cause: " + e);
                return;
            }

            Log.d(TAG, "Notification successfully saved);
        }
    });

Retrieve Notifications

If you need to fetch a Notification with the latest data that is in the cloud, you can call the fetchAsync method like so:

// create notification from existing objecId
MesosferNotification notif = MesosferNotification.createWithObjectId("notificationObjectId");
// fetching the notification data
notif.fetchAsync(new GetCallback() {
    @Override
    public void done(MesosferNotification notif, MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // fetch notification succeeded
    }
});

This will automatically update notif with the latest data from cloud.

Querying Notification

There are many other ways to retrieve data with MesosferQuery. You can retrieve many data at once, put conditions on the data you wish to retrieve.

Basic Query

In many cases, there is a condition that need to specify which datas you want to retrieve. The MesosferQuery offers different ways to retrieve a list of notifications. The general pattern is to create a MesosferQuery, put conditions on it, and then retrieve a List of matching MesosferNotifications using the findAsync method with a FindCallback. For example, to retrieve Notifications data with a type, use the whereEqualTo method to constrain the value for a key:

MesosferQuery query = MesosferNotification.getQuery();
query.whereEqualTo(MesosferNotification.KEY_TYPE, Type.TEXT.name());
query.findAsync(new FindCallback() {
    @Override
    public void done(List<MesosferNotification> list, MesosferException e) {
        if (e != null) {
            // exception happen, handle the message
            return;
        } 

        // found the notifications, show in listview
    }
});

Query Constraint

Refer to this link to learn more about query constraint.

Update Notification

After getting the notification data, you can update your data that stored in cloud using method saveAsync.

MesosferNotification notif; // fetched notification data
// update notification data
notif.setEvent(MesosferBeacon.Event.EXIT);
notif.setType(Type.IMAGE);
notif.setData("timestamp", new Date());
notif.setData("urlImageAndroid", "http://image.com/image-android-720x1280.png");
// execute save notification data
notif.saveAsync(new SaveCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // notification updated, show success message
    }
});

Delete Notification

To delete a notification from the Mesosfer Cloud, use method deleteAsync :

// the current notification object to delete
MesosferNotification notif;
// execute delete notification async
notif.deleteAsync(new DeleteCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // notification deleted successfully
    }
});

Module Storyline

Mesosfer provide a specialized bucket Storyline that automatically handles much of the functionality required for storyline management.

Objects and Types

Here is some predefined Storyline object :

  • title => String, define the title of a storyline.
  • isEnabled => Boolean, define the state of storyline, whether it is enabled or not.

Predefined Getters & Setters Method

  • getTitle() - setTitle(String title), getter and setter for title of storyline.
  • isEnabled() - isEnabled(boolean isEnabled), getter and setter for isEnabled of storyline.

Saving Storylines

Let’s say you want to save the Storyline described above to the Mesosfer Cloud with saveAsync method:

// create new Storyline object
MesosferStoryline storyline = MesosferStoryline.createStoryline();
// set title
storyline.setTitle("Entering-region-storyline");
// set isEnabled
storyline.isEnabled(true);
// execute save async using callback
storyline.saveAsync(new SaveCallback() {
        @Override
        public void done(MesosferException e) {
            // check if there is an exception happen
            if (e != null) {
                Log.e(TAG, "Error saving Storyline, cause: " + e);
                return;
            }

            Log.d(TAG, "Storyline successfully saved);
        }
    });

Retrieve Storylines

If you need to fetch a Storyline with the latest data that is in the cloud, you can call the fetchAsync method like so:

// create storyline from existing objecId
MesosferStoryline storyline = MesosferStoryline.createWithObjectId("storylineObjectId");
// fetching the storyline data
storyline.fetchAsync(new GetCallback() {
    @Override
    public void done(MesosferStoryline storyline, MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // fetch storyline succeeded
    }
});

This will automatically update storyline with the latest data from cloud.

Querying Storyline

There are many other ways to retrieve data with MesosferQuery. You can retrieve many data at once, put conditions on the data you wish to retrieve.

Basic Query

In many cases, there is a condition that need to specify which datas you want to retrieve. The MesosferQuery offers different ways to retrieve a list of Storylines. The general pattern is to create a MesosferQuery, put conditions on it, and then retrieve a List of matching MesosferStorylines using the findAsync method with a FindCallback. For example, to retrieve Storylines data where isEnabled, use the whereEqualTo method to constrain the value for a key:

MesosferQuery query = MesosferStoryline.getQuery();
query.whereEqualTo(MesosferStoryline.KEY_IS_ENABLED, true);
query.findAsync(new FindCallback() {
    @Override
    public void done(List<MesosferStoryline> list, MesosferException e) {
        if (e != null) {
            // exception happen, handle the message
            return;
        } 

        // found the storylines, show in listview
    }
});

Query Constraint

Refer to this link to learn more about query constraint.

Update Storyline

After getting the Storyline data, you can update your data that stored in cloud using method saveAsync.

MesosferStoryline storyline; // fetched storyline data
// update Storyline data
storyline.setTitle("Exiting-region-storyline");
storyline.isEnabled(false);
// execute save data
storyline.saveAsync(new SaveCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // Storyline updated, show success message
    }
});

Delete Storyline

To delete a Storyline from the Mesosfer Cloud, use method deleteAsync :

// the current Storyline object to delete
MesosferStoryline storyline;
// execute delete storyline async
storyline.deleteAsync(new DeleteCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // Storyline deleted successfully
    }
});

Module Storyline Detail

Mesosfer provide a specialized bucket StorylineDetail that automatically handles much of the functionality required for storyline management.

Objects and Types

Here is some predefined StorylineDetail object :

  • event => String, define the event name of a storyline.
  • campaign => String, define the campaign type of a storyline.
  • beacons => Array, define array of beacon of a storyline.
  • showOn => Array, define array of key and value pairs within day name and boolean state of a storyline.
  • alertTitle => String, define the alert title of storyline, used for TEXT campaign.
  • alertMessage => String, define the alert message of storyline, used for TEXT campaign.
  • urlImageAndroid => String, define the url image for Android of storyline, used for IMAGE campaign.
  • urlImageiOS => String, define the url image for iOS of storyline, used for IMAGE campaign.
  • urlPage => String, define the url page of storyline, used for URL campaign.
  • urlVideo => String, define the url video of storyline, used for VIDEO campaign.

Predefined Getters & Setters Method

  • getEvent() - setEvent(MesosferBeacon.Event event), getter and setter for event of storyline.
  • getCampaign() - setCampaign(MesosferStoryline.Campaign campaign), getter and setter for campaign of storyline.
  • getBeacons() - setBeacons(List<MesosferBeacon> beacons), getter and setter for custom object beacons of storyline.
  • getShowOn() - setShowOn(MesosferShowDay showOn), getter and setter for custom object showOn of storyline.
  • getAlertTitle() - setAlertTitle(String alertTitle), getter and setter for custom object alertTitle of storyline.
  • getAlertMessage() - setAlertMessage(String alertMessage), getter and setter for custom object alertMessage of storyline.
  • getUrlImageAndroid() - setUrlImageAndroid(String urlImageAndroid), getter and setter for custom object urlImageAndroid of storyline.
  • getUrlImageIOS() - setUrlImageIOS(String urlImageIOS), getter and setter for custom object urlImageIOS of storyline.
  • getUrlPage() - setUrlPage(String urlPage), getter and setter for custom object urlPage of storyline.
  • getUrlVideo() - setUrlVideo(String urlVideo), getter and setter for custom object urlVideo of storyline.

Saving Storyline Details

Let’s say you want to save the StorylineDetail described above to the Mesosfer Cloud with saveAsync method:

// Storyline object
MesosferStoryline storyline;

// create new Storyline Detail object
MesosferStorylineDetail detail = MesosferStorylineDetail.createStoryline(storyline);
// set campaign
detail.setCampaign(MesosferStoryline.Campaign.VIDEO);
// set event
detail.setEvent(MesosferBeacon.Event.IMMEDIATE);
// set alert title
detail.setAlertTitle("App Notification");
// set alert message
detail.setAlertMessage("You have a notification.");
// set url video
detail.setUrlVideo("https://youtube.com/watch?v=mesosfer-video-campaign");

// set beacon list
List<MesosferBeacon> beaconList;
detail.setBeacons(beaconList);
// set show on
MesosferShowDay showOn = new MesosferShowDay();
detail.setShowOn(showOn);

// execute saving storyline detail
detail.saveAsync(new SaveCallback() {
        @Override
        public void done(MesosferException e) {
            // check if there is an exception happen
            if (e != null) {
                Log.e(TAG, "Error saving storyline detail, cause: " + e);
                return;
            }

            Log.d(TAG, "Storyline detail successfully saved);
        }
    });

Retrieve Storyline Details

If you need to fetch a StorylineDetail with the latest data that is in the cloud, you can call the fetchAsync method like so:

// create storyline detail from existing objecId
MesosferStorylineDetail detail = MesosferStorylineDetail.createWithObjectId("storylineDetailObjectId");
// fetching the storyline detail data
detail.fetchAsync(new GetCallback() {
    @Override
    public void done(MesosferStorylineDetail storyline, MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // fetch storyline detail succeeded
    }
});

This will automatically update detail with the latest data from cloud.

Querying Storyline

There are many other ways to retrieve data with MesosferQuery. You can retrieve many data at once, put conditions on the data you wish to retrieve.

Basic Query

In many cases, there is a condition that need to specify which datas you want to retrieve. The MesosferQuery offers different ways to retrieve a list of Storylines. The general pattern is to create a MesosferQuery, put conditions on it, and then retrieve a List of matching MesosferStorylineDetails using the findAsync method with a FindCallback. For example, to retrieve Storylines data with campaign VIDEO and event ENTER, use the whereEqualTo method to constrain the value for a key:

MesosferQuery query = MesosferStorylineDetail.getQuery();
query.whereEqualTo(MesosferStorylineDetail.KEY_CAMPAIGN, MesosferStoryline.Campaign.VIDEO.name());
query.whereEqualTo(MesosferStorylineDetail.KEY_EVENT, MesosferBeacon.Event.ENTER.name());
query.findAsync(new FindCallback() {
    @Override
    public void done(List<MesosferStorylineDetail> list, MesosferException e) {
        if (e != null) {
            // exception happen, handle the message
            return;
        } 

        // found the storyline details, show in listview
    }
});

Query Constraint

Refer to this link to learn more about query constraint.

Update Storyline

After getting the StorylineDetail data, you can update your data that stored in cloud using method saveAsync.

MesosferStorylineDetail detail; // fetched storyline detail data
// update storyline detail data
detail.setUrlVideo("https://youtube.com/watch?v=cubeacon-video-campaign");
detail.setEvent(MesosferBeacon.Event.NEAR);
// execute save data
detail.saveAsync(new SaveCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // storyline detail updated, show success message
    }
});

Delete Storyline Detail

To delete a Storyline from the Mesosfer Cloud, use method deleteAsync :

// the current Storyline object to delete
MesosferStorylineDetail detail;
// execute delete storyline async
detail.deleteAsync(new DeleteCallback() {
    @Override
    public void done(MesosferException e) {
        // check if there is an exception happen
        if (e != null) {
            // handle the exception
            return;
        }

        // Storyline detail deleted successfully
    }
});

Module Log

Within Beacon modules, Mesosfer provide a specialized bucket Log that use for logging.

Objects and Types

Here is some predefined Storyline object :

  • beacon => String, define the beacon that detected.
  • event => String, define the event beacon that happen.
  • interval => Number, define the interval between entering and exiting region of beacon.
  • module => String, define the module that used for logging. There are 4 modules :
    • STORYLINE
    • PRESENCE
    • TAGGING
    • MICROLOCATION

Sending Logs

Let’s say you want to send a Log to Mesosfer Cloud with saveAsync method:

// create log object
MesosferLog log = MesosferLog.createLog();
// set module log
log.setModule(MesosferBeacon.Module.STORYLINE);
// set beacon for log
log.setBeacon(MesosferBeacon.createWithObjectId("foo0HW4mZA"));
// set event beacon that triggering log
log.setEvent(MesosferBeacon.Event.FAR);
// sending log to Mesosfer Cloud
log.sendAsync(new SaveCallback() {
            @Override
            public void done(MesosferException e) {
                // check if exception happen
                if (e != null) {
                    Log.e(TAG, "Failed to send log.");
                    return;
                }

                Log.e(TAG, "Log sent.");
            }
        });