Публикация и подписка

Nearby Messages – это API публикации и подписки, который позволяет устройствам поблизости обмениваться небольшими пакетами данных. После того как устройство публикует сообщение, устройства поблизости могут его получить. В этом руководстве описаны все функции, которые необходимо реализовать в приложении, чтобы публиковать сообщения и подписываться на них с помощью Nearby Messages API.

Устройства поблизости определяются путем обмена небольшими токенами по Bluetooth. Когда устройство обнаруживает токен от устройства поблизости, оно отправляет его на сервер Nearby Messages, чтобы проверить его и узнать, есть ли сообщения для текущего набора подписок приложения.

Приложение может управлять набором средств, используемых для обнаружения устройств, и тем, используются ли эти средства для трансляции токенов и/или сканирования токенов. По умолчанию трансляция и сканирование выполняются на всех носителях. Чтобы выполнить обнаружение на подмножестве или носителях и контролировать, следует ли транслировать или сканировать, вы должны передать дополнительные параметры при создании публикаций и подписок.

Когда приложение активно публикует или подписывается на сообщения, появляется уведомление о том, что функция "Рядом" используется. Это уведомление показывается, только если одно или несколько приложений активно используют Nearby. Так пользователи могут отключить функцию, если она не нужна, и сэкономить заряд батареи. Пользователям доступны следующие варианты:

  • Выберите приложение, для которого нужно отключить функцию "Рядом".
  • Запретите приложению использовать функцию "Рядом".
  • Перейдите в раздел Настройки функции "Обмен с окружением".

Вы можете использовать PublishCallback() и SubscribeCallback(), чтобы отслеживать случаи, когда пользователь принудительно останавливает работу приложения с Nearby. В этом случае вызывается метод onExpired().

Поскольку Nearby Messages API может влиять на время работы от батареи, его следует использовать только для активных действий (за исключением фоновой подписки BLE).

Чтобы использовать Nearby Messages API, вызовите publish() и/или subscribe(). Приложение должно симметрично вызывать методы unpublish() и unsubscribe() в onStop().

@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 КБ. Такие сообщения доставляются быстрее. Однако при необходимости можно отправлять сообщения размером до 100 КБ. Этот сервис не предназначен для обмена крупными объектами, такими как фотографии и видео.

При необходимости вызовите 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(). Как минимум, приложение должно вызывать метод 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);
}