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

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

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

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

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

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

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

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

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