פרסום והרשמה

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

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

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

כשמפרסמים ומנויים באופן פעיל, מוצגת ההתראה 'השימוש ב-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);
}