פרסום והרשמה

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

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

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

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

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

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

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

כדי להשתמש ב-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() ומעבירים את מערך הבייטים של ההודעה. מומלץ לשמור על גודל ההודעות מתחת ל-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(). לפחות, האפליקציה צריכה לקרוא לשיטה 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);
}