Your app can subscribe to Bluetooth Low Energy (BLE) beacon attachments using the same mechanism that is used to subscribe to messages published by other nearby devices. When subscribing, your app will automatically receive messages from both beacons and nearby devices.
Subscribe to BLE beacon messages
There are two ways your app can subscribe to BLE beacon messages:
- In the foreground , in response to a user action or event.
- In the background , when your app is not running.
Subscribe in the foreground
When your app subscribes to beacon messages in the foreground, scans are performed continuously until your app unsubscribes. Only start a foreground subscription when your app is active, typically in response to a user action.
Your app can initiate a foreground subscription by calling Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions)
and setting the Strategy
option to BLE_ONLY
.
The following code snippet demonstrates initiating a foreground subscription Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions)
:
public
void
onCreate
(
Bundle
savedInstanceState
)
{
super
.
onCreate
(
savedInstanceState
);
...
mMessageListener
=
new
MessageListener
()
{
@Override
public
void
onFound
(
Message
message
)
{
Log
.
d
(
TAG
,
"Found message: "
+
new
String
(
message
.
getContent
()));
}
@Override
public
void
onLost
(
Message
message
)
{
Log
.
d
(
TAG
,
"Lost sight of message: "
+
new
String
(
message
.
getContent
()));
}
}
}
//
Subscribe
to
receive
messages
.
private
void
subscribe
()
{
Log
.
i
(
TAG
,
"Subscribing."
);
SubscribeOptions
options
=
new
SubscribeOptions
.
Builder
()
.
setStrategy
(
Strategy
.
BLE_ONLY
)
.
build
();
Nearby
.
getMessagesClient
(
this
).
subscribe
(
mMessageListener
,
options
);
}
When the subscription is no longer required, your app should unsubscribe
by calling Nearby.getMessagesClient(Activity).unsubscribe(MessageListener)
.
Subscribe in the background
When your app subscribes to beacon messages in the background, low-power scans are triggered at screen-on events, even when your app is not currently active. You can use these scan notifications to "wake up" your app in response to a particular message. Background subscriptions consumes less power than foreground subscriptions, but have higher latency and lower reliability.
Your app can initiate a background subscription by calling Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions)
and setting the Strategy
option to BLE_ONLY
.
The following code snippet demonstrates initiating a background subscription by
calling Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions)
.
// Subscribe to messages in the background.
private
void
backgroundSubscribe
()
{
Log
.
i
(
TAG
,
"Subscribing for background updates."
);
SubscribeOptions
options
=
new
SubscribeOptions
.
Builder
()
.
setStrategy
(
Strategy
.
BLE_ONLY
)
.
build
();
Nearby
.
getMessagesClient
(
this
).
subscribe
(
getPendingIntent
(),
options
);
}
private
PendingIntent
getPendingIntent
()
{
return
PendingIntent
.
getBroadcast
(
this
,
0
,
new
Intent
(
this
,
BeaconMessageReceiver
.
class
),
PendingIntent
.
FLAG_UPDATE_CURRENT
);
}
The following code snippet demonstrates handling the intent in the BeaconMessageReceiver
class.
@Override
public
void
onReceive
(
Context
context
,
Intent
intent
)
{
Nearby
.
getMessagesClient
(
context
).
handleIntent
(
intent
,
new
MessageListener
()
{
@Override
public
void
onFound
(
Message
message
)
{
Log
.
i
(
TAG
,
"Found message via PendingIntent: "
+
message
);
}
@Override
public
void
onLost
(
Message
message
)
{
Log
.
i
(
TAG
,
"Lost message via PendingIntent: "
+
message
);
}
}
);
}
When the subscription is no longer required, your app should unsubscribe
by calling Nearby.getMessagesClient(Activity).unsubscribe(PendingIntent)
.
Parse beacon messages
Beacon attachments are blobs of arbitrary data that you can add to beacons . Each attachment consists of the following parts:
- Namespace: A namespace identifier.
- Type: The data type.
- Data: The data value for the attachment.
The following code snippet demonstrates using a message listener to parse messages received from a BLE beacon:
mMessageListener
=
new
MessageListener
()
{
@
Override
public
void
onFound
(
Message
message
)
{
// Do something with the message here.
Log
.
i
(
TAG
,
"Message found: "
+
message
);
Log
.
i
(
TAG
,
"Message string: "
+
new
String
(
message
.
getContent
()));
Log
.
i
(
TAG
,
"Message namespaced type: "
+
message
.
getNamespace
()
+
"/"
+
message
.
getType
());
}
...
};
Parsing the content depends on the format of the bytes. This example assumes that the content bytes encode a UTF-8 string, but your beacon message can encode other byte formats (for example a serialized protocol buffer). For more information, see Add Attachments to Beacons .
To find out which namespaces are associated with your project, call namespaces.list .
Notes:
- To conserve battery life, call
Nearby.getMessagesClient(Activity).unsubscribe()in your Activity'sonStop()function. Note that this applies only when subscribing in the foreground . - To reduce latency, use the
Strategy.BLE_ONLYoption when callingNearby.getMessagesClient(Activity).subscribe(). When this option is set, Nearby Messages API won't trigger classic Bluetooth scans. This improves the latency for beacon detection since the system doesn't cycle through all of the possible scan types. - To attach a message payload to a beacon, use the Proximity Beacon API .
