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 sie 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 Geräte in der Nähe werden durch den Austausch kleiner Tokens über Bluetooth und Audio im Bereich des Ultraschalls (nicht hörbar) ermittelt. 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 bereitgestellt werden müssen.

Eine Anwendung kann die für die Geräteerkennung verwendeten Medien festlegen und bestimmen, ob die Medien zum Senden und/oder Scannen von Tokens verwendet werden. Standardmäßig werden Tokens über alle Medien gesendet und alle Medien werden gescannt. Wenn Sie die Erkennung auf eine Teilmenge von Medien beschränken und festlegen möchten, ob Tokens gesendet oder gescannt werden sollen, 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 solchen Schlüssel in der Google Developers Console 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 im vorherigen Veröffentlichungs-Snippet 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 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. Das 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 verwendet, fügen Sie NSBluetoothPeripheralUsageDescription hinzu. Das 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 gescannt werden.

Eine App, die für die Verbindung mit einer Set-Top-Box entwickelt wurde, die nur Audio sendet, muss beispielsweise nur Audio scannen, um die Set-Top-Box zu erkennen. Das folgende 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 Einwilligungsdialog 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 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 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
      }
    })

Dialog zur 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 einen Vorabdialog an, in dem erklärt wird, warum der Nutzer um die Erteilung einer Berechtigung gebeten wird.

Wenn Sie ein benutzerdefiniertes Preflight-Dialogfeld verwenden 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 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, BLE im Hintergrund zu verwenden.

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

    • UIBackgroundModes-Einträge:

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