Publikasikan dan Berlangganan

Nearby Messages API adalah API publikasi-langganan yang memungkinkan perangkat di sekitar bertukar sejumlah kecil data. Setelah perangkat memublikasikan pesan, Anda akan perangkat tersebut dapat menerima pesan. Ukuran pesan harus dijaga cukup kecil untuk mempertahankan performa yang baik. Layanan ini tidak dimaksudkan untuk menukar objek seperti foto dan video.

Set perangkat terdekat ditentukan oleh pertukaran token kecil melalui Bluetooth dan audio yang mendekati ultrasonik (tidak terdengar). Saat perangkat mendeteksi token dari perangkat di sekitar, perangkat ini mengirimkan token ke server Nearby Messages untuk memvalidasinya dan memeriksa apakah ada pesan yang harus dikirimkan untuk sekumpulan langganan saat ini.

Aplikasi dapat mengontrol kumpulan media yang digunakan untuk penemuan perangkat, dan apakah media digunakan untuk menyiarkan token dan/atau memindai token. Secara default, penyiaran dan pemindaian dilakukan pada semua media. Yang akan dilakukan pada {i>subset<i} 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 Konsol Google Developers untuk pada proyek 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 menghentikan memublikasikan, merilis 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 langganan. Untuk berhenti berlangganan, lepaskan langganan .

Pengendali pesan yang ditemukan dipanggil saat perangkat di sekitar yang melakukan publikasi pesan ditemukan. Pengendali pesan yang hilang dipanggil jika pesan tidak diamati lagi (perangkat telah berada di luar jangkauan atau tidak lagi memublikasikan pesan ini).

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 di sekitar perangkat, dan kedua media akan menyiarkan dan memindai. Untuk kasus tertentu, Anda diperlukan untuk menambahkan entri berikut ke Info.plist aplikasi Anda:

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

  • Jika siaran aplikasi Anda 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."

Pada beberapa kasus, aplikasi Anda mungkin hanya perlu menggunakan salah satu media, dan mungkin tidak perlu melakukan kedua siaran dan pemindaian pada media itu.

Misalnya, aplikasi yang didesain untuk terhubung ke dekoder yang penyiaran pada audio hanya perlu memindai audio untuk menemukannya. Hal berikut cuplikan ini menunjukkan cara memublikasikan pesan ke dekoder tersebut dengan hanya menggunakan audio pemindaian untuk pencarian:

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 temui saat mengintegrasikan Nearby Pesan ke aplikasi Anda. Kami akan meminta catatan ini jika Anda menghubungi kami untuk 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 Nearby

Izin pengguna diperlukan untuk mengaktifkan penemuan perangkat. Hal ini ditunjukkan oleh Status izin terdekat. Saat pertama kali membuat publikasi atau berlangganan, pengguna akan melihat dialog izin. Jika pengguna tidak penemuan perangkat tidak akan berfungsi. Dalam hal ini, aplikasi Anda harus menampilkan untuk mengingatkan pengguna bahwa penemuan perangkat dinonaktifkan. Izin disimpan di NSUserDefaults.

Cuplikan berikut menunjukkan cara berlangganan status izin. Tujuan status izin yang diubah dipanggil setiap kali status berubah, dan tidak dipanggil untuk 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 Anda dapat menyediakan cara bagi pengguna untuk mengubah status izin; untuk misalnya dengan menggunakan tombol di laman 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

Memantau setelan pengguna yang memengaruhi fitur Di Sekitar

Jika pengguna menolak izin mikrofon, menolak izin Bluetooth, atau telah menonaktifkan Bluetooth. Fitur Di Sekitar juga tidak berfungsi, atau mungkin tidak berfungsi sama sekali. Dalam kasus ini, aplikasi Anda harus menampilkan pesan, yang memberi tahu pengguna bahwa operasionalnya terhambat. Cuplikan berikut menunjukkan cara melacak setelan pengguna ini dengan meneruskan pengendali saat membuat pesan manajer:

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 Berbagi Langsung

Bergantung pada parameter yang Anda teruskan ke publikasi dan langganan, iOS mungkin meminta berbagai izin sebelum mengizinkan Di Sekitar berfungsi. Sebagai Sebagai contoh, strategi default memproses data yang ditransmisikan audio, sehingga iOS akan meminta izin untuk menggunakan mikrofon. Dalam kasus ini, Di sekitar akan menampilkan "preflight" dialog yang menjelaskan mengapa pengguna diminta untuk memberikan izin.

Jika Anda ingin menyediakan "preflight" kustom dialog, setel atribut permissionRequestHandler ke blok kustom dalam publikasi atau parameter langganan. Elemen penyusun kustom Anda harus memanggil permissionHandler blokir 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 ini 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 tambahan untuk BLE latar belakang. Biayanya rendah, tetapi Anda sebaiknya Anda mengukurnya sebelum memutuskan untuk menggunakan mode latar belakang.
  • iOS akan meminta izin kepada pengguna untuk beriklan melalui BLE di latar belakang.

Untuk menambahkan mode latar belakang ke publikasi atau langganan, ikuti petunjuk langkah:

  • 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 saat mode penemuan menyertakan pemindaian; hal itu dilakukan secara {i>default<i}.
      • bluetooth-peripheral untuk iklan BLE di latar belakang. Dibutuhkan hanya jika mode penemuan mencakup penyiaran; hal itu dilakukan secara {i>default<i}.

    • String NSBluetoothPeripheralUsageDescription yang menjelaskan alasannya Anda akan beriklan di BLE. Misalnya, "Token anonim adalah 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 pengaturan yang dapat diaktifkan atau dinonaktifkan oleh pengguna, aplikasi harus melakukan hal berikut:

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

Notifikasi latar belakang

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

Ikuti langkah-langkah berikut untuk menambahkannya ke aplikasi Anda:

  • Daftar untuk menerima notifikasi lokal saat sistem 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 pesan yang ditemukan pada 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...
}