النشر والاشتراك

واجهة برمجة تطبيقات "الرسائل القريبة" هي واجهة برمجة تطبيقات تتيح للمستخدمين الاشتراك في القناة وتتيح استخدام الأجهزة المجاورة لتبادل الحمولات الصغيرة من البيانات. بعد نشر أحد الأجهزة لرسالة، يتم استخدام الأجهزة المجاورة الأجهزة أن تتلقى الرسالة. يجب إبقاء حجم الرسالة صغيرًا إلى حد ما والحفاظ على الأداء الجيد. ولا تهدف هذه الخدمة إلى تبادل عناصر مثل الصور والفيديوهات.

يتم تحديد مجموعة الأجهزة القريبة من خلال تبادُل الرموز المميزة الصغيرة الصوت عبر البلوتوث والموجات فوق الصوتية شبه الصوتية (غير المسموعة) عندما يرصد جهاز رمزًا مميزًا من جهاز مجاور، فإنه يرسل الرمز المميز إلى خادم تطبيق "الرسائل القريبة" والتحقق من وجود أي رسائل لتسليمها إلى المجموعة الحالية من الاشتراكات

يمكن لأحد التطبيقات التحكم في مجموعة الوسائط المستخدمة لاكتشاف الأجهزة ما إذا كانت الوسائط تُستخدم لبث الرموز المميزة و/أو البحث عن رموز مميزة. يتم البث والمسح الضوئي افتراضيًا على جميع الوسائط. للقيام بذلك، والاكتشاف على مجموعة فرعية أو وسائط، والتحكم في البث أو المسح، يجب تمرير معلَمات إضافية عند إنشاء جهات نشر الاشتراكات.

تعمل هذه المكتبة على iOS 7 والإصدارات الأحدث، وهي تستند إلى iOS 8 SDK.

إنشاء مدير رسائل

ينشئ هذا الرمز كائن مدير الرسائل، ما يتيح لك نشر الاشتراك. لم تتم مصادقة تبادل الرسائل، لذا يجب تقديم مفتاح واجهة برمجة تطبيقات عام لنظام التشغيل iOS. يمكنك إنشاء حساب باستخدام إدخال Google Developers Console لمشروعك.

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

نشر رسالة

يوضح مقتطف الرمز هذا نشر رسالة تحتوي على اسم. جهة النشر نشطة ما دام عنصر جهة النشر متوفرًا. لإيقاف النشر أو تحرير كائن جهة النشر

Objective-C

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

Swift

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

الاشتراك في الرسائل

يوضح مقتطف الرمز هذا الاشتراك في جميع الأسماء التي تتم مشاركتها من قِبل مقتطف جهة النشر السابق ويكون الاشتراك نشطًا طالما هناك عناصر اشتراك لإيقاف الاشتراك، يجب إلغاء الاشتراك .

يتم استدعاء معالج العثور على الرسائل عند نشر الأجهزة المجاورة اكتشاف الرسائل. يتم استدعاء معالج فقدان الرسالة عندما تكون الرسالة غير متوفرة تمت ملاحظته (الجهاز خارج النطاق أو لم يعد ينشر ).

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

وسائط الاستكشاف

سيتم بشكل تلقائي استخدام الوسيطين (الصوت والبلوتوث) لاكتشاف الأماكن القريبة الأجهزة، وستبث كلتا الوسيطتين وتفحصهما. في بعض الحالات، مطلوبة لإضافة الإدخالات التالية إلى Info.plist في تطبيقك:

  • إذا كان تطبيقك يفحص المحتوى باستخدام الصوت، أضِف "NSMicrophoneUsageDescription"، وهي سلسلة تصف سبب استخدامك للميكروفون. على سبيل المثال، "في يرصد الميكروفون الرموز المميزة المجهولة المصدر من الأجهزة المجاورة".

  • إذا كان تطبيقك يبثّ باستخدام تقنية البلوتوث منخفض الطاقة، أضِف NSBluetoothPeripheralUsageDescription، وهي سلسلة تصف سبب الذين يعلنون عن استخدام BLE. على سبيل المثال، "يتم الإعلان عن رمز مميز مجهول الهوية عبر البلوتوث لاكتشاف الأجهزة المجاورة".

وفي بعض الحالات، قد يحتاج تطبيقك إلى استخدام وسيط واحد فقط، قد لا يحتاجون إلى البث والمسح الضوئي معًا على ذلك الوسيط.

فعلى سبيل المثال، يمكن استخدام تطبيق مصمم للاتصال بجهاز فك ترميز البث الصوتي فقط يحتاج إلى مسح ضوئي على الصوت لاكتشافه. ما يلي: يعرض المقتطف كيفية نشر رسالة إلى جهاز فك ترميز المحتوى التلفزيوني باستخدام الصوت فقط البحث عن استكشاف:

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

تفعيل تسجيل تصحيح الأخطاء

يطبع تسجيل تصحيح الأخطاء أحداثًا داخلية مهمة إلى وحدة التحكم التي يمكن هذه الميزة مفيدة لتعقب المشكلات التي قد تواجهها عند دمج "الأجهزة المجاورة" إرسال الرسائل إلى تطبيقك سنطلب هذه السجلات في حال التواصل معنا والدعم الفني

ويجب تفعيلها قبل إنشاء مدير الرسائل. يعرض مقتطف الرمز هذا كيفية تفعيل تسجيل تصحيح الأخطاء:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

تتبُّع حالة إذن "المشاركة عن قرب"

يجب الحصول على موافقة المستخدم لتفعيل ميزة اكتشاف الأجهزة. ويشار إلى ذلك من خلال حالة إذن الأجهزة المجاورة عند إجراء المكالمة الأولى لإنشاء جهة نشر اشتراكك، سيظهر للمستخدم مربّع إفادة الموافقة. إذا لم يكن المستخدم لن تعمل ميزة اكتشاف الأجهزة. في هذه الحالة، من المفترض أن يعرض تطبيقك لتذكير المستخدم بإيقاف اكتشاف الأجهزة. الإذن سيتم تخزين الحالة في NSUserDefaults.

يوضح المقتطف التالي الاشتراك في حالة الإذن. تشير رسالة الأشكال البيانية يتم استدعاء معالج تغيير حالة الإذن كلما تغيرت الحالة، لم يتم استدعاؤها في المرة الأولى إلى أن يمنح المستخدم الإذن أو يرفضه. حرر كائن الإذن لإيقاف الاشتراك.

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

يمكن أن يوفّر تطبيقك طريقة للمستخدم لتغيير حالة الإذن. حيث مثلاً، باستخدام مفتاح تبديل في صفحة الإعدادات.

في ما يلي مثال على كيفية الحصول على حالة الإذن وضبطها.

Objective-C

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

Swift

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

تتبع إعدادات المستخدم التي تؤثر في الأجهزة المجاورة

إذا رفض المستخدم إذن استخدام الميكروفون، أو رفض إذن الوصول إلى البلوتوث، أو أوقف البلوتوث، فلن تعمل ميزة الأجهزة المجاورة أيضًا، أو قد لا تعمل على الإطلاق. ومن المفترض أن يعرض تطبيقك رسالة في هذه الحالات لتنبيه المستخدم بأنّ أجهزة تعطيل العمليات. يوضح المقتطف التالي كيفية تتبع حالة إعدادات المستخدم هذه من خلال تمرير المعالِجات عند إنشاء الرسالة المدير:

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

إلغاء مربع حوار إذن الأجهزة المجاورة

بناءً على المَعلمات التي تدخِلها في جهات النشر والاشتراكات، يمكنك قد يطلب نظام iOS الحصول على أذونات مختلفة قبل السماح لميزة "الأجهزة المجاورة" بالعمل. بالنسبة إذًا، تعتمد الإستراتيجية الافتراضية على البيانات المنقولة عبر موجات فوق سمعية شبه صوتية الصوت، لذلك سيطلب iOS الإذن لاستخدام الميكروفون. في هذه الحالات، ستعرض ميزة "المشاركة عن قرب" "طلب أوّلي" مربع حوار يشرح سبب سؤال المستخدم لمنح الإذن.

إذا كنت ترغب في تقديم "طلب أوّلي" مخصص تعيين مَعلمة permissionRequestHandler إلى مجموعة حظر مخصَّصة في جهة النشر أو مَعلمات الاشتراك يجب أن تستدعي الوحدة المخصّصة permissionHandler. الحظر بعد رد المستخدم. يوضّح المقتطف التالي كيفية إجراء ذلك. لجهة النشر

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

التشغيل في الخلفية

يمكن أن تعمل جهات النشر والاشتراكات التي تستخدم تقنية BLE لاكتشاف الأجهزة في نطاق الخلفية. إليك بعض النقاط التي يجب أن تكون على دراية بها عند اتّخاذ قرار استخدام وضع الخلفية:

  • يجب أن تستخدم العمليات التي تتم في الخلفية وسيط BLE فقط، الصوت غير متاح.
  • هناك تكلفة إضافية للبطارية لتشغيل البلوتوث في الخلفية. التكلفة منخفضة، لكنك يجب قياسه قبل اتخاذ قرار باستخدام وضع الخلفية.
  • سيطلب iOS من المستخدم إذنًا للإعلان من خلال تقنية BLE في الخلفية.

لإضافة وضع الخلفية إلى جهة نشر أو اشتراك، يُرجى اتّباع الخطوات التالية: الخطوات:

  • يجب تفعيل "وضع الخلفية" وBLE فقط في جهة النشر أو الاشتراك من خلال تمرير عنصر GNSStrategy تم إعداده بشكل صحيح. المقتطف التالي كيفية إجراء ذلك لأحد الاشتراكات:

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

  • إضافة هذه الإدخالات إلى Info.plist في تطبيقك:

    • إدخالان (UIBackgroundModes):

      • bluetooth-central لإجراء مسح ضوئي منخفض الطاقة (BLE) في الخلفية. المطلوب فقط عندما يتضمّن وضع الاكتشاف عملية فحص وهو يفعل ذلك افتراضيًا.
      • bluetooth-peripheral لإعلانات BLE في الخلفية مطلوب إذا كان وضع "الاكتشاف" يتضمّن خدمة البث فقط وهو يفعل ذلك افتراضيًا.

    • سلسلة NSBluetoothPeripheralUsageDescription تصف السبب التي ستُعلن عنها على BLE. على سبيل المثال، "الرمز المميز المجهول هو الإعلان عنه عبر البلوتوث لاكتشاف الأجهزة المجاورة". عرض مستندات Apple لمزيد من التفاصيل.

  • يستطيع النظام إيقاف تطبيقك في أي وقت أثناء تشغيله في الخلفية. في حال حذف وضع الخلفية هو إعداد يمكن للمستخدم تفعيله أو إيقافه، على النحو التالي:

    • حفظ قيمة وضع الخلفية في NSUserDefaults كلما استخدم المستخدم تغييرها.
    • عند بدء التشغيل، تتم قراءته من NSUserDefaults واستعادة ميزة "الأجهزة المجاورة". جهات النشر و/أو الاشتراكات في حال تفعيل وضع الخلفية

الإشعارات التي يتم إجراؤها في الخلفية

إذا أردت أن يرسل تطبيقك إشعارًا إلى المستخدم عندما يتلقّى الاشتراك رسالة أثناء تشغيل الخلفية، يمكنك استخدام الإشعارات المحلية

يُرجى اتّباع الخطوات التالية لإضافتها إلى تطبيقك:

  • التسجيل في الإشعارات المحلية عند بدء التشغيل:

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

  • أرسل إشعارًا محليًا في معالج الاشتراك الذي تم العثور عليه:

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