Yayınla ve Abone Ol

Yakındaki Mesajlar API'si, yakındaki cihazların küçük veri yükleri alışverişi yapmasına olanak tanıyan bir yayınlama-abonelik API'sidir. Bir cihaz mesaj yayınladığında yakındaki cihazlar bu mesajı alabilir. İyi bir performans elde etmek için mesaj boyutu oldukça küçük tutulmalıdır. Bu hizmet, fotoğraf ve video gibi daha büyük nesnelerin paylaşılması için tasarlanmamıştır.

Yakındaki cihazlar kümesi, Bluetooth ve yakın ultrasonik (duyulmayan) ses üzerinden küçük jetonların değişimiyle belirlenir. Bir cihaz, yakındaki bir cihazdan gelen jetonu algıladığında jetonu doğrulamak ve uygulamanın mevcut abonelik grubu için teslim edilecek mesaj olup olmadığını kontrol etmek üzere Yakın Mesajlar sunucusuna gönderir.

Bir uygulama, cihaz keşfi için kullanılan ortamlar grubunu ve ortamların jeton yayınlamak ve/veya jeton taramak için kullanılıp kullanılmadığını kontrol edebilir. Varsayılan olarak, yayın ve tarama tüm ortamlarda yapılır. Bir alt küme veya ortamda keşif yapmak ve yayın yapılıp yapılmayacağını ya da tarama yapılıp yapılmayacağını kontrol etmek için yayın ve abonelik oluştururken ek parametreler iletmeniz gerekir.

Bu kitaplık iOS 7 ve sonraki sürümlerde çalışır ve iOS 8 SDK ile oluşturulur.

İleti yöneticisi oluşturma

Bu kod, yayınlama ve abone olma işlemlerini yapmanızı sağlayan bir mesaj yöneticisi nesnesi oluşturur. İleti değişimi kimliği doğrulanmamış olduğundan iOS için herkese açık bir API anahtarı sağlamanız gerekir. Projenizin Google Developers Console girişini kullanarak bir proje oluşturabilirsiniz.

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Mesaj yayınlama

Bu kod snippet'i, ad içeren bir mesajın yayınlanmasını gösterir. Yayın nesnesi var olduğu sürece yayın aktiftir. Yayınlamayı durdurmak için yayın nesnesini serbest bırakın.

Objective-C

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

Swift

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

Mesajlara abone olma

Bu kod snippet'i, önceki yayın snippet'i tarafından paylaşılan tüm adlara abone olmayı gösterir. Abonelik nesneleri mevcut olduğu sürece abonelik etkindir. Aboneliği durdurmak için abonelik nesnesini serbest bırakın.

Mesaj bulan işleyici, mesaj yayınlayan yakındaki cihazlar bulunduğunda çağrılır. Bir mesaj artık gözlemlenmediğinde (cihazın menzili dışında kalması veya mesajı yayınlamayı bırakması) mesaj kaybı işleyicisi çağrılır.

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

Keşif ortamları

Varsayılan olarak, yakındaki cihazları keşfetmek için hem ses hem de Bluetooth kullanılır. Her iki ortam da yayın yapar ve tarama gerçekleştirir. Bazı durumlarda, uygulamanızın Info.plist bölümüne aşağıdaki girişleri eklemeniz gerekir:

  • Uygulamanız ses kullanarak tarama yapıyorsa NSMicrophoneUsageDescription ifadesini ekleyin. Bu ifade, mikrofonu neden kullanacağınızı açıklayan bir dizedir. Örneğin, "Mikrofon, yakındaki cihazlardan gelen anonim jetonları dinler."

  • Uygulamanız BLE kullanarak yayın yapıyorsa NSBluetoothPeripheralUsageDescription dizesini ekleyin. Bu dize, BLE'de neden reklam yayınlayacağınızı açıklar. Örneğin, "Yakındaki cihazları keşfetmek için Bluetooth üzerinden anonim bir jetonun reklamı yayınlanır."

Bazı durumlarda uygulamanızın yalnızca bir ortamı kullanması gerekebilir ve bu ortamda hem yayın yapması hem de tarama yapması gerekmeyebilir.

Örneğin, yalnızca ses yayını yapan bir set üstü kutuya bağlanmak için tasarlanmış bir uygulamanın, kutuyu bulmak için yalnızca ses taraması yapması gerekir. Aşağıdaki snippet'te, keşif için yalnızca ses taraması kullanılarak bu set üstü kutuya nasıl mesaj yayınlanacağı gösterilmektedir:

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

Hata ayıklama günlük kaydını etkinleştirme

Hata ayıklama günlüğü, Nearby Mesajları'nı uygulamanıza entegre ederken karşılaşabileceğiniz sorunları izlemek için yararlı olabilecek önemli dahili etkinlikleri konsola yazdırır. Teknik destek için bizimle iletişime geçerseniz bu günlükleri isteriz.

İleti yöneticisi oluşturmadan önce bu özelliği etkinleştirmeniz gerekir. Bu kod snippet'inde hata ayıklama günlük kaydının nasıl etkinleştirileceği gösterilmektedir:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Yakındaki cihazlar izni durumunu izleme

Cihaz bulma özelliğini etkinleştirmek için kullanıcı izni gerekir. Bu durum, Yakınlardaki cihazlar izni durumuyla gösterilir. Yayın veya abonelik oluşturmak için yapılan ilk çağrıda kullanıcıya izin iletişim kutusu gösterilir. Kullanıcı izin vermezse cihaz keşfi çalışmaz. Bu durumda, uygulamanızda kullanıcıya cihaz bulma özelliğinin devre dışı olduğunu hatırlatan bir mesaj gösterilmelidir. İzin durumu NSUserDefaults içinde saklanır.

Aşağıdaki snippet, izin durumuna abone olmayı gösterir. İzin durumu değiştiğinde izin durumu değişti işleyici çağrılır. Kullanıcı izin verene veya izni reddedene kadar ilk kez çağrılmaz. Aboneliği durdurmak için izin nesnesini serbest bırakın.

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

Uygulamanız, kullanıcının izin durumunu değiştirmesine olanak tanıyabilir. Örneğin, ayarlar sayfasında açma/kapatma düğmesi kullanılabilir.

İzin durumunu alma ve ayarlama ile ilgili bir örneği aşağıda bulabilirsiniz.

Objective-C

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

Swift

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

Yakındakiler'i etkileyen kullanıcı ayarlarını izleme

Kullanıcı mikrofon iznini veya Bluetooth iznini reddettiyse ya da Bluetooth'u kapattıysa Yakındakiler özelliği iyi çalışmaz veya hiç çalışmayabilir. Uygulamanız bu durumlarda, kullanıcının Etrafımda'nın işlemlerinin engellendiği konusunda uyarılması için bir mesaj göstermelidir. Aşağıdaki snippet, ileti yöneticisi oluşturulurken işleyiciler iletilerek bu kullanıcı ayarlarının durumunun nasıl izleneceğini gösterir:

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

Yakınlardaki cihazlar izni iletişim kutusunu geçersiz kılma

Yayınlarınıza ve aboneliklerinize ilettiğiniz parametrelere bağlı olarak iOS, Yakınlardaki'nin çalışmasına izin vermeden önce çeşitli izinler isteyebilir. Örneğin, varsayılan strateji, yakın ultrasonik sesle iletilen verileri dinler. Bu nedenle iOS, mikrofonu kullanmak için izin ister. Bu durumlarda, Yakındaki Cihazlar, kullanıcıdan neden izin vermesinin istendiğini açıklayan bir "uçuş öncesi" iletişim kutusu gösterir.

Özel bir "ön kontrol" iletişim kutusu sağlamak istiyorsanız permissionRequestHandler parametresini yayın veya abonelik parametrelerindeki özel bir bloğa ayarlayın. Özel bloğunuz, kullanıcı yanıt verdikten sonra permissionHandler bloğunu çağırmalıdır. Aşağıdaki snippet'te, bu işlemin bir yayın için nasıl yapılacağı gösterilmektedir:

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

Arka plan işlemi

Cihaz keşfi için BLE kullanan yayınlar ve abonelikler arka planda çalışabilir. Arka plan modunu kullanmaya karar verirken dikkat etmeniz gereken bazı noktalar şunlardır:

  • Arka plan işlemleri yalnızca BLE ortamını kullanmalıdır. Ses desteklenmez.
  • Arka planda BLE için ek pil maliyeti vardır. Maliyet düşüktür ancak arka plan modunu kullanmaya karar vermeden önce bunu ölçmeniz gerekir.
  • iOS, kullanıcılardan arka planda BLE üzerinden reklam yayınlamak için izin ister.

Bir yayına veya aboneliğe arka plan modunu eklemek için aşağıdaki ek adımları uygulayın:

  • Doğru şekilde yapılandırılmış bir GNSStrategy nesnesi ileterek yayınınızda veya aboneliğinizde arka plan modunu ve yalnızca BLE'yi etkinleştirin. Aşağıdaki snippet'te, bunun abonelik için nasıl yapılacağı gösterilmektedir:

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

  • Bu girişleri uygulamanızın Info.plist dosyasına ekleyin:

    • UIBackgroundModes giriş:

      • Arka planda BLE taraması için bluetooth-central. Yalnızca keşif modu taramayı içerdiğinde gereklidir. Varsayılan olarak tarama içerir.
      • Arka planda BLE reklamı için bluetooth-peripheral. Yalnızca keşif modu yayın yapmayı içerdiğinde gereklidir. Varsayılan olarak yayın yapmayı içerir.

    • NSBluetoothPeripheralUsageDescription BLE'de neden reklam yayınlayacağınızı açıklayan dize. Örneğin, "Yakındaki cihazları bulmak için Bluetooth üzerinden anonim bir jetonun reklamı yapılır." Ayrıntılar için Apple'ın belgelerine bakın.

  • Uygulamanız arka plandayken sistem tarafından herhangi bir zamanda sonlandırılabilir. Arka plan modu, kullanıcı tarafından etkinleştirilebilen veya devre dışı bırakılabilen bir ayarsa uygulamanız şunları yapmalıdır:

    • Kullanıcı arka plan modu değerini her değiştirdiğinde değeri NSUserDefaults konumuna kaydedin.
    • Başlangıçta NSUserDefaults konumundan okuyun ve arka plan modu etkinse Yakındaki yayınları ve/veya abonelikleri geri yükleyin.

Arka plan bildirimleri

Uygulamanızın, arka planda çalışırken aboneliğe mesaj geldiğinde kullanıcıyı bilgilendirmesini istiyorsanız yerel bildirimleri kullanabilirsiniz.

Bu öğeleri uygulamanıza eklemek için aşağıdaki adımları uygulayın:

  • Başlangıçta yerel bildirimlere kaydolma:

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

  • Aboneliğinizin message-found işleyicisinde yerel bildirim gönderin:

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