Veröffentlichen und abonnieren

Die Nearby Messages API ist eine Publish-Subscribe-API, mit der sich Geräte in der Nähe befinden kleine Datenmengen austauschen. Sobald ein Gerät eine Nachricht veröffentlicht, Geräte die Nachricht empfangen können. Die Nachrichtengröße sollte relativ klein sein, um eine gute Leistung zu gewährleisten. Dieser Dienst ist nicht zum Austausch größerer wie Fotos und Videos.

Die Anzahl der in der Nähe befindlichen Geräte wird durch den Austausch kleiner Tokens über Bluetooth und Beinahe-Ultraschall-Audio (unverständlich) Wenn ein Gerät ein Token erkennt von einem Gerät in der Nähe sendet es das Token an den Nearby Messages-Server, und prüfen, ob es Nachrichten gibt, die an den die aktuelle Gruppe von Abos.

Eine App kann die Medien steuern, die für die Geräteerkennung verwendet werden, und Informationen darüber, ob die Medien zur Übertragung von Tokens und/oder zum Scannen nach Tokens verwendet werden. Das Senden und Scannen erfolgt standardmäßig auf allen Medien. Aufgabe die Erkennung auf einer Teilmenge oder auf Medien an. Außerdem lässt sich festlegen, ob Beim Erstellen von Publikationen und Abos.

Diese Bibliothek läuft unter iOS 7 und höher und wird mit dem iOS 8 SDK erstellt.

Nachrichtenmanager erstellen

Mit diesem Code wird ein Nachrichtenmanagerobjekt erstellt, mit dem Sie abonnieren. Da der Nachrichtenaustausch nicht authentifiziert ist, müssen Sie einen öffentlichen API-Schlüssel für iOS. Sie können ein Konto mit dem Eintrag in der Google Developers Console für für Ihr Projekt.

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Mitteilung veröffentlichen

Dieses Code-Snippet zeigt, wie eine Nachricht mit einem Namen veröffentlicht wird. Die Publikation ist aktiv, solange das Publikationsobjekt vorhanden ist. Beenden Publishing, geben Sie das Publikationsobjekt frei.

Objective-C

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

Swift

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

Abonnieren von Nachrichten

Dieses Code-Snippet zeigt, wie alle vom vorherigen Publikations-Snippet. Das Abo ist aktiv, solange das Aboobjekte vorhanden sind. Wenn du das Abo beenden möchtest, musst du das Abo freigeben -Objekt enthält.

Der Handler für gefundene Nachrichten wird aufgerufen, wenn Geräte in der Nähe veröffentlicht werden Nachrichten erkannt werden. Der Handler für verloren gegangene Nachrichten wird aufgerufen, wenn eine Nachricht keine länger beobachtet werden (das Gerät befindet sich außerhalb der Reichweite oder veröffentlicht den .

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-Medien

Standardmäßig werden beide Medien (Audio und Bluetooth) verwendet, um Orte in der Nähe zu finden Geräte gesendet und von beiden Medien gescannt werden. In bestimmten Fällen müssen Sie erforderlich, um dem Info.plist Ihrer App die folgenden Einträge hinzuzufügen:

  • Wenn deine App Audio-Scans verwendet, füge NSMicrophoneUsageDescription hinzu. Dabei handelt es sich Zeichenfolge, die beschreibt, warum Sie das Mikrofon verwenden werden. Zum Beispiel: „Die Das Mikrofon wartet auf anonyme Tokens von Geräten in der Nähe.“

  • Wenn Ihre App BLE verwendet, fügen Sie NSBluetoothPeripheralUsageDescription ist ein String, der beschreibt, warum Sie wird auf BLE werben. Beispiel: "Ein anonymes Token wird beworben. um Geräte in der Nähe zu finden.“

In einigen Fällen muss Ihre App möglicherweise nur eines der Medien verwenden. muss auf diesem Medium möglicherweise nicht sowohl gesendet als auch gescannt werden.

Eine App, die zum Verbinden mit einer Set-Top-Box entwickelt wurde, Bei der Übertragung über Audio muss lediglich die Audiospur gescannt werden, um sie zu erkennen. Die folgenden Das Snippet zeigt, wie eine Nachricht nur mit Audio in der Set-Top-Box veröffentlicht wird. Scannen für Erkennung:

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

Debuggingprotokollierung aktivieren

Beim Debugging-Logging werden wichtige interne Ereignisse in der Konsole ausgegeben, die ist hilfreich, um Probleme aufzuspüren, die bei der Integration von Nearby auftreten können. Nachrichten in deine App. Wir fragen Sie nach diesen Protokollen, wenn Sie uns bezüglich technischen Support.

Aktivieren Sie sie, bevor Sie einen Nachrichten-Manager erstellen. Dieses Code-Snippet zeigt So aktivieren Sie das Debugging-Logging:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Berechtigungsstatus „Nearby“ verfolgen

Die Nutzereinwilligung ist erforderlich, um die Geräteerkennung zu aktivieren. Dies wird durch die Berechtigungsstatus „Nearby“. Beim ersten Aufruf zum Erstellen einer Publikation oder Abo abgeschlossen haben, wird dem Nutzer ein Dialog zur Einholung von Einwilligungen angezeigt. Wenn die Nutzenden Einwilligung geben, funktioniert die Geräteerkennung nicht. In diesem Fall sollte Ihre App eine Nachricht, um den Nutzer daran zu erinnern, dass die Geräteerkennung deaktiviert ist. Die Berechtigung Status wird in NSUserDefaults gespeichert.

Das folgende Snippet zeigt, wie der Berechtigungsstatus abonniert wird. Die Der Handler für geänderte Berechtigungsstatus wird immer dann aufgerufen, wenn sich der Status ändert. wird beim ersten Aufruf erst dann wieder aufgerufen, wenn der Nutzer die Berechtigung erteilt oder verweigert hat. Lassen Sie das Berechtigungsobjekt los, um das Abo zu beenden.

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

Ihre App bietet Nutzern die Möglichkeit, den Berechtigungsstatus zu ändern. für indem Sie auf einer Einstellungsseite die entsprechende Ein/Aus-Schaltfläche verwenden.

Hier ist ein Beispiel für das Abrufen und Festlegen des Berechtigungsstatus.

Objective-C

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

Swift

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

Nutzereinstellungen erfassen, die sich auf Nearby auswirken

Wenn der Nutzer die Mikrofonberechtigung oder die Bluetooth-Berechtigung verweigert oder Bluetooth deaktiviert hat, funktioniert Nearby nicht oder gar nicht. Ihre App sollte in diesen Fällen eine Meldung anzeigen, die den Nutzer darauf hinweist, dass Nearby Operationen behindert werden. Das folgende Snippet zeigt, wie Sie Status dieser Nutzereinstellungen durch Übergeben von Handlern beim Erstellen der Nachricht Manager:

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

Dialogfeld mit Berechtigungen in der Nähe überschreiben

Je nach den Parametern, die Sie an Ihre Publikationen und Abos übergeben, iOS fordert möglicherweise verschiedene Berechtigungen an, bevor Nearby verwendet werden kann. Für erfasst die Standardstrategie Daten, die auf Beinahe-Ultraschall übertragen werden, Daher fordert iOS Sie auf, das Mikrofon zu verwenden. In diesen Fällen In der Nähe wird ein "Preflight" angezeigt. Dialogfeld, in dem erklärt wird, warum der Nutzer gefragt wird um die Berechtigung zu erteilen.

Wenn Sie einen benutzerdefinierten Preflight die Option permissionRequestHandler-Parameter zu einem benutzerdefinierten Block in der Publikation oder Aboparameter. Mit Ihrem benutzerdefinierten Baustein muss die Methode permissionHandler aufgerufen werden nachdem der Nutzer geantwortet hat. Das folgende Snippet zeigt, wie das geht. für eine Publikation:

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

Hintergrundvorgang

Publikationen und Abos, die BLE für die Geräteerkennung verwenden, funktionieren in der Hintergrund. Hier sind einige Dinge, die Sie bei der Verwendung Hintergrundmodus:

  • Für Hintergrundvorgänge darf nur das BLE-Medium verwendet werden. Audio wird nicht unterstützt.
  • Für BLE im Hintergrund fallen zusätzliche Akkukosten an. Die Kosten sind niedrig, aber Sie bevor Sie sich für den Hintergrundmodus entscheiden.
  • iOS bittet den Nutzer um die Berechtigung, im Hintergrund über BLE zu werben.

Wenn Sie einer Publikation oder einem Abo den Hintergrundmodus hinzufügen möchten, folgen Sie diesen zusätzlichen Schritte:

  • Aktiviere in deiner Publikation oder deinem Abo den Hintergrundmodus und BLE-Only, indem du und übergeben ein korrekt konfiguriertes GNSStrategy-Objekt. Das folgende Snippet zeigt, wie das für ein Abo geht:

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

  • Fügen Sie dem Info.plist Ihrer App diese Einträge hinzu:

    • UIBackgroundModes Einträge:

      • bluetooth-central für BLE-Scans im Hintergrund. Nur erforderlich wenn der Erkennungsmodus das Scannen umfasst; ist das standardmäßig der Fall.
      • bluetooth-peripheral für BLE-Werbung im Hintergrund. Erforderlich nur wenn der Erkennungsmodus Übertragungen umfasst; ist das standardmäßig der Fall.

    • NSBluetoothPeripheralUsageDescription-String mit Beschreibung des Grundes werden Sie auf BLE werben. Beispiel: „Ein anonymes Token über Bluetooth beworben werden, um Geräte in der Nähe zu finden.“ Weitere Informationen finden Sie unter Dokumentation von Apple .

  • Ihre App kann jederzeit vom System beendet werden, wenn sie im Hintergrund ausgeführt wird. Wenn Hintergrundmodus ist eine Einstellung, die vom Nutzer aktiviert oder deaktiviert werden kann. sollte Folgendes ausgeführt werden:

    • Speichert den Wert für den Hintergrundmodus jedes Mal in NSUserDefaults, wenn der Nutzer und ändert es.
    • Beim Start aus NSUserDefaults lesen und Nearby wiederherstellen Publikationen und/oder Abos, wenn der Hintergrundmodus aktiviert ist.

Hintergrundbenachrichtigungen

Wenn Sie möchten, dass Ihre App den Nutzer benachrichtigt, wenn ein Abo eine Nachricht erhält Im Hintergrund können Sie lokale Benachrichtigungen.

So fügen Sie sie Ihrer App hinzu:

  • Registrieren Sie sich für lokale Benachrichtigungen beim Start:

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

  • Senden Sie im Handler für Nachrichtenfundierung Ihres Abos eine lokale Benachrichtigung:

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