Veröffentlichen und abonnieren

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

Die Gruppe von Geräten in der Nähe wird durch den Austausch kleiner Tokens über Bluetooth und beinahe-Ultraschall-Audio (unverständlich) 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 gesendet werden müssen.

Eine Anwendung kann die Gruppe von Medien steuern, die für die Geräteerkennung verwendet werden und ob diese zum Übertragen von Tokens und/oder zum Scannen nach Tokens verwendet werden. Standardmäßig werden Übertragungen und Scans auf allen Medien ausgeführt. Wenn du die Erkennung auf einer Teilmenge oder auf Medien durchführen möchtest und um zu bestimmen, ob gesendet oder gescannt werden soll, musst du beim Erstellen von Publikationen und Abos zusätzliche Parameter übergeben.

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 Inhalte veröffentlichen und abonnieren können. Da der Nachrichtenaustausch nicht authentifiziert ist, müssen Sie einen öffentlichen API-Schlüssel für iOS angeben. Sie können eines mithilfe des Eintrags 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")

Mitteilung veröffentlichen

Dieses Code-Snippet zeigt das Veröffentlichen einer Nachricht, die einen Namen enthält. Die Publikation ist aktiv, solange das Publikationsobjekt vorhanden ist. Wenn Sie die Veröffentlichung beenden möchten, lassen Sie das Publikationsobjekt los.

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, dass alle Namen abonniert werden, die vom vorherigen Publikations-Snippet gemeinsam genutzt wurden. Das Abo ist aktiv, solange die Aboobjekte vorhanden sind. Wenn du das Abo beenden möchtest, musst du das Aboobjekt freigeben.

Der Handler für gefundene Nachrichten wird aufgerufen, wenn Geräte in der Nähe gefunden werden, auf denen Nachrichten veröffentlicht werden. Der Handler für verlorene Nachrichten wird aufgerufen, wenn eine Nachricht nicht mehr beobachtet wird (das Gerät hat den Bereich überschritten oder die Nachricht nicht mehr veröffentlicht).

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 Geräte in der Nähe zu finden, und beide Medien werden übertragen und gescannt. In bestimmten Fällen müssen Sie der Info.plist Ihrer Anwendung die folgenden Einträge hinzufügen:

  • Wenn deine App Audio verwendet, füge NSMicrophoneUsageDescription hinzu. Dieser String beschreibt, warum Sie das Mikrofon verwenden. Beispiel: „Das Mikrofon wartet auf anonyme Tokens von Geräten in der Nähe.“

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

In einigen Fällen muss Ihre Anwendung möglicherweise nur eines der Medien verwenden und auf diesem Medium müssen möglicherweise nicht gleichzeitig Daten gesendet und gescannt werden.

Beispielsweise muss eine App, die für die Verbindung mit einer Set-Top-Box entwickelt wurde, die Audiodaten sendet, nur die Audiodaten scannen, um sie zu erkennen. Das folgende Snippet zeigt, wie Sie eine Nachricht in dieser Set-Top-Box nur mithilfe der Audiosuche für die Erkennung veröffentlichen:

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. Dies kann hilfreich sein, um Probleme zu ermitteln, die bei der Integration von Nearby Messages in Ihre App auftreten können. Wir fragen nach diesen Logs, wenn Sie sich an uns wenden, um technischen Support zu erhalten.

Sie müssen ihn aktivieren, bevor Sie einen Nachrichtenmanager erstellen. Dieses Code-Snippet zeigt, wie das Debugging-Logging aktiviert wird:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Nearby-Berechtigungsstatus verfolgen

Zum Aktivieren der Geräteerkennung ist die Einwilligung des Nutzers erforderlich. Dies wird durch den Nearby-Berechtigungsstatus angegeben. Beim ersten Aufruf zum Erstellen einer Publikation oder eines Abos wird dem Nutzer ein Dialog zur Einholung von Einwilligungen angezeigt. Wenn der Nutzer nicht einwilligt, funktioniert die Geräteerkennung nicht. In diesem Fall sollte Ihre App eine Nachricht anzeigen, die den Nutzer daran erinnert, 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 dann aufgerufen, wenn sich der Status ändert. Er wird erst dann aufgerufen, wenn der Nutzer die Berechtigung erteilt oder verweigert hat. Gib 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 eine Ein/Aus-Schaltfläche auf einer Einstellungsseite.

Hier ein Beispiel, 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

Nachverfolgung von Nutzereinstellungen, die Nearby betreffen

Wenn der Nutzer die Mikrofon- oder Bluetooth-Berechtigung verweigert oder Bluetooth deaktiviert hat, funktioniert Nearby ebenfalls nicht oder gar nicht. Ihre App sollte in diesen Fällen eine Meldung anzeigen, mit der der Nutzer darauf hingewiesen wird, dass die Nutzung von Nearby behindert wird. Das folgende Snippet zeigt, wie Sie den Status dieser Nutzereinstellungen verfolgen können, 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 Nearby-Berechtigungen überschreiben

Abhängig von den Parametern, die du an deine Publikationen und Abos übergibst, fordert iOS möglicherweise verschiedene Berechtigungen an, bevor Nearby zugelassen wird. Die Standardstrategie überwacht beispielsweise Daten, die von Nah-Ultraschall-Audio übertragen werden. Daher bittet iOS um Erlaubnis zur Verwendung des Mikrofons. In diesen Fällen zeigt Nearby ein Preflight-Dialogfeld an, in dem erläutert wird, warum der Nutzer um die Berechtigung gebeten wird.

Wenn du ein benutzerdefiniertes „Preflight“-Dialogfeld anzeigen möchtest, setze den Parameter permissionRequestHandler in den Publikations- oder Aboparametern auf einen benutzerdefinierten Block. Der benutzerdefinierte Block muss den permissionHandler-Block aufrufen, nachdem der Nutzer geantwortet hat. Das folgende Snippet zeigt, wie dies 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

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

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

So fügst du einer Publikation oder einem Abo den Hintergrundmodus hinzu:

  • Aktiviere den Hintergrundmodus und die ausschließliche BLE-Funktion in deiner Publikation oder deinem Abo, indem du ein ordnungsgemäß konfiguriertes GNSStrategy-Objekt übergibst. Das folgende Snippet zeigt, wie dies 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 dem Info.plist Ihrer Anwendung diese Einträge hinzu:

    • UIBackgroundModes Einträge:

      • bluetooth-central für BLE-Scans im Hintergrund. Dies ist nur erforderlich, wenn der Erkennungsmodus das Scannen umfasst. Dies ist standardmäßig der Fall.
      • bluetooth-peripheral für BLE-Werbung im Hintergrund. Ist nur erforderlich, wenn der Erkennungsmodus die Übertragung umfasst. Standardmäßig ist er erforderlich.

    • Der String NSBluetoothPeripheralUsageDescription, der beschreibt, warum Sie auf BLE werben. Beispiel: „Ein anonymes Token wird über Bluetooth beworben, 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, während sie im Hintergrund ausgeführt wird. Wenn der Hintergrundmodus vom Nutzer aktiviert oder deaktiviert werden kann, sollte Ihre App so vorgehen:

    • Speichern Sie den Wert für den Hintergrundmodus immer dann in NSUserDefaults, wenn der Nutzer ihn ändert.
    • Beim Start aus NSUserDefaults lesen und die Nearby-Publikationen und/oder -Abos wiederherstellen, wenn der Hintergrundmodus aktiviert ist.

Hintergrundbenachrichtigungen

Wenn du möchtest, dass deine App den Nutzer benachrichtigt, wenn ein Abo im Hintergrund eine Nachricht empfängt, kannst du lokale Benachrichtigungen verwenden.

So fügen Sie sie Ihrer App hinzu:

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