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

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

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

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

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

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

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

از آنجا که APIهای پیام‌های نزدیک (Nearby Messages) پتانسیل تأثیرگذاری بر عمر باتری را دارند، فقط باید از یک فعالیت پیش‌زمینه (foreground activity) استفاده شوند (به استثنای اشتراک پس‌زمینه BLE ).

برای استفاده از 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() را فراخوانی کنید و آرایه بایت پیام خود را ارسال کنید. توصیه می‌کنیم حجم پیام‌ها را کمتر از ۳ کیلوبایت نگه دارید - این پیام‌ها را می‌توانیم سریع‌تر تحویل دهیم - اما می‌توانیم برای برنامه‌هایی که به آن نیاز دارند، تا ۱۰۰ کیلوبایت را پشتیبانی کنیم. این سرویس برای تبادل اشیاء بزرگتر مانند عکس و فیلم در نظر گرفته نشده است.

شما می‌توانید به صورت اختیاری 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);
}