انتشار و اشتراک

Nearby Messages API یک API انتشار-اشتراک است که به دستگاه‌های اطراف اجازه می‌دهد تا حجم‌های کوچکی از داده‌ها را مبادله کنند. هنگامی که یک دستگاه پیامی را منتشر می کند، دستگاه های اطراف می توانند پیام را دریافت کنند. اندازه پیام باید نسبتاً کوچک نگه داشته شود تا عملکرد خوب حفظ شود. این سرویس برای مبادله اشیاء بزرگتر مانند عکس و فیلم نیست.

مجموعه دستگاه‌های نزدیک با تبادل توکن‌های کوچک از طریق بلوتوث و صدای نزدیک به اولتراسونیک (نامفهوم) تعیین می‌شود. وقتی دستگاهی رمزی را از یک دستگاه نزدیک تشخیص می‌دهد، رمز را به سرور پیام‌های نزدیک می‌فرستد تا اعتبار آن را تأیید کند و بررسی کند که آیا پیام‌هایی برای ارسال برای مجموعه اشتراک‌های فعلی برنامه وجود دارد یا خیر.

یک برنامه کاربردی می‌تواند مجموعه‌ای از رسانه‌های مورد استفاده برای کشف دستگاه و اینکه آیا رسانه‌ها برای پخش توکن‌ها و/یا اسکن نشانه‌ها استفاده می‌شوند را کنترل کند. به طور پیش فرض، پخش و اسکن در تمام رسانه ها انجام می شود. برای انجام اکتشاف در یک زیرمجموعه یا رسانه و کنترل پخش یا اسکن کردن، باید پارامترهای اضافی را هنگام ایجاد انتشارات و اشتراک‌ها ارسال کنید.

این کتابخانه روی iOS 7 و بالاتر اجرا می‌شود و با iOS 8 SDK ساخته می‌شود.

ایجاد یک مدیر پیام

این کد یک شی مدیر پیام ایجاد می کند که به شما امکان انتشار و اشتراک می دهد. تبادل پیام احراز هویت نشده است، بنابراین باید یک کلید API عمومی برای iOS ارائه دهید. می‌توانید با استفاده از ورودی Google Developers Console برای پروژه خود یکی ایجاد کنید.

هدف-C 

#import <GNSMessages.h>

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

سویفت 

let messageManager = GNSMessageManager(APIKey: "API_KEY")

انتشار پیام

این قطعه کد انتشار یک پیام حاوی نام را نشان می دهد. تا زمانی که هدف انتشار وجود داشته باشد، انتشارات فعال است. برای توقف انتشار، شی انتشار را رها کنید.

هدف-C 

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

سویفت 

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

اشتراک در پیام ها

این قطعه کد اشتراک همه نام‌های اشتراک‌گذاری شده توسط قطعه انتشار قبلی را نشان می‌دهد. اشتراک تا زمانی که اشیاء اشتراک وجود دارد فعال است. برای توقف اشتراک، شیء اشتراک را رها کنید.

هنگامی که دستگاه‌های نزدیکی که پیام‌ها را منتشر می‌کنند کشف شوند، کنترل‌کننده پیام یافت شده فراخوانی می‌شود. کنترل کننده پیام از دست رفته زمانی فراخوانی می شود که پیامی دیگر مشاهده نشود (دستگاه از محدوده خارج شده یا دیگر پیام را منتشر نمی کند).

هدف-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
    }];

سویفت 

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

رسانه های کشف

به طور پیش‌فرض، از هر دو رسانه (صوتی و بلوتوث) برای کشف دستگاه‌های نزدیک استفاده می‌شود، و هر دو رسانه پخش و اسکن می‌شوند. برای موارد خاص، باید ورودی های زیر را به Info.plist برنامه خود اضافه کنید:

  • اگر برنامه شما با استفاده از صدا اسکن می‌کند، NSMicrophoneUsageDescription را اضافه کنید، که رشته‌ای است که دلیل استفاده از میکروفون را توضیح می‌دهد. به عنوان مثال، "میکروفون به نشانه های ناشناس از دستگاه های نزدیک گوش می دهد."

  • اگر برنامه شما با استفاده از BLE پخش می شود، NSBluetoothPeripheralUsageDescription را اضافه کنید، که رشته ای است که توضیح می دهد چرا در BLE تبلیغ می کنید. به عنوان مثال، "یک توکن ناشناس از طریق بلوتوث برای کشف دستگاه های نزدیک تبلیغ می شود."

در برخی موارد، برنامه شما ممکن است نیاز به استفاده از یکی از رسانه ها داشته باشد و ممکن است نیازی به پخش و اسکن در آن رسانه نداشته باشد.

به عنوان مثال، برنامه ای که برای اتصال به ستاپ باکسی طراحی شده است که روی صدا پخش می شود، فقط باید صدا را اسکن کند تا آن را پیدا کند. قطعه زیر نشان می‌دهد که چگونه می‌توان پیامی را با استفاده از اسکن صوتی برای اکتشاف در آن جعبه تنظیم، منتشر کرد:

هدف-C 

id<GNSPublication> publication = [messageManager publicationWithMessage:message
    paramsBlock:^(GNSPublicationParams *params) {
      params.strategy = [GNSStrategy strategyWithParamsBlock:^(GNSStrategyParams *params) {
        params.discoveryMediums = kGNSDiscoveryMediumsAudio;
        params.discoveryMode = kGNSDiscoveryModeScan;
      }];
    }];

سویفت 

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

فعال کردن ثبت اشکال زدایی

ثبت اشکال‌زدایی رویدادهای داخلی مهمی را در کنسول چاپ می‌کند که می‌تواند برای ردیابی مشکلاتی که ممکن است هنگام ادغام Nearby Messages در برنامه خود با آن مواجه شوید، مفید باشد. اگر برای پشتیبانی فنی با ما تماس بگیرید، این گزارش‌ها را درخواست خواهیم کرد.

قبل از ایجاد یک مدیر پیام، باید آن را فعال کنید. این قطعه کد نحوه فعال کردن گزارش اشکال زدایی را نشان می دهد:

هدف-C 

[GNSMessageManager setDebugLoggingEnabled:YES];

سویفت 

GNSMessageManager.setDebugLoggingEnabled(true)

ردیابی وضعیت مجوز Nearby

برای فعال کردن کشف دستگاه، رضایت کاربر لازم است. این با وضعیت مجوز Nearby نشان داده می شود. در اولین تماس برای ایجاد یک نشریه یا اشتراک، یک گفتگوی رضایت به کاربر ارائه می شود. اگر کاربر رضایت ندهد، کشف دستگاه کار نخواهد کرد. در این حالت، برنامه شما باید پیامی را نشان دهد تا به کاربر یادآوری کند که کشف دستگاه غیرفعال است. وضعیت مجوز در NSUserDefaults ذخیره می شود.

قطعه زیر اشتراک در وضعیت مجوز را نشان می دهد. کنترل کننده تغییر وضعیت مجوز هر زمان که وضعیت تغییر کند فراخوانی می شود و تا زمانی که کاربر اجازه نداده یا رد کرده باشد، اولین بار فراخوانی نمی شود. شی مجوز برای توقف اشتراک را آزاد کنید.

هدف-C 

GNSPermission *nearbyPermission = [[GNSPermission alloc] initWithChangedHandler:^(BOOL granted) {
  // Update the UI here
}];

سویفت 

let nearbyPermission = GNSPermission(changedHandler: { (granted: Bool) in
  // Update the UI here
})

برنامه شما می تواند راهی را برای کاربر فراهم کند تا وضعیت مجوز را تغییر دهد. به عنوان مثال، با استفاده از یک سوئیچ در صفحه تنظیمات.

در اینجا مثالی از نحوه دریافت و تنظیم وضعیت مجوز آورده شده است.

هدف-C 

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

سویفت 

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

ردیابی تنظیمات کاربر که بر Nearby تأثیر می گذارد

اگر کاربر اجازه میکروفون را رد کرده باشد، اجازه بلوتوث را رد کرده باشد، یا بلوتوث را خاموش کرده باشد، Nearby نیز کار نخواهد کرد یا ممکن است اصلا کار نکند. برنامه شما باید در این موارد پیامی را نشان دهد که به کاربر هشدار می‌دهد که عملیات Nearby مانع شده است. قطعه زیر نحوه ردیابی وضعیت این تنظیمات کاربر را با عبور از کنترلرها هنگام ایجاد مدیر پیام نشان می دهد:

هدف-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
         };
}];

سویفت 

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

لغو گفتگوی مجوز Nearby

بسته به پارامترهایی که برای انتشارات و اشتراک‌های خود ارسال می‌کنید، iOS ممکن است قبل از اجازه دادن به Nearby مجوزهای مختلفی درخواست کند. به عنوان مثال، استراتژی پیش‌فرض به داده‌های ارسال شده با صدای نزدیک به اولتراسونیک گوش می‌دهد، بنابراین iOS برای استفاده از میکروفون اجازه می‌خواهد. در این موارد، Nearby یک گفتگوی «پیش از پرواز» را نشان می‌دهد که توضیح می‌دهد چرا از کاربر اجازه درخواست می‌شود.

اگر می‌خواهید یک گفتگوی سفارشی «پیش پرواز» ارائه کنید، پارامتر permissionRequestHandler را روی یک بلوک سفارشی در پارامترهای انتشار یا اشتراک تنظیم کنید. بلوک سفارشی شما باید پس از پاسخ کاربر، بلوک permissionHandler را فراخوانی کند. قطعه زیر نحوه انجام این کار را برای یک نشریه نشان می دهد:

هدف-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.
                                 };
                               }];

سویفت 

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

عملیات پس زمینه

انتشارات و اشتراک هایی که از BLE برای کشف دستگاه استفاده می کنند می توانند در پس زمینه کار کنند. در اینجا مواردی وجود دارد که هنگام تصمیم گیری برای استفاده از حالت پس زمینه باید از آنها آگاه باشید:

  • عملیات پس‌زمینه باید فقط از محیط BLE استفاده کند. صدا پشتیبانی نمی شود
  • هزینه باتری اضافی برای BLE پس زمینه وجود دارد. هزینه کم است، اما قبل از تصمیم به استفاده از حالت پس‌زمینه، باید آن را اندازه بگیرید.
  • iOS از کاربر اجازه می‌خواهد تا از طریق BLE در پس‌زمینه تبلیغ کند.

برای افزودن حالت پس‌زمینه به یک نشریه یا اشتراک، این مراحل اضافی را دنبال کنید:

  • حالت پس‌زمینه و فقط BLE را در انتشارات یا اشتراک خود با ارسال یک شیء GNSStrategy که به درستی پیکربندی شده است، فعال کنید. قطعه زیر نحوه انجام این کار را برای اشتراک نشان می دهد:

    هدف-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;
      }];
    }];

    سویفت 

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

  • این ورودی ها را به Info.plist برنامه خود اضافه کنید:

    • ورودی های UIBackgroundModes :

      • bluetooth-central برای اسکن BLE در پس زمینه. فقط زمانی مورد نیاز است که حالت کشف شامل اسکن باشد. به صورت پیش فرض انجام می دهد.
      • bluetooth-peripheral برای تبلیغات BLE در پس زمینه. فقط زمانی مورد نیاز است که حالت کشف شامل پخش باشد. به صورت پیش فرض انجام می دهد.

    • رشته NSBluetoothPeripheralUsageDescription توضیح می دهد که چرا در BLE تبلیغ می کنید. به عنوان مثال، "یک توکن ناشناس از طریق بلوتوث برای کشف دستگاه های نزدیک تبلیغ می شود." برای جزئیات بیشتر به مستندات اپل مراجعه کنید.

  • برنامه شما می تواند در هر زمانی توسط سیستم در حالی که در پس زمینه هستید از بین برود. اگر حالت پس‌زمینه تنظیمی است که کاربر می‌تواند آن را فعال یا غیرفعال کند، برنامه شما باید کارهای زیر را انجام دهد:

    • هر زمان که کاربر آن را تغییر داد، مقدار حالت پس‌زمینه را در NSUserDefaults ذخیره کنید.
    • هنگام راه‌اندازی، آن را از NSUserDefaults بخوانید و اگر حالت پس‌زمینه فعال است، انتشارات و/یا اشتراک‌های Nearby را بازیابی کنید.

اعلان های پس زمینه

اگر می‌خواهید برنامه شما هنگام دریافت پیام در پس‌زمینه، کاربر را مطلع کند، می‌توانید از اعلان‌های محلی استفاده کنید.

این مراحل را دنبال کنید تا آنها را به برنامه خود اضافه کنید:

  • ثبت نام برای اطلاعیه های محلی هنگام راه اندازی:

    هدف-C 

    if ([UIApplication instancesRespondToSelector:@selector(registerUserNotificationSettings:)]) {
  [[UIApplication sharedApplication] registerUserNotificationSettings:
      [UIUserNotificationSettings settingsForTypes:
          UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound
                                        categories:nil]];
}

    سویفت 

    UIApplication.shared.registerUserNotificationSettings(
    UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil))

  • یک اعلان محلی در کنترل کننده پیام یافت شده اشتراک خود ارسال کنید:

    هدف-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...
  };

    سویفت 

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