Publikasikan dan Berlangganan

Nearby Messages API adalah API publish-subscribe yang memungkinkan perangkat di sekitar bertukar payload data kecil. Setelah perangkat memublikasikan pesan, perangkat di sekitar dapat menerima pesan tersebut. Ukuran pesan harus tetap cukup kecil untuk mempertahankan performa yang baik. Layanan ini tidak ditujukan untuk menukar objek yang lebih besar seperti foto dan video.

Kumpulan perangkat di sekitar ditentukan oleh pertukaran token kecil melalui audio Bluetooth dan near-ultrasonic (tidak terdengar). Saat mendeteksi token dari perangkat di sekitar, perangkat akan mengirimkan token tersebut ke server Nearby Messages untuk memvalidasinya dan memeriksa apakah ada pesan yang akan dikirimkan untuk kumpulan langganan aplikasi saat ini.

Aplikasi dapat mengontrol set media yang digunakan untuk penemuan perangkat, dan apakah media tersebut digunakan untuk menyiarkan token dan/atau memindai token. Secara default, penyiaran dan pemindaian dilakukan di semua media. Untuk melakukan penemuan pada subset atau media, dan untuk mengontrol apakah akan menyiarkan atau memindai, Anda harus meneruskan parameter tambahan saat membuat publikasi dan langganan.

Library ini berjalan di iOS 7 dan yang lebih baru, serta dibuat dengan iOS 8 SDK.

Membuat pengelola pesan

Kode ini membuat objek pengelola pesan, yang memungkinkan Anda memublikasikan dan berlangganan. Pertukaran pesan tidak diautentikasi, jadi Anda harus memberikan kunci API publik untuk iOS. Anda dapat membuatnya menggunakan entri Google Developers Console untuk project Anda.

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Memublikasikan pesan

Cuplikan kode ini menunjukkan cara memublikasikan pesan yang berisi nama. Publikasi aktif selama objek publikasi ada. Untuk berhenti memublikasikan, lepaskan objek publikasi.

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)))

Berlangganan pesan

Cuplikan kode ini menunjukkan cara berlangganan semua nama yang dibagikan oleh cuplikan publikasi sebelumnya. Langganan aktif selama objek langganan ada. Untuk berhenti berlangganan, lepaskan objek langganan.

Handler pesan yang ditemukan dipanggil saat perangkat di sekitar yang memublikasikan pesan ditemukan. Handler pesan hilang dipanggil saat pesan tidak lagi diamati (perangkat telah keluar dari jangkauan atau tidak lagi memublikasikan pesan).

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

Media penemuan

Secara default, kedua media (audio dan Bluetooth) akan digunakan untuk menemukan perangkat di sekitar, dan kedua media akan menyiarkan dan memindai. Untuk kasus tertentu, Anda diwajibkan menambahkan entri berikut ke Info.plist aplikasi Anda:

  • Jika aplikasi Anda memindai menggunakan audio, tambahkan NSMicrophoneUsageDescription, yang merupakan string yang menjelaskan alasan Anda akan menggunakan mikrofon. Misalnya, "Mikrofon mendengarkan token anonim dari perangkat di sekitar."

  • Jika aplikasi Anda melakukan siaran menggunakan BLE, tambahkan NSBluetoothPeripheralUsageDescription, yang merupakan string yang menjelaskan alasan Anda akan beriklan di BLE. Misalnya, "Token anonim diiklankan melalui Bluetooth untuk menemukan perangkat di sekitar."

Dalam beberapa kasus, aplikasi Anda mungkin hanya perlu menggunakan salah satu media, dan mungkin tidak perlu melakukan penyiaran dan pemindaian di media tersebut.

Misalnya, aplikasi yang didesain untuk terhubung ke set-top box yang menyiarkan audio saja hanya perlu memindai audio untuk menemukannya. Cuplikan berikut menunjukkan cara memublikasikan pesan ke set-top box tersebut hanya menggunakan pemindaian audio untuk penemuan:

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

Mengaktifkan logging debug

Pencatatan log debug mencetak peristiwa internal penting ke konsol yang dapat berguna untuk melacak masalah yang mungkin Anda alami saat mengintegrasikan Nearby Messages ke dalam aplikasi Anda. Kami akan meminta log ini jika Anda menghubungi kami untuk mendapatkan dukungan teknis.

Anda harus mengaktifkannya sebelum membuat pengelola pesan. Cuplikan kode ini menunjukkan cara mengaktifkan logging debug:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Melacak status izin Perangkat di sekitar

Izin pengguna diperlukan untuk mengaktifkan penemuan perangkat. Hal ini ditunjukkan oleh status izin Terdekat. Pada panggilan pertama untuk membuat publikasi atau langganan, pengguna akan melihat dialog izin. Jika pengguna tidak memberikan izin, penemuan perangkat tidak akan berfungsi. Dalam hal ini, aplikasi Anda harus menampilkan pesan untuk mengingatkan pengguna bahwa penemuan perangkat dinonaktifkan. Status izin disimpan di NSUserDefaults.

Cuplikan berikut menunjukkan cara berlangganan status izin. Handler perubahan status izin dipanggil setiap kali status berubah, dan tidak dipanggil untuk pertama kalinya hingga pengguna memberikan atau menolak izin. Lepaskan objek izin untuk berhenti berlangganan.

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

Aplikasi Anda dapat menyediakan cara bagi pengguna untuk mengubah status izin; misalnya, dengan menggunakan tombol di halaman setelan.

Berikut adalah contoh cara mendapatkan dan menyetel status izin.

Objective-C

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

Swift

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

Melacak setelan pengguna yang memengaruhi Nearby

Jika pengguna telah menolak izin mikrofon, menolak izin Bluetooth, atau telah menonaktifkan Bluetooth, fitur Di Sekitar juga tidak akan berfungsi, atau mungkin tidak berfungsi sama sekali. Aplikasi Anda harus menampilkan pesan dalam kasus ini, yang memberi tahu pengguna bahwa operasi Nearby terhambat. Cuplikan berikut menunjukkan cara melacak status setelan pengguna ini dengan meneruskan handler saat membuat pengelola pesan:

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

Mengganti dialog izin Perangkat di sekitar

Bergantung pada parameter yang Anda teruskan ke publikasi dan langganan, iOS dapat meminta berbagai izin sebelum mengizinkan Nearby berfungsi. Misalnya, strategi default memproses data yang ditransmisikan melalui audio hampir ultrasonik, sehingga iOS akan meminta izin untuk menggunakan mikrofon. Dalam kasus ini, Nearby akan menampilkan dialog "penerbangan awal" yang menjelaskan alasan pengguna diminta untuk memberikan izin.

Jika Anda ingin menyediakan dialog "penerbangan awal" kustom, tetapkan parameter permissionRequestHandler ke blok kustom di parameter publikasi atau langganan. Blok kustom Anda harus memanggil blok permissionHandler setelah pengguna merespons. Cuplikan berikut menunjukkan cara melakukannya untuk publikasi:

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

Operasi latar belakang

Publikasi dan langganan yang menggunakan BLE untuk penemuan perangkat dapat berfungsi di latar belakang. Berikut beberapa hal yang harus Anda perhatikan saat memutuskan untuk menggunakan mode latar belakang:

  • Operasi latar belakang hanya boleh menggunakan media BLE; audio tidak didukung.
  • Ada biaya baterai tambahan untuk BLE di latar belakang. Biayanya rendah, tetapi Anda harus mengukurnya sebelum memutuskan untuk menggunakan mode latar belakang.
  • iOS akan meminta izin pengguna untuk mengiklankan melalui BLE di latar belakang.

Untuk menambahkan mode latar belakang ke publikasi atau langganan, ikuti langkah-langkah tambahan berikut:

  • Aktifkan mode latar belakang dan khusus BLE di publikasi atau langganan Anda dengan meneruskan objek GNSStrategy yang dikonfigurasi dengan benar. Cuplikan berikut menunjukkan cara melakukannya untuk langganan:

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

  • Tambahkan entri ini ke Info.plist aplikasi Anda:

    • UIBackgroundModes entri:

      • bluetooth-central untuk pemindaian BLE di latar belakang. Hanya diperlukan jika mode penemuan mencakup pemindaian; secara default, mode ini mencakup pemindaian.
      • bluetooth-peripheral untuk iklan BLE di latar belakang. Diperlukan hanya jika mode penemuan mencakup penyiaran; mode ini diaktifkan secara default.

    • String NSBluetoothPeripheralUsageDescription yang menjelaskan alasan Anda akan beriklan di BLE. Misalnya, "Token anonim diiklankan melalui Bluetooth untuk menemukan perangkat di sekitar." Lihat dokumentasi Apple untuk mengetahui detailnya.

  • Aplikasi Anda dapat dihentikan kapan saja oleh sistem saat berada di latar belakang. Jika mode latar belakang adalah setelan yang dapat diaktifkan atau dinonaktifkan oleh pengguna, aplikasi Anda harus melakukan hal berikut:

    • Simpan nilai mode latar belakang ke NSUserDefaults setiap kali pengguna mengubahnya.
    • Saat startup, baca dari NSUserDefaults dan pulihkan publikasi dan/atau langganan Nearby jika mode latar belakang diaktifkan.

Notifikasi latar belakang

Jika Anda ingin aplikasi memberi tahu pengguna saat langganan menerima pesan di latar belakang, Anda dapat menggunakan notifikasi lokal.

Ikuti langkah-langkah berikut untuk menambahkannya ke aplikasi Anda:

  • Mendaftar untuk notifikasi lokal saat startup:

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

  • Kirim notifikasi lokal di pengendali message-found langganan Anda:

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