Veröffentlichen und abonnieren

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

Die Gruppe der Geräte in der Nähe wird durch den Austausch kleiner Tokens über Bluetooth und Audio im Bereich des oberen Hörbereichs (nicht hörbar) bestimmt. Wenn ein Gerät ein Token von einem Gerät in der Nähe erkennt, wird das Token an den Nearby Messages-Server gesendet, um es zu validieren und zu prüfen, ob Nachrichten für die aktuellen Abonnements der Anwendung gesendet werden müssen.

Eine Anwendung kann die für die Geräteerkennung verwendeten Medien sowie die Verwendung der Medien zum Senden von Tokens und/oder zum Scannen nach Tokens steuern. Standardmäßig werden Broadcasts und Scans auf allen Medien durchgeführt. Wenn Sie die Erkennung auf eine Teilmenge oder bestimmte Media beschränken und steuern möchten, ob gesendet oder gescannt werden soll, müssen Sie beim Erstellen von Publikationen und Abonnements zusätzliche Parameter übergeben.

Diese Bibliothek wird unter iOS 7 und höher ausgeführt und 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 also einen öffentlichen API-Schlüssel für iOS angeben. Sie können ein Projekt über den Google Developers Console-Eintrag für Ihr Projekt erstellen.

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Nachricht veröffentlichen

Dieses Code-Snippet zeigt, wie eine Nachricht mit einem Namen veröffentlicht wird. Die Veröffentlichung ist aktiv, solange das Veröffentlichungsobjekt vorhanden ist. Um die Veröffentlichung zu beenden, 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)))

Nachrichten abonnieren

In diesem Code-Snippet wird gezeigt, wie Sie alle Namen abonnieren, die vom vorherigen Publikations-Snippet freigegeben wurden. Das Abo ist aktiv, solange die Abo-Objekte vorhanden sind. Wenn Sie das Abonnieren 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 hat die Reichweite verlassen 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
    })

Möglichkeiten zum Entdecken von Inhalten

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

  • Wenn Ihre App Audio zum Scannen verwendet, fügen Sie NSMicrophoneUsageDescription hinzu. Das 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 BLE für die Übertragung verwendet, fügen Sie NSBluetoothPeripheralUsageDescription hinzu. Das ist ein String, der beschreibt, warum Sie BLE für Werbung verwenden. Beispiel: „Ein anonymes Token wird über Bluetooth übertragen, um Geräte in der Nähe zu erkennen.“

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

Eine App, die für die Verbindung mit einer Set-Top-Box entwickelt wurde, die nur Audio überträgt, muss beispielsweise nur nach Audio scannen, um sie zu erkennen. Das folgende Snippet zeigt, wie Sie eine Nachricht auf diesem Gerät veröffentlichen, indem Sie nur die Audioerkennung verwenden:

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

Beim Debug-Logging werden wichtige interne Ereignisse in der Konsole ausgegeben. Das kann hilfreich sein, um Probleme zu beheben, die bei der Integration von Nearby Messages in Ihre App auftreten. Wir werden Sie um diese Logs bitten, wenn Sie uns wegen technischen Supports kontaktieren.

Sie sollten sie aktivieren, bevor Sie einen Message Manager erstellen. Dieses Code-Snippet zeigt, wie Sie das Debug-Logging aktivieren:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Status der Nearby-Berechtigung verfolgen

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

Das folgende Snippet zeigt, wie Sie den Berechtigungsstatus abonnieren. Der Handler für Änderungen des Berechtigungsstatus wird immer dann aufgerufen, wenn sich der Status ändert. Beim ersten Mal wird er erst aufgerufen, wenn der Nutzer die Berechtigung erteilt oder verweigert hat. Geben Sie das Berechtigungsobjekt frei, 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 kann dem Nutzer 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 können.

Objective-C

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

Swift

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

Nutzereinstellungen für Nearby-Funktionen

Wenn der Nutzer die Mikrofonberechtigung oder die Bluetooth-Berechtigung verweigert oder Bluetooth deaktiviert hat, funktioniert Nearby nicht richtig oder möglicherweise gar nicht. In diesen Fällen sollte in Ihrer App eine Meldung angezeigt werden, in der der Nutzer darauf hingewiesen wird, dass die Funktionen von Nearby eingeschränkt sind. Im folgenden Snippet sehen Sie, wie Sie den Status dieser Nutzereinstellungen erfassen, 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 an Ihre Publikationen und Abonnements übergeben, fordert iOS möglicherweise verschiedene Berechtigungen an, bevor Nearby funktioniert. Bei der Standardstrategie wird beispielsweise auf Daten geachtet, die über Audio im Bereich des oberen Ultraschalls übertragen werden. Daher wird in iOS um die Berechtigung zur Verwendung des Mikrofons gebeten. In diesen Fällen wird in Nearby ein Dialogfeld angezeigt, in dem erklärt wird, warum der Nutzer um die Erteilung der Berechtigung gebeten wird.

Wenn Sie ein benutzerdefiniertes Dialogfeld für den Preflight-Check bereitstellen möchten, legen Sie den Parameter permissionRequestHandler auf einen benutzerdefinierten Block in den Publikations- oder Aboparametern fest. 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.
          }
        })

Hintergrundvorgang

Veröffentlichungen und Abos, bei denen BLE zur Geräteerkennung verwendet wird, können im Hintergrund ausgeführt werden. Wenn Sie den Hintergrundmodus verwenden möchten, sollten Sie Folgendes beachten:

  • Für Hintergrundvorgänge darf nur das BLE-Medium verwendet werden. Audio wird nicht unterstützt.
  • Für Bluetooth Low Energy im Hintergrund fallen zusätzliche Akkukosten an. Die Kosten sind gering, aber Sie sollten sie messen, bevor Sie sich für die Verwendung des Hintergrundmodus entscheiden.
  • iOS bittet den Nutzer um die Erlaubnis, im Hintergrund Werbung über BLE zu schalten.

So fügen Sie einer Publikation oder einem Abo den Hintergrundmodus hinzu:

  • Aktivieren Sie den Hintergrundmodus und BLE-only in Ihrer Publikation oder Ihrem Abo, indem Sie ein richtig konfiguriertes GNSStrategy-Objekt übergeben. 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 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 Erkennungsmodus das Scannen umfasst. Das ist standardmäßig der Fall.
      • bluetooth-peripheral für BLE-Werbung im Hintergrund. Nur erforderlich, wenn der Erkennungsmodus Broadcasting umfasst. Das ist standardmäßig der Fall.

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

  • Ihre App kann jederzeit vom System beendet werden, wenn sie im Hintergrund ausgeführt wird. 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.
    • Lesen Sie sie beim Start aus NSUserDefaults und stellen Sie die Nearby-Veröffentlichungen und/oder ‑Abos wieder her, 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:

  • Bei Start für lokale Benachrichtigungen registrieren:

    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 „message-found“ 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...
}