פרסום והרשמה

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

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

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

הערה: כל פונקציות ה-callbacks בספרייה הזו משתמשות בבלוק במקום ב-delegate. חשוב להימנע ממעגלים של שמירה בהטמעות של הבלוק. במסמכי העזרה של Apple מוסבר איך להימנע ממעגלים של שמירה.

הספרייה הזו פועלת ב-iOS 7 ואילך, והיא נוצרת באמצעות iOS 8 SDK.

יצירת מנהל הודעות

הקוד הזה יוצר אובייקט של מנהל הודעות, שמאפשר לפרסם ולעקוב אחרי הודעות. החלפת ההודעות לא מאומתת, לכן צריך לספק מפתח API ציבורי ל-iOS. אפשר ליצור פרויקט באמצעות הרשומה ב-Google Developers Console.

Objective-C

#import <GNSMessages.h>

GNSMessageManager *messageManager =
    [[GNSMessageManager alloc] initWithAPIKey:@"API_KEY"];

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

פרסום הודעה

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

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)))

הרשמה לקבלת הודעות

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

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

Objective-C

id<GNSSubscription> subscription =
    [messageManager subscriptionWithMessageFoundHandler:^(GNSMessage *message) {
      // Add the name to a list for display
    }
    messageLostHandler:^(GNSMessage *message) {
      // Remove the name from the list
    }];

Swift

let subscription =
    messageManager.subscription(messageFoundHandler: { (message: GNSMessage?) in
      // Add the name to a list for display
    },
    messageLostHandler: { (message: GNSMessage?) in
      // Remove the name from the list
    })

אמצעי הגעה לקהל בקמפיינים מסוג Discovery

כברירת מחדל, שני האמצעים (אודיו ו-Bluetooth) ישמשו לגילוי מכשירים בקרבת מקום, ושניהם ישדרו ויסריקו. במקרים מסוימים, עליכם להוסיף את הרשומות הבאות לקובץ Info.plist של האפליקציה:

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

• אם האפליקציה שלכם משדרת באמצעות BLE, צריך להוסיף את הערך NSBluetoothPeripheralUsageDescription, שהוא מחרוזת שמתארת את הסיבה לפרסום ב-BLE. לדוגמה, "אסימון אנונימי מפורסם באמצעות Bluetooth כדי לזהות מכשירים בקרבת מקום".

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

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

Objective-C

id<GNSPublication> publication = [messageManager publicationWithMessage:message
    paramsBlock:^(GNSPublicationParams *params) {
      params.strategy = [GNSStrategy strategyWithParamsBlock:^(GNSStrategyParams *params) {
        params.discoveryMediums = kGNSDiscoveryMediumsAudio;
        params.discoveryMode = kGNSDiscoveryModeScan;
      }];
    }];

Swift

let publication = messageManager.publication(with: message,
    paramsBlock: { (params: GNSPublicationParams?) in
      guard let params = params else { return }
      params.strategy = GNSStrategy(paramsBlock: { (params: GNSStrategyParams?) in
        guard let params = params else { return }
        params.discoveryMediums = .audio
        params.discoveryMode = .scan
      })
    })

הפעלת רישום נתונים של ניפוי באגים

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

מומלץ להפעיל אותו לפני שיוצרים מנהל הודעות. קטע הקוד הזה מראה איך מפעילים את הרישום ביומן לניפוי באגים:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

מעקב אחרי מצב ההרשאה 'מכשירים בקרבת מקום'

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

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

Objective-C

GNSPermission *nearbyPermission = [[GNSPermission alloc] initWithChangedHandler:^(BOOL granted) {
  // Update the UI here
}];

Swift

let nearbyPermission = GNSPermission(changedHandler: { (granted: Bool) in
  // Update the UI here
})

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

דוגמה לאופן שבו מקבלים ומגדירים את מצב ההרשאה:

Objective-C

BOOL permissionState = [GNSPermission isGranted];
[GNSPermission setGranted:!permissionState];  // toggle the state

Swift

let permissionState = GNSPermission.isGranted()
GNSPermission.setGranted(!permissionState)  // toggle the state

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

מעקב אחר הגדרות משתמשים שמשפיעות על 'שיתוף בקרבת מקום'

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

Objective-C

GNSMessageManager *messageManager = [[GNSMessageManager alloc]
    initWithAPIKey:API_KEY
       paramsBlock:^(GNSMessageManagerParams *params) {
         params.microphonePermissionErrorHandler = ^(BOOL hasError) {
           // Update the UI for microphone permission
         };
         params.bluetoothPowerErrorHandler = ^(BOOL hasError) {
           // Update the UI for Bluetooth power
         };
         params.bluetoothPermissionErrorHandler = ^(BOOL hasError) {
           // Update the UI for Bluetooth permission
         };
}];

Swift

let messageManager = GNSMessageManager(
         APIKey: API_KEY,
    paramsBlock: { (params: GNSMessageManagerParams?) in
      guard let params = params else { return }
      params.microphonePermissionErrorHandler = { (hasError: Bool) in
        // Update the UI for microphone permission
      }
      params.bluetoothPowerErrorHandler = { (hasError: Bool) in
        // Update the UI for Bluetooth power
      }
      params.bluetoothPermissionErrorHandler = { (hasError: Bool) in
        // Update the UI for Bluetooth permission
      }
    })

שינוי של תיבת הדו-שיח של ההרשאה 'סמוך'

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

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

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]
                               paramsBlock:^(GNSPublicationParams *params) {
                                 params.permissionRequestHandler = ^(GNSPermissionHandler permissionHandler) {
                                   // Show your custom dialog here.
                                   // Don't forget to call permissionHandler() with YES or NO when the user dismisses it.
                                 };
                               }];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)),
        paramsBlock: { (params: GNSPublicationParams?) in
          guard let params = params else { return }
          params.permissionRequestHandler = { (permissionHandler: GNSPermissionHandler?) in
            // Show your custom dialog here.
            // Don't forget to call permissionHandler() with true or false when the user dismisses it.
          }
        })

פעולה ברקע

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

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

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

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

  Objective-C

  id<GNSSubscription> subscription =
      [messageManager subscriptionWithMessageFoundHandler:^(GNSMessage *message) {
        // Add the name to a list for display
      }
      messageLostHandler:^(GNSMessage *message) {
        // Remove the name from the list
      }
      paramsBlock:^(GNSSubscriptionParams *params) {
        params.strategy = [GNSStrategy strategyWithParamsBlock:^(GNSStrategyParams *params) {
          params.allowInBackground = YES;
          params.discoveryMediums = kGNSDiscoveryMediumsBLE;
        }];
      }];
  

  Swift

  let subscription =
      messageManager.subscription(messageFoundHandler: { (message: GNSMessage?) in
        // Add the name to a list for display
      },
      messageLostHandler: { (message: GNSMessage?) in
        // Remove the name from the list
      },
      paramsBlock:{ (params: GNSSubscriptionParams?) in
        guard let params = params else { return }
        params.strategy = GNSStrategy(paramsBlock: { (params: GNSStrategyParams?) in
          guard let params = params else { return }
          params.allowInBackground = true
          params.discoveryMediums = .BLE
        })
      })
  

• מוסיפים את הרשומות הבאות לקובץ Info.plist של האפליקציה:

  • רשומות UIBackgroundModes:

    • bluetooth-central לסריקה של BLE ברקע. צריך להגדיר את ההגדרה הזו רק אם מצב הגילוי כולל סריקה. כברירת מחדל, מצב הגילוי כולל סריקה.
    • bluetooth-peripheral לפרסום ב-BLE ברקע. נדרש רק אם מצב הגילוי כולל שידור. כברירת מחדל, הוא כולל שידור.

  • מחרוזת NSBluetoothPeripheralUsageDescription שמתארת למה אתם רוצים לפרסם ב-BLE. לדוגמה, "אסימון אנונימי מפורסם באמצעות Bluetooth כדי לזהות מכשירים בקרבת מקום". פרטים נוספים זמינים במסמכי התיעוד של Apple.

• המערכת יכולה להרוג את האפליקציה בכל שלב כשהיא פועלת ברקע. אם מצב ההפעלה ברקע הוא הגדרה שהמשתמשים יכולים להפעיל או להשבית, האפליקציה צריכה לבצע את הפעולות הבאות:

  • שומרים את הערך של מצב הרקע ב-NSUserDefaults בכל פעם שהמשתמש משנה אותו.
  • בזמן ההפעלה, המערכת קוראת את הקובץ מ-NSUserDefaults ושוחזרת את המינויים או את כתבי העת בסביבה, אם מצב הרקע מופעל.

התראות ברקע

אם אתם רוצים שהאפליקציה תודיע למשתמש כשמגיעה הודעה למינוי בזמן שהיא פועלת ברקע, תוכלו להשתמש בהתראות מקומיות.

כדי להוסיף אותם לאפליקציה:

• להירשם לקבלת התראות מקומיות בזמן ההפעלה:

  Objective-C

  if ([UIApplication instancesRespondToSelector:@selector(registerUserNotificationSettings:)]) {
    [[UIApplication sharedApplication] registerUserNotificationSettings:
        [UIUserNotificationSettings settingsForTypes:
            UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound
                                          categories:nil]];
  }
  

  Swift

  UIApplication.shared.registerUserNotificationSettings(
      UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil))
  

• שולחים התראה מקומית במטפל של המינוי לאירוע 'התקבלה הודעה':

  Objective-C

  GNSMessageHandler myMessageFoundHandler = ^(GNSMessage *message) {
      // Send a local notification if not in the foreground.
      if ([UIApplication sharedApplication].applicationState != UIApplicationStateActive) {
        UILocalNotification *localNotification = [[UILocalNotification alloc] init];
        localNotification.alertBody = @"Message received";
        [[UIApplication sharedApplication] presentLocalNotificationNow:localNotification];
      }
      // Process the new message...
    };
  

  Swift

  let myMessageFoundHandler: GNSMessageHandler = { (message: GNSMessage?) in
    // Send a local notification if not in the foreground.
    if UIApplication.shared.applicationState != .active {
      let localNotification = UILocalNotification()
      localNotification.alertBody = "Message received"
      UIApplication.shared.presentLocalNotificationNow(localNotification)
    }
    // Process the new message...
  }