ビーコン メッセージを受信する

アプリは、近くにある他のデバイスから公開されたメッセージを登録するのと同じメカニズムを使用して、Bluetooth Low Energy（BLE）ビーコン アタッチメントを登録できます。定期購入すると、アプリはビーコンと近くのデバイスの両方からメッセージを自動的に受信します。

BLE ビーコン メッセージに登録する

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.

プロジェクトに関連付けられている Namespace を確認するには、namespaces.list を呼び出します。

注:

  • バッテリーの消費を抑えるには、アクティビティの onStop() 関数で Nearby.getMessagesClient(Activity).unsubscribe() を呼び出します。これは、フォアグラウンドで登録する場合にのみ適用されます。
  • レイテンシを短縮するには、Nearby.getMessagesClient(Activity).subscribe() を呼び出すときに Strategy.BLE_ONLY オプションを使用します。このオプションを設定すると、Nearby Messages API はクラシック Bluetooth スキャンをトリガーしません。これにより、システムが可能なすべてのスキャンタイプを循環しないため、ビーコン検出のレイテンシが改善されます。
  • メッセージ ペイロードをビーコンにアタッチするには、Proximity Beacon API を使用します。