פרסום והרשמה

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

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

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

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

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

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