Nearby Messages は、付近のデバイスが少量のペイロードを交換できるようにするパブリッシュ / サブスクライブ API です。デバイスがメッセージを公開すると、付近のデバイスはメッセージを受信できます。このガイドでは、Nearby Messages API を使用してメッセージをパブリッシュし、メッセージをサブスクライブするためにアプリに実装する必要があるすべての機能について説明します。
近くにあるデバイスのセットは、Bluetooth を介した小さなトークンの交換によって決定されます。デバイスは付近のデバイスからトークンを検出すると、そのトークンを Nearby Messages サーバーに送信して検証し、アプリの現在の定期購入セットに配信するメッセージがあるかどうかを確認します。
アプリは、デバイスの検出に使用するメディアのセットと、そのメディアをトークンのブロードキャストやトークンのスキャンに使用するかどうかを制御できます。デフォルトでは、ブロードキャストとスキャンはすべてのメディアで行われます。サブセットまたはメディアで検出を行い、ブロードキャストとスキャンのどちらを行うかを制御するには、パブリケーションと定期購入を作成するときに追加のパラメータを渡す必要があります。
積極的に公開や登録を行っている場合は、「Nearby が使用中」という通知が表示され、Nearby がアクティブであることをユーザーに通知します。この通知は、1 つ以上のアプリが Nearby をアクティブに使用している場合にのみ表示されます。そのため、Nearby が不要な場合は、バッテリーを節約できます。ユーザーは次のオプションを使用できます。
- Nearby を無効にするには、アプリに移動します。
- アプリが Nearby の使用を強制的に停止する。
- [Nearby Settings] 画面に移動します。
PublishCallback()
と SubscribeCallback()
を使用して、ユーザーがアプリに Nearby の使用を強制的に停止した場合のケースをリッスンできます。この処理が完了すると、onExpired()
メソッドがトリガーされます。
Nearby Messages API はバッテリー駆動時間に影響する可能性があるため、フォアグラウンド アクティビティからのみ使用してください(BLE バックグラウンド サブスクライブを除く)。
Nearby Messages API を使用するには、publish()
や subscribe()
を呼び出します。アプリは常に onStop()
で unpublish()
と unsubscribe()
を対称的に並べる必要があります。
@Override
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()));
}
}
mMessage = new Message("Hello World".getBytes());
}
@Override
public void onStart() {
super.onStart();
...
Nearby.getMessagesClient(this).publish(mMessage);
Nearby.getMessagesClient(this).subscribe(mMessageListener);
}
@Override
public void onStop() {
Nearby.getMessagesClient(this).unpublish(mMessage);
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
...
super.onStop();
}
メッセージの公開
メッセージをパブリッシュするには、Nearby.getMessagesClient(Activity).publish()
を呼び出して、メッセージのバイト配列を渡します。メッセージは 3 KB 未満にすることをおすすめします。3 KB 未満であればメッセージをより迅速に配信できますが、必要なアプリでは最大 100 KB をサポートできます。このサービスは、写真や動画などのサイズの大きいオブジェクトの交換を目的としたものではありません。
必要に応じて、PublishOptions.setStrategy()
を呼び出して、使用する戦略を設定できます。
次の例は、publish()
を呼び出して小さなテキスト メッセージを送信する方法を示しています。
private void publish(String message) {
Log.i(TAG, "Publishing message: " + message);
mActiveMessage = new Message(message.getBytes());
Nearby.getMessagesClient(this).publish(mActiveMessage);
}
メッセージの公開を停止する
メッセージを非公開にするには、unpublish()
を呼び出します。少なくとも、アプリは onStop()
メソッドで公開停止を呼び出す必要があります。公開に使用したのと同じ Message
オブジェクト(この例では mActiveMessage
)を渡します。
次のコード例は、unpublish()
を呼び出す方法を示しています。
private void unpublish() {
Log.i(TAG, "Unpublishing.");
if (mActiveMessage != null) {
Nearby.getMessagesClient(this).unpublish(mActiveMessage);
mActiveMessage = null;
}
}
メッセージに登録する
他のデバイスからのメッセージに登録するには、Nearby.getMessagesClient(Activity).subscribe()
を呼び出します。サブスクライブされたメッセージの受信を処理するために、MessageListener
を渡す必要があります。
必要に応じて、SubscribeOptions.setStrategy()
を呼び出して、使用する戦略を設定できます。
次の例は、メッセージのサブスクライブを示しています。
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.");
Nearby.getMessagesClient(this).subscribe(mMessageListener, options);
}
配信停止
登録を解除して、デバイスのメッセージの受信を停止するには、Nearby.getMessagesClient(Activity).unsubscribe()
を呼び出します。サブスクライブに使用したのと同じ MessageListener
オブジェクトを渡します(この例では mMessageListener
)。
次のサンプルコードは、登録解除を示しています。
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}