פרסום והרשמה

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

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

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

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

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

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

אפשר גם להתקשר ל-PublishOptions.setStrategy() להגדרת האסטרטגיה לשימוש.

הדוגמה הבאה ממחישה איך קוראים לפונקציה publish() כדי לשלוח הודעת טקסט קטנה message:

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);
}