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

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

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

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

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

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

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

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

Вызовите publish() и/или subscribe() , чтобы использовать API близлежащих сообщений. Ваше приложение должно всегда симметрично 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() . Как минимум ваше приложение должно вызвать отмену публикации в методе 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);
}