Опубликовать и подписаться

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

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

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

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

  • Чтобы отключить функцию «Рядом», перейдите в нужное приложение.
  • Принудительно отключить использование функции «Рядом» приложением.
  • Перейдите на экран «Настройки поблизости» .

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

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

Для использования API Nearby Messages вызовите методы 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 КБ — такие сообщения мы сможем доставлять быстрее, — но мы можем поддерживать сообщения размером до 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);
}