Veröffentlichen und abonnieren

Die Nearby Messages API ist eine Publish-Subscribe-API, mit der Geräte in der Nähe kleine Datennutzlasten austauschen können. Sobald ein Gerät eine Nachricht veröffentlicht hat, können Geräte in der Nähe diese Nachricht empfangen. Die Nachrichtengröße sollte möglichst klein gehalten werden, um eine gute Leistung zu erzielen. Dieser Dienst ist nicht für den Austausch größerer Objekte wie Fotos und Videos gedacht.

Die Geräte in der Nähe werden durch den Austausch kleiner Tokens über Bluetooth und Nah-Ultraschall (nicht hörbar) bestimmt. Wenn ein Gerät ein Token von einem Gerät in der Nähe erkennt, sendet es das Token an den Nearby Messages-Server, um es zu validieren und zu prüfen, ob Nachrichten für die aktuellen Abos der Anwendung zuzustellen sind.

Eine Anwendung kann die Medien steuern, die für die Gerätesuche verwendet werden, und festlegen, ob die Medien zum Übertragen von Tokens und/oder zum Scannen nach Tokens verwendet werden. Standardmäßig werden die Übertragung und das Scannen auf allen Medien ausgeführt. Wenn Sie die Suche auf eine Teilmenge oder Medien beschränken und festlegen möchten, ob gesendet oder gescannt werden soll, müssen Sie beim Erstellen von Publikationen und Abos zusätzliche Parameter übergeben.

Diese Bibliothek ist für iOS 7 und höher verfügbar und wird mit dem iOS 8 SDK erstellt.

Message Manager erstellen

Mit diesem Code wird ein Message Manager-Objekt erstellt, mit dem Sie Nachrichten veröffentlichen und abonnieren können. Der Nachrichtenaustausch ist nicht authentifiziert. Sie müssen daher einen öffentlichen API-Schlüssel für iOS angeben. Sie können einen über den Eintrag für Ihr Projekt in der Google Developers Console erstellen.

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Mitteilung veröffentlichen

In diesem Code-Snippet wird das Veröffentlichen einer Nachricht mit einem Namen veranschaulicht. Die Veröffentlichung ist aktiv, solange das Veröffentlichungsobjekt vorhanden ist. Wenn Sie die Veröffentlichung beenden möchten, geben Sie das Veröffentlichungsobjekt 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)))

Nachrichten abonnieren

In diesem Code-Snippet wird gezeigt, wie alle Namen abonniert werden, die im vorherigen Veröffentlichungs-Snippet geteilt wurden. Das Abo ist so lange aktiv, wie die Abo-Objekte vorhanden sind. Wenn Sie das Abo beenden möchten, geben Sie das Aboobjekt frei.

Der Handler für gefundene Nachrichten wird aufgerufen, wenn Geräte in der Nähe gefunden werden, die Nachrichten veröffentlichen. Der Handler für verlorene Nachrichten wird aufgerufen, wenn eine Nachricht nicht mehr empfangen wird (das Gerät ist außer Reichweite oder veröffentlicht die Nachricht nicht mehr).

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

Standardmäßig werden beide Medien (Audio und Bluetooth) verwendet, um Geräte in der Nähe zu erkennen. Beide Medien werden übertragen und gescannt. In bestimmten Fällen müssen Sie der Info.plist Ihrer App die folgenden Einträge hinzufügen:

  • Wenn Ihre App Audio verwendet, fügen Sie NSMicrophoneUsageDescription hinzu. Dies ist ein String, der beschreibt, warum Sie das Mikrofon verwenden. Beispiel: „Das Mikrofon achtet auf anonyme Tokens von Geräten in der Nähe.“

  • Wenn Ihre App per BLE sendet, fügen Sie NSBluetoothPeripheralUsageDescription hinzu. Dies ist ein String, der beschreibt, warum Sie per BLE werben. Beispiel: „Ein anonymes Token wird über Bluetooth gesendet, um Geräte in der Nähe zu finden.“

In einigen Fällen muss Ihre App möglicherweise nur eines der Medien verwenden und es ist nicht erforderlich, dass auf diesem Medium sowohl gesendet als auch gescannt wird.

Eine App, die beispielsweise für die Verbindung mit einem Set-Top-Box-Gerät entwickelt wurde, das nur Audio überträgt, muss nur nach Audio suchen, um es zu finden. Im folgenden Snippet wird gezeigt, wie du eine Nachricht auf diesem Set-Top-Box veröffentlichst, indem du nur Audioscans zur Erkennung verwendest:

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

Debug-Logging aktivieren

Bei der Debug-Protokollierung werden wichtige interne Ereignisse in der Konsole ausgegeben. Diese können hilfreich sein, um Probleme bei der Einbindung von Nearby Messages in Ihre App zu finden. Wir bitten Sie um diese Protokolle, wenn Sie uns wegen technischen Supports kontaktieren.

Sie sollten sie aktivieren, bevor Sie einen Nachrichtenmanager erstellen. In diesem Code-Snippet wird gezeigt, wie Sie die Debug-Protokollierung aktivieren:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Status der Nearby-Berechtigung verfolgen

Die Nutzereinwilligung ist erforderlich, um die Gerätesuche zu aktivieren. Dies wird durch den Status der Berechtigung „In der Nähe“ angezeigt. Beim ersten Aufruf zum Erstellen einer Publikation oder eines Abos wird dem Nutzer ein Einwilligungsdialog angezeigt. Wenn der Nutzer nicht einwilligt, funktioniert die Geräteerkennung nicht. In diesem Fall sollte Ihre App dem Nutzer eine Nachricht anzeigen, dass die Gerätesuche deaktiviert ist. Der Berechtigungsstatus wird in NSUserDefaults gespeichert.

Im folgenden Snippet wird gezeigt, wie Sie den Berechtigungsstatus abonnieren. Der Handler für die Änderung des Berechtigungsstatus wird jedes Mal aufgerufen, wenn sich der Status ändert. Er wird erst zum ersten Mal aufgerufen, wenn der Nutzer die Berechtigung erteilt oder abgelehnt hat. Hebe die Sperre des Berechtigungsobjekts auf, um das Abonnieren 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 kann Nutzern die Möglichkeit bieten, den Berechtigungsstatus zu ändern, z. B. über einen Ein/Aus-Schalter auf einer Einstellungsseite.

Hier ist ein Beispiel dafür, wie Sie den Berechtigungsstatus abrufen und festlegen.

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 beziehen

Wenn der Nutzer die Mikrofon- oder Bluetooth-Berechtigung verweigert oder Bluetooth deaktiviert hat, funktioniert Nearby nicht optimal oder gar nicht. In diesen Fällen sollte Ihre App eine Meldung anzeigen, in der der Nutzer darüber informiert wird, dass die Nearby-Funktion beeinträchtigt ist. Im folgenden Snippet wird gezeigt, wie Sie den Status dieser Nutzereinstellungen verfolgen, indem Sie beim Erstellen des Message Managers Handler übergeben:

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 für die Berechtigung „In der Nähe“ überschreiben

Je nach den Parametern, die Sie in Ihre Publikationen und Abos übergeben, werden unter iOS möglicherweise verschiedene Berechtigungen angefordert, bevor Nearby funktioniert. Die Standardstrategie prüft beispielsweise, ob Daten per Ultraschall übertragen werden. In diesem Fall wird auf dem iPhone die Berechtigung zur Verwendung des Mikrofons angefordert. In diesen Fällen wird in Nearby ein Vorab-Dialogfeld angezeigt, in dem erklärt wird, warum der Nutzer um die Berechtigung gebeten wird.

Wenn du ein benutzerdefiniertes Preflight-Dialogfeld einblenden möchtest, setze den Parameter permissionRequestHandler in den Parametern für die Publikation oder das Abo auf einen benutzerdefinierten Block. Ihr benutzerdefinierter Block muss den permissionHandler-Block aufrufen, nachdem der Nutzer geantwortet hat. Das folgende Snippet zeigt, wie das für eine Publikation geht:

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

Hintergrundbetrieb

Publikationen und Abos, die BLE für die Geräteerkennung verwenden, können im Hintergrund ausgeführt werden. Wenn Sie den Hintergrundmodus verwenden, sollten Sie Folgendes beachten:

  • Für Hintergrundvorgänge darf nur das BLE-Medium verwendet werden. Audio wird nicht unterstützt.
  • Für die Hintergrund-BLE-Nutzung fallen zusätzliche Akkukosten an. Die Kosten sind gering, aber Sie sollten sie messen, bevor Sie sich für den Hintergrundmodus entscheiden.
  • iOS fragt den Nutzer um Erlaubnis, im Hintergrund per BLE zu werben.

Wenn du einer Publikation oder einem Abo den Hintergrundmodus hinzufügen möchtest, gehe so vor:

  • Aktivieren Sie den Hintergrundmodus und BLE-only in Ihrer Publikation oder Ihrem Abo, indem Sie ein ordnungsgemäß konfiguriertes GNSStrategy-Objekt übergeben. Das folgende Snippet zeigt, wie das für ein Abo funktioniert:

    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 der Datei Info.plist Ihrer App die folgenden Einträge hinzu:

    • UIBackgroundModes Einträge:

      • bluetooth-central für BLE-Scans im Hintergrund. Nur erforderlich, wenn der Discovery-Modus das Scannen umfasst. Das ist standardmäßig der Fall.
      • bluetooth-peripheral für BLE-Werbung im Hintergrund. Nur erforderlich, wenn der Discovery-Modus die Übertragung umfasst. Das ist standardmäßig der Fall.

    • NSBluetoothPeripheralUsageDescription-String, in dem Sie angeben, warum Sie BLE-Werbung schalten möchten Beispiel: „Ein anonymes Token wird über Bluetooth gesendet, um Geräte in der Nähe zu finden.“ Weitere Informationen finden Sie in der Dokumentation von Apple.

  • Ihre App kann vom System jederzeit im Hintergrund beendet werden. Wenn der Hintergrundmodus eine Einstellung ist, die vom Nutzer aktiviert oder deaktiviert werden kann, sollte Ihre App Folgendes tun:

    • Speichern Sie den Wert für den Hintergrundmodus in NSUserDefaults, wenn der Nutzer ihn ändert.
    • Beim Starten wird es aus NSUserDefaults gelesen und die Nearby-Publikationen und/oder ‑Abos werden wiederhergestellt, wenn der Hintergrundmodus aktiviert ist.

Hintergrundbenachrichtigungen

Wenn Ihre App den Nutzer benachrichtigen soll, wenn ein Abo im Hintergrund eine Nachricht erhält, können Sie lokale Benachrichtigungen verwenden.

So fügen Sie sie Ihrer App hinzu:

  • So registrieren Sie sich für lokale Benachrichtigungen beim Starten:

    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 eine lokale Benachrichtigung im Handler für gefundene Nachrichten Ihres Abos:

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