انتشار و اشتراک

Nearby Messages یک API انتشار-اشتراک است که به دستگاه‌های اطراف امکان می‌دهد حجم‌های کوچکی از داده را مبادله کنند. هنگامی که یک دستگاه پیامی را منتشر می کند، دستگاه های اطراف می توانند پیام را دریافت کنند. این راهنما شما را در تمام عملکردهایی که برنامه شما باید برای انتشار پیام‌ها و اشتراک پیام‌ها با استفاده از Nearby Messages API اجرا کند، راهنمایی می‌کند.

مجموعه دستگاه های نزدیک با تبادل توکن های کوچک از طریق بلوتوث تعیین می شود. وقتی دستگاهی رمزی را از یک دستگاه نزدیک تشخیص می‌دهد، رمز را به سرور پیام‌های نزدیک می‌فرستد تا اعتبار آن را تأیید کند و بررسی کند که آیا پیام‌هایی برای ارسال برای مجموعه اشتراک‌های فعلی برنامه وجود دارد یا خیر.

یک برنامه کاربردی می‌تواند مجموعه‌ای از رسانه‌های مورد استفاده برای کشف دستگاه و اینکه آیا رسانه‌ها برای پخش توکن‌ها و/یا اسکن نشانه‌ها استفاده می‌شوند را کنترل کند. به طور پیش فرض، پخش و اسکن در تمام رسانه ها انجام می شود. برای انجام اکتشاف در یک زیرمجموعه یا رسانه و کنترل پخش یا اسکن کردن، باید پارامترهای اضافی را هنگام ایجاد انتشارات و اشتراک‌ها ارسال کنید.

هنگام انتشار و اشتراک فعال، یک اعلان "Nearby در حال استفاده است" ارائه می شود و به کاربران اطلاع می دهد که Nearby فعال است. این اعلان تنها زمانی نمایش داده می‌شود که یک یا چند برنامه به طور فعال از Nearby استفاده می‌کنند و در صورت عدم نیاز به Nearby، به کاربران این فرصت را می‌دهد که عمر باتری خود را حفظ کنند. گزینه های زیر را در اختیار کاربران قرار می دهد:

  • برای غیرفعال کردن Nearby به برنامه ای بروید.
  • برنامه‌ای را مجبور به توقف استفاده از Nearby کنید.
  • به صفحه تنظیمات Nearby بروید.

می‌توانید از PublishCallback() و SubscribeCallback() برای گوش دادن به مواردی که کاربر برنامه را مجبور به توقف استفاده از Nearby می‌کند، استفاده کنید. هنگامی که این اتفاق می افتد، متد onExpired() راه اندازی می شود.

از آنجایی که APIهای Nearby Messages دارای پتانسیل تأثیرگذاری بر عمر باتری هستند، آنها باید فقط از یک فعالیت پیش زمینه استفاده شوند (به استثنای اشتراک در پس‌زمینه 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);
}