פרסום והרשמה

Nearby Messages הוא ממשק API שניתן להירשם אליו לפרסום, ומאפשר למכשירים בקרבת מקום להעביר מטענים קטנים של נתונים. ברגע שמכשיר מפרסם הודעה, מכשירים בקרבת מקום יכולים לקבל את ההודעה. במדריך הזה מוסבר מה צריך לעשות באפליקציה כדי לפרסם הודעות, ולהירשם לקבלת הודעות באמצעות Nearby Messages API.

קבוצת המכשירים בקרבת מקום נקבעת על ידי החלפת אסימונים קטנים באמצעות Bluetooth. כשמכשיר מזהה אסימון ממכשיר בקרבת מקום, הוא שולח את האסימון לשרת של Nearby Messages כדי לאמת אותו ולבדוק אם יש הודעות שצריך להעביר לגבי קבוצת המינויים הנוכחית של האפליקציה.

האפליקציה יכולה לשלוט בקבוצה של אמצעי ההגעה לאתר שמשמשים לגילוי מכשירים, ולבדוק אם האמצעים האלה משמשים כדי לשדר אסימונים ו/או כדי לסרוק אסימונים. כברירת מחדל, השידור והסריקה מתבצעים בכל אמצעי התקשורת. כדי לבצע גילוי בקבוצת משנה או אמצעי הגעה לאתר, ולקבוע אם לשדר או לסרוק, צריך לקבוע פרמטרים נוספים כשיוצרים אתרי חדשות ומינויים.

כשמפרסמים ונרשמים באופן פעיל, מוצגת ההודעה "Nearby נמצא בשימוש" שמיידע את המשתמשים ש-Nearby פעיל. ההתראה הזו מוצגת רק כשאפליקציה אחת או יותר משתמשת ב-Nearby באופן פעיל, כך שלמשתמשים יש אפשרות לחסוך בצריכת הסוללה אם אין צורך ב-Nearby. היא מציעה למשתמשים את האפשרויות הבאות:

  • מנווטים לאפליקציה כדי להשבית את Nearby.
  • לאלץ אפליקציה להפסיק להשתמש ב-Nearby.
  • מנווטים למסך הגדרות בקרבת מקום.

ניתן להשתמש ב-PublishCallback() וב-SubscribeCallback() על מנת להאזין למקרים שבהם משתמש אילץ את האפליקציה להפסיק להשתמש ב-Nearby. במקרה כזה, ה-method onExpired() מופעלת.

ממשקי API של Nearby Messages יכולים להשפיע על חיי הסוללה, ולכן יש להשתמש בהם רק מפעילות בחזית (למעט הרשמה ברקע ב-BLE).

קוראים לפונקציה publish() ו/או subscribe() כדי להשתמש ב-Nearby Messages 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() ולהעביר את המערך הבייטים של ההודעות. אנחנו ממליצים לשמור את ההודעות בנפח של פחות מ-3KB – נוכל לשלוח את ההודעות האלה מהר יותר, אבל נוכל לתמוך בנפח של עד 100KB באפליקציות שצריכות אותן. השירות הזה לא מיועד להחלפת אובייקטים גדולים יותר, כמו תמונות וסרטונים.

אפשר לקרוא לפונקציה 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);
}