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 gewährleisten. Dieser Dienst ist nicht für den Austausch größerer Objekte wie Fotos und Videos vorgesehen.

Die Menge der Geräte in der Nähe wird durch den Austausch kleiner Tokens über Bluetooth und Audio im Bereich des Ultraschalls (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 aktuelle Menge der Abos der Anwendung bereitgestellt werden müssen.

Eine Anwendung kann die Menge der für die Geräteerkennung verwendeten Medien steuern und festlegen, ob die Medien zum Senden von Tokens und/oder zum Scannen nach Tokens verwendet werden. Standardmäßig werden Tokens über alle Medien gesendet und alle Medien werden nach Tokens gescannt. Wenn Sie die Erkennung auf eine Teilmenge von Medien beschränken und festlegen möchten, ob Tokens gesendet oder nach Tokens gescannt werden soll, müssen Sie beim Erstellen von Veröffentlichungen und Abos zusätzliche Parameter übergeben.

Diese Bibliothek wird unter iOS 7 und höher ausgeführt und mit dem iOS 8 SDK erstellt.

Nachrichtenmanager erstellen

Mit diesem Code wird ein Nachrichtenmanagerobjekt erstellt, mit dem Sie Nachrichten veröffentlichen und abonnieren können. Der Nachrichtenaustausch ist nicht authentifiziert. Daher müssen Sie einen öffentlichen API-Schlüssel für iOS angeben. Sie können einen API-Schlüssel ü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 Sie eine Nachricht mit einem Namen veröffentlichen. 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

Dieses Code-Snippet zeigt, wie Sie alle Namen abonnieren, die vom vorherigen Veröffentlichungssnippet freigegeben wurden. Das Abo ist aktiv, solange das Aboobjekt vorhanden ist. 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 beobachtet 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
    })

Erkennungsmedien

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

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

  • Wenn Ihre App BLE zum Senden von Tokens verwendet, fügen Sie NSBluetoothPeripheralUsageDescription hinzu. Dies ist ein String, der beschreibt, warum Sie BLE verwenden. Beispiel: „Ein anonymes Token wird über Bluetooth gesendet, um Geräte in der Nähe zu erkennen.“

In einigen Fällen muss Ihre App möglicherweise nur eines der Medien verwenden und es ist nicht erforderlich, dass Tokens über dieses Medium gesendet und nach Tokens gescannt wird.

Eine App, die für die Verbindung mit einer Set-Top-Box entwickelt wurde, die nur Audio sendet, muss beispielsweise nur Audio scannen, um sie zu erkennen. Das folgende Code-Snippet zeigt, wie Sie eine Nachricht an diese Set-Top-Box senden, indem Sie nur Audio zum Scannen 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 können. Wir bitten Sie um diese Logs, wenn Sie sich an den technischen Support wenden.

Sie sollten das Debug-Logging aktivieren, bevor Sie einen Nachrichtenmanager 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. Das wird durch den Status der Nearby-Berechtigung angegeben. Beim ersten Aufruf zum Erstellen einer Veröffentlichung oder eines Abos wird dem Nutzer ein Einwilligungsdialogfeld angezeigt. Wenn der Nutzer nicht einwilligt, funktioniert die Geräteerkennung nicht. In diesem Fall sollte Ihre App eine Nachricht anzeigen, um den Nutzer daran zu erinnern, dass die Geräteerkennung deaktiviert ist. Der Berechtigungsstatus wird in NSUserDefaults gespeichert.

Das folgende Code-Snippet zeigt, wie Sie den Berechtigungsstatus abonnieren. Der Handler für geänderte Berechtigungsstatus wird immer aufgerufen, wenn sich der Status ändert. Beim ersten Mal wird er erst aufgerufen, wenn der Nutzer die Berechtigung erteilt oder abgelehnt 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 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 verfolgen, die sich auf Nearby auswirken

Wenn der Nutzer die Mikrofonberechtigung oder die Bluetooth-Berechtigung abgelehnt oder Bluetooth deaktiviert hat, funktioniert Nearby nicht so gut oder möglicherweise gar nicht. In diesen Fällen sollte Ihre App eine Nachricht anzeigen, um den Nutzer darauf hinzuweisen, dass die Vorgänge von Nearby beeinträchtigt werden. Das folgende Code-Snippet zeigt, wie Sie den Status dieser Nutzereinstellungen verfolgen, indem Sie beim Erstellen des Nachrichtenmanagers 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 Nearby-Berechtigung überschreiben

Je nach den Parametern, die Sie an Ihre Veröffentlichungen und Abos übergeben, fordert iOS möglicherweise verschiedene Berechtigungen an, bevor Nearby verwendet werden kann. Die Standardstrategie sucht beispielsweise nach Daten, die über Audio im Bereich des Ultraschalls übertragen werden. Daher fordert iOS die Berechtigung zur Verwendung des Mikrofons an. In diesen Fällen zeigt Nearby ein Dialogfeld an, in dem erklärt wird, warum der Nutzer um die Erteilung der Berechtigung gebeten wird.

Wenn Sie ein benutzerdefiniertes Dialogfeld anzeigen möchten, legen Sie den Parameter permissionRequestHandler in den Veröffentlichungs- oder Aboparametern auf einen benutzerdefinierten Block fest. Ihr benutzerdefinierter Block muss den Block permissionHandler aufrufen, nachdem der Nutzer geantwortet hat. Das folgende Code-Snippet zeigt, wie Sie das für eine Veröffentlichung tun:

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

Veröffentlichungen und Abos, die BLE für die Geräteerkennung verwenden, 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 BLE im Hintergrund fallen zusätzliche Akkukosten an. Die Kosten sind gering, aber Sie sollten sie messen, bevor Sie sich für den Hintergrundmodus entscheiden.
  • iOS bittet den Nutzer um die Berechtigung, Tokens über BLE im Hintergrund zu senden.

So fügen Sie einer Veröffentlichung oder einem Abo den Hintergrundmodus hinzu:

  • Aktivieren Sie den Hintergrundmodus und die Verwendung von BLE in Ihrer Veröffentlichung oder Ihrem Abo, indem Sie ein entsprechend konfiguriertes GNSStrategy-Objekt übergeben. Das folgende Code-Snippet zeigt, wie Sie das für ein Abo tun:

    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 das Scannen nach BLE-Geräten im Hintergrund. Nur erforderlich, wenn der Erkennungsmodus das Scannen umfasst. Das ist standardmäßig der Fall.
      • bluetooth-peripheral für das Senden von Tokens über BLE im Hintergrund. Nur erforderlich, wenn der Erkennungsmodus das Senden von Tokens umfasst. Das ist standardmäßig der Fall.

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

  • Ihre App kann vom System jederzeit 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 den Wert 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 eine Nachricht empfängt im Hintergrund, können Sie lokale Benachrichtigungenverwenden.

So fügen Sie sie Ihrer App hinzu:

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

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