Publikasikan dan Berlangganan

Nearby Messages API adalah API publikasi-langganan yang memungkinkan perangkat di sekitar bertukar payload data dalam jumlah kecil. Setelah perangkat memublikasikan pesan, perangkat di sekitar dapat menerima pesan tersebut. Ukuran pesan harus dijaga agar tetap kecil untuk mempertahankan performa yang baik. Layanan ini tidak dimaksudkan untuk menukar objek yang lebih besar seperti foto dan video.

Kumpulan perangkat di sekitar ditentukan oleh pertukaran token kecil melalui Bluetooth dan audio yang mendekati ultrasonik (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 rangkaian langganan aplikasi saat ini.

Aplikasi dapat mengontrol kumpulan 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 subkumpulan 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 di-build dengan iOS 8 SDK.

Membuat pengelola pesan

Kode ini membuat objek pengelola pesan, yang memungkinkan Anda memublikasikan dan berlangganan. Pertukaran pesan tidak diautentikasi, sehingga 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 publikasi pesan yang berisi nama. Publikasi aktif selama objek publikasi ada. Untuk berhenti memublikasikan, rilis 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 berlangganan ke semua nama yang dibagikan oleh cuplikan publikasi sebelumnya. Langganan aktif selama objek langganan ada. Untuk berhenti berlangganan, lepaskan objek langganan.

Pengendali pesan yang ditemukan dipanggil saat perangkat di sekitar yang memublikasikan pesan ditemukan. Pengendali pesan yang 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 harus menambahkan entri berikut ke Info.plist aplikasi:

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

  • Jika aplikasi Anda menyiarkan 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 pada media tersebut.

Misalnya, aplikasi yang dirancang untuk terhubung ke dekoder yang melakukan siaran dalam audio hanya perlu memindai audio untuk menemukannya. Cuplikan berikut menunjukkan cara memublikasikan pesan ke dekoder tersebut dengan 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

Logging debug mencetak peristiwa internal yang signifikan ke konsol, yang dapat berguna untuk melacak masalah yang mungkin Anda alami saat mengintegrasikan Pesan Di Sekitar ke aplikasi. 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 Di sekitar

Izin pengguna diperlukan untuk mengaktifkan penemuan perangkat. Hal ini ditunjukkan oleh status izin Di Sekitar. 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. Pengendali status izin yang diubah akan dipanggil setiap kali status berubah, dan tidak dipanggil pertama kali 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 dapat menyediakan cara bagi pengguna untuk mengubah status izin; misalnya, dengan menggunakan tombol pengalihan di halaman setelan.

Berikut adalah contoh cara mendapatkan dan menetapkan 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 fitur Di Sekitar

Jika pengguna telah menolak izin mikrofon, menolak izin Bluetooth, atau menonaktifkan Bluetooth, fitur Di Sekitar tidak akan berfungsi juga, atau mungkin tidak berfungsi sama sekali. Dalam kasus ini, aplikasi Anda akan menampilkan pesan, yang memberi tahu pengguna bahwa operasi Di Sekitar sedang terhambat. Cuplikan berikut menunjukkan cara melacak status setelan pengguna tersebut dengan meneruskan pengendali 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 Di Sekitar

Bergantung pada parameter yang Anda teruskan ke publikasi dan langganan, iOS mungkin akan meminta berbagai izin sebelum mengizinkan fitur Di Sekitar berfungsi. Misalnya, strategi default memproses data yang ditransmisikan di audio yang mendekati frekuensi ultrasonik, sehingga iOS akan meminta izin untuk menggunakan mikrofon. Dalam hal ini, Nearby akan menampilkan dialog "preflight" yang menjelaskan alasan pengguna diminta untuk memberikan izin.

Jika Anda ingin menyediakan dialog "preflight" kustom, tetapkan parameter permissionRequestHandler ke pemblokiran kustom dalam parameter publikasi atau langganan. Elemen penyusun 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 berjalan di latar belakang. Berikut adalah beberapa hal yang harus Anda ketahui saat memutuskan untuk menggunakan mode latar belakang:

  • Operasi latar belakang hanya boleh menggunakan media BLE; audio tidak didukung.
  • Ada biaya baterai tambahan untuk BLE latar belakang. Biayanya rendah, tetapi Anda harus mengukurnya sebelum memutuskan untuk menggunakan mode latar belakang.
  • iOS akan meminta izin pengguna untuk beriklan 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 dalam 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 berikut ke Info.plist aplikasi Anda:

    • Entri UIBackgroundModes:

      • bluetooth-central untuk pemindaian BLE di latar belakang. Hanya diperlukan saat mode penemuan menyertakan pemindaian; mode ini berfungsi secara default.
      • bluetooth-peripheral untuk iklan BLE di latar belakang. Hanya diperlukan saat mode penemuan mencakup penyiaran; mode ini berfungsi secara default.

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

  • Aplikasi Anda dapat dihentikan kapan saja oleh sistem saat berada di latar belakang. Jika mode latar belakang merupakan 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 memulai, baca dari NSUserDefaults lalu pulihkan publikasi dan/atau langganan Nearby jika mode latar belakang diaktifkan.

Notifikasi latar belakang

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

Ikuti langkah-langkah berikut untuk menambahkannya ke aplikasi Anda:

  • Daftar untuk mendapatkan notifikasi lokal saat browser dimulai:

    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 langganan yang ditemukan pesan:

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