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

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

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

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

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

  • برای غیرفعال کردن «اطراف»، به برنامه‌ای بروید.
  • برنامه‌ای را وادار کنید استفاده از «اطراف» را متوقف کند.
  • به صفحه تنظیمات اطراف پیمایش کنید.

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

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

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