דף זה תורגם על ידי Cloud Translation API.

פרסום והרשמה

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

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

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

הספרייה הזו פועלת ב-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)))

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

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

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

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)

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

נדרשת הסכמת המשתמשים כדי לאפשר גילוי מכשירים. מצב ההרשאה הזה מצוין באמצעות מצב ההרשאה Nearby. בקריאה הראשונה ליצירת אתר חדשות או מינוי, למשתמש מוצגת תיבת דו-שיח להבעת הסכמה. אם המשתמש לא מסכים, גילוי המכשיר לא יפעל. במקרה כזה, באפליקציה אמורה להופיע הודעה כדי להזכיר למשתמש שזיהוי המכשיר מושבת. מצב ההרשאה שמור ב-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

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

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

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 עשויה לבקש הרשאות שונות לפני שתאפשרו ל-Nearby לפעול. במכונה, אסטרטגיית ברירת המחדל מאזינה לנתונים שמשודרים באודיו כמעט על-קולי, ולכן מערכת iOS תבקש הרשאה להשתמש במיקרופון. במקרים כאלה, ב-Nearby תוצג תיבת הדו-שיח 'preflight' שבה מוסבר למה המשתמש מתבקש לתת הרשאה.

אם אתם רוצים לספק תיבת דו-שיח בהתאמה אישית מסוג 'preflight', צריך להגדיר את הפרמטר 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))

שליחת הודעה מקומית ב-handler של המינוי שלכם שמבוסס על הודעות:

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...
}