פרסום והרשמה

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

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

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

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

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

אתם יכולים להשתמש ב-PublishCallback() וב-SubscribeCallback() כדי להאזין למקרים שבהם משתמש מאלץ את האפליקציה להפסיק להשתמש בתכונה 'שיתוף עם מכשירים סמוכים'. במקרה כזה, מופעלת השיטה 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);
}

הערה: בדוגמה הזו לא הוגדרו קריאות חוזרות לסטטוס של הפונקציה publish. כדי להגדיר קריאה חוזרת, מעבירים את PublishOptions עם PublishCallback תקין כשמפרסמים. בנוסף, צריך להוסיף את OnFailureListener לסוף קריאת הפרסום כדי לקבל הודעה אם הפרסום נכשל. לדוגמה, אם למכשיר אין חיבור אינטרנט פעיל.

ביטול הפרסום של הודעה

כדי לבטל את הפרסום של הודעה, מתקשרים אל 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);
}

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

ביטול ההרשמה

כדי לבטל את ההרשמה ולהפסיק לקבל הודעות למכשיר, צריך להתקשר למספר Nearby.getMessagesClient(Activity).unsubscribe(). מעבירים את אותו אובייקט MessageListener ששימש להרשמה (mMessageListener בדוגמה הזו).

בדוגמה הבאה של קוד מוצגת הסרת הרשמה:

private void unsubscribe() {
    Log.i(TAG, "Unsubscribing.");
    Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}