إعداد التطوير باستخدام إطار عمل تطبيق Cast (CAF) لنظام التشغيل iOS

يتوافق إطار عمل Cast مع الإصدار 14 من نظام التشغيل iOS والإصدارات الأحدث، وهو متوفّر في كلٍّ من الإطارات الثابتة والديناميكية.

اطّلِع على مرجع Google Cast iOS API للحصول على أوصاف لجميع الفئات والطُرق.

ملاحظة: تتوفّر الآن إصدارات جديدة من حزمة XCFrameworks لنظام التشغيل iOS، وهي تتيح التطوير على أجهزة Apple Silicon.

إعداد Xcode

تحذير: سيؤدي ضبط العلامة Apple Clang - Code Generation Optimization Level على -Ofast لـ "أسرع التحسينات وأكثرها فاعلية" إلى تعطُّل التطبيقات التي تستخدم حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من Cast بسبب عدم التوافق مع التحسينات. يتيح حِزم تطوير البرامج (SDK) استخدام القيمة التلقائية -Os لإعداد "أسرع وأصغر حجمًا".

الإصدار 14 من نظام التشغيل iOS

تحذير بشأن الإصدار 14 من نظام التشغيل iOS: أدّت التغييرات في الإصدار 14 من نظام التشغيل iOS إلى تغيير أذونات الوصول إلى الشبكة المحلية في حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من Google Cast، وذلك بطرق مختلفة. يُرجى الاطّلاع على مستند التغييرات في نظام التشغيل iOS 14 لمعرفة مدى تأثُّر تطبيقك.

1. إضافة حزمة تطوير البرامج (SDK) لنظام التشغيل iOS 4.8.3 من Cast إلى مشروعك

   في حال استخدام CocoaPods، استخدِم pod update لإضافة حزمة SDK 4.8.3 إلى مشروعك.

   بخلاف ذلك، استخدِم حزمة تطوير البرامج (SDK) يدويًا.

   ملاحظة: إذا أنشأت أداة اختيار أجهزة مخصّصة في تطبيقك، ستحتاج إلى استدعاء طريقة startDiscovery بشكل صريح في فئة GCKDiscoveryManager لبدء اكتشاف الأجهزة. تم إيقاف عملية المسح التلقائي بشكل تلقائي اعتبارًا من الإصدار 4.5.0 من حزمة تطوير البرامج (SDK) لتطبيقات البث.
2. إضافة NSBonjourServices إلى Info.plist

   حدِّد NSBonjourServices في Info.plist لسماح بنجاح عملية اكتشاف الشبكة المحلية على نظام التشغيل iOS 14.

   ستحتاج إلى إضافة كل من _googlecast._tcp و _<your-app-id>._googlecast._tcp كخدمتَين لكي تعمل ميزة اكتشاف الأجهزة بشكلٍ سليم.

   رقم تعريف التطبيق هو رقم تعريف المستلِم، وهو رقم التعريف نفسه المحدَّد في GCKDiscoveryCriteria.

   عدِّل تعريف NSBonjourServices في المثال التالي واستبدِل "ABCD1234" بمعرّف تطبيقك.

   <key>NSBonjourServices</key>
   <array>
     <string>_googlecast._tcp</string>
     <string>_ABCD1234._googlecast._tcp</string>
   </array>

3. إضافة NSLocalNetworkUsageDescription إلى Info.plist

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

   <key>NSLocalNetworkUsageDescription</key>
   <string>${PRODUCT_NAME} uses the local network to discover Cast-enabled devices on your WiFi
   network.</string>

   ستظهر هذه الرسالة كجزء من مربّع حوار "الوصول إلى الشبكة المحلية" في نظام التشغيل iOS كما هو موضح في التصميم.

   
4. إعادة إصدار تطبيقك على Apple App Store

   ننصحك أيضًا بإعادة إصدار تطبيقك باستخدام الإصدار 4.8.3 في أقرب وقت ممكن.

الإصدار 13 من نظام التشغيل iOS

تحذير بشأن نظام التشغيل iOS 13: أدّت تغييرات أذونات Apple في نظام التشغيل iOS 13 وXcode 11 إلى التأثير في حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من Google Cast بعدة طرق. يُرجى الاطّلاع على مستند التغييرات في نظام التشغيل iOS 13 لمعرفة مدى تأثُّر تطبيقك.

الإصدار 12 من نظام التشغيل iOS

تحذير بشأن الإصدار 12 من نظام التشغيل iOS: في حال تطوير التطبيقات باستخدام Xcode 10، يجب تفعيل ميزة "الوصول إلى معلومات Wi-Fi" لأجل التعرّف على أجهزة البث والاتصال بها.

تأكَّد من ضبط مفتاح التبديل الوصول إلى معلومات شبكة Wi-Fi في قسم الإمكانات للهدف على "تفعيل".

بالإضافة إلى ذلك، يجب أن يتيح ملف الإعداد إمكانية الوصول إلى WiFi المعلومات. ويمكن إضافة هذا المحتوى في بوابة المطوّرين في Apple.

إعداد CocoaPods

الطريقة المُقترَحة لدمج Google Cast هي استخدام CocoaPods. للدمج، استخدِم google-cast-sdk CocoaPods.

للبدء، اتّبِع دليل البدء.

بعد إعداد CocoaPods، اتّبِع دليل استخدام CocoaPods لإنشاء Podfile وتجهيز مشروعك للاستخدام مع Google Cast SDK.

في ما يلي مثال على كيفية إضافة google-cast-sdk CocoaPod إلى Podfile:

use_frameworks!

platform :ios, '14.0'

def target_pods
  pod 'google-cast-sdk'
end

target 'CastVideos-objc' do
  target_pods
end
target 'CastVideos-swift' do
  target_pods
end

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

في هذا المقتطف، يُسمح بالإصدار 4.8.3 والإصدارات حتى الإصدار الرئيسي التالي (major.minor.patch):

pod 'google-cast-sdk', '~> 4.8.3'

على سبيل المثال، سيتضمّن الإصدار "‎~> 1.6.7" جميع الإصدارات من 1.6.7 إلى الإصدار 2.0.0، ولكن ليس بما في ذلك الإصدار 2.0.0.

الإعداد اليدوي

تهدف التعليمات التالية إلى إضافة حزمة تطوير البرامج (SDK) لتطبيق Cast على نظام التشغيل iOS إلى مشروعك بدون استخدام CocoaPods:

ملاحظة مهمة: بدءًا من الإصدار 4.3.1، يستخدم CocoaPods المكتبات الثابتة لتجنُّب التحذيرات بشأن الرموز المكرّرة الناتجة عن ملف برمجي مشترَك يعتمد على مكتبة Protobuf عند استخدام حِزم SDK لكلّ من Firebase وCast معًا. على الرغم من أنّ هذا التغيير سيؤدي إلى زيادة حجم التنزيل، لن يزداد حجم التطبيق النهائي.

إذا كان الفرق في الحجم يشكّل مصدر قلق في حالتك، نزِّل المكتبة الديناميكية للحصول على حجم مشابه للإصدارات التي تسبق 4.3.1 من مكتبة CocoaPods.

عمليات التنزيل

بعد تنزيل المكتبة المناسبة أدناه، اتّبِع خطوات الإعداد لإضافة إطار العمل إلى مشروعك.

مكتبات حزمة تطوير البرامج (SDK) لنظام التشغيل iOS Sender 4.8.3:

ثابتة ديناميكية

خطوات الإعداد

لتثبيت المكتبة:

1. نزِّل حزمة تطوير البرامج (SDK) المناسبة لمشروعك واحرص على استخراجها.
2. إعداد مكتبة GoogleCastSDK الديناميكية:
3. اسحب .xcframework غير المضغوطة إلى مشروعك الرئيسي في مخطِّط مشاريع Xcode (وليس إلى مشروع Pods إذا كان لديك مشروع). ضَع علامة في المربّع "نسخ كل العناصر إذا لزم الأمر" وأضِفها إلى جميع الاستهدافات.
4. في ملف Xcode المستهدف، ضمن علامة التبويب General، اختَر Embed and Sign لـ GoogleCast.xcframework.

إذا كنت بصدد إعداد المكتبة الثابتة، اتّبِع الخطوات التالية بالإضافة إلى الخطوات السابقة:

1. إعداد مكتبة Protobuf باستخدام الإصدار v3.13 كحد أدنى
1. إذا كان مشروعك يستخدم CocoaPods:
1. افتح Podfile وأزِل google-cast-sdk إذا كان متوفّرًا:

   pod 'google-cast-sdk'

2. أضِف مكتبة Protobuf إذا لم تكن متوفّرة:

   pod 'Protobuf', '3.13'

3. شغِّل pod install في المجلد الجذر لمشروعك.
2. إذا كان مشروعك لا يستخدم CocoaPods:
1. أزِل الإصدار الحالي من GoogleCastSDK إذا كان متوفّرًا.
2. أضِف الإصدار 3.13 من مكتبة Protobuf أو إصدارًا أحدث، باتّباع التعليمات الواردة في مستودع GitHub الخاص بمكتبة Protobuf.
2. في مشروع Xcode، أضِف العلامات -ObjC -lc++ إلى إعدادات الإنشاء > علامات الربط الأخرى.
3. ابحث عن مجلد "الموارد" في الدليل الذي تم فك ضغطه، ثم اسحب GoogleCastCoreResources.bundle وGoogleCastUIResources.bundle وMaterialDialogs.bundle إلى مشروعك بجانب GoogleCast.xcframework الذي أضفته سابقًا. ضَع علامة في المربّع بجانب "نسخ كل العناصر إذا لزم الأمر" وأضِفها إلى كل الاستهدافات.

إعداد Mac Catalyst

بالنسبة إلى التطبيقات المتوافقة مع Mac Catalyst، استخدِم المكتبة الديناميكية لحزمة تطوير البرامج (SDK) لتطبيق Cast. اتّبِع عملية الإعداد اليدوي لإضافة الإطار إلى مشروعك. بعد ذلك، استبعِد حزمة تطوير البرامج (SDK) لتطبيق Cast بشكل مشروط من ملف ملف برمجة التطبيقات المخصّص لأجهزة Mac، كما هو موضّح في مستندات Apple. يتم تجميع المكتبات الثابتة مسبقًا لبنية iOS، ما يؤدي إلى خطأ في الرابط عند الإنشاء لهدف Mac.