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

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

يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات Google Cast iOS للحصول على أوصاف لجميع الفئات والطرق.

ملاحظة: تتوفّر الآن إصدارات جديدة من حِزم تطوير البرامج (SDK) لـ Cast على أجهزة iOS التي تستخدم XCFrameworks، والتي تتيح التطوير على أجهزة كمبيوتر Apple Silicon.

إعداد Xcode

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

1. إضافة الإصدار 4.8.6 من حزمة تطوير البرامج (SDK) لتطبيق Cast على أجهزة iOS إلى مشروعك

   في حال استخدام Swift Package Manager، يجب تحديث حزمة google-cast-ios-sdk إلى الإصدار 4.8.6.

   بخلاف ذلك، اسحب حزمة SDK يدويًا.

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

   يُرجى تحديد NSBonjourServices في Info.plist للسماح بنجاح عملية البحث عن الأجهزة على الشبكة المحلية.

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

   ‫appID هو receiverID، وهو رقم التعريف نفسه المحدّد في GCKDiscoveryCriteria.

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

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

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

   ننصحك بشدة بتخصيص الرسالة التي تظهر في طلب "الشبكة المحلية" من خلال إضافة سلسلة أذونات خاصة بالتطبيق في ملف Info.plist لتطبيقك لـ NSLocalNetworkUsageDescription، مثل وصف ميزة "اكتشاف Cast" وخدمات الاكتشاف الأخرى، مثل 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.6 في أقرب وقت ممكن.

إعداد Swift Package Manager

الطريقة المقترَحة لدمج Google Cast هي استخدام Swift Package Manager (SPM). تتوفّر حزمة تطوير البرامج (SDK) لتطبيق Cast على أجهزة iOS من مستودع GitHub‏ google-cast-ios-sdk.

لإضافة حزمة تطوير البرامج (SDK) لتطبيق Cast على iOS إلى مشروعك في Xcode، اتّبِع الخطوات التالية:

1. في Xcode، انقر على ملف (File) > إضافة حِزم… (Add Packages…‎).
2. أدخِل عنوان URL الخاص بالمستودع: https://github.com/googlecast/google-cast-ios-sdk.
3. اختَر قواعد تحديد الإصدارات. على سبيل المثال، اختَر حتى الإصدار الرئيسي التالي مع الحد الأدنى للإصدار 4.8.6 لتلقّي التحديثات المتوافقة بدون تغييرات قد تؤدي إلى عطل غير متوقّعة.
4. انقر على إضافة حزمة.
5. اختَر منتج GoogleCastDynamic أو GoogleCastStatic، وأضِفه إلى هدف تطبيقك.

تحذير: أضِف منتجًا واحدًا فقط من منتجات GoogleCastDynamic أو GoogleCastStatic إلى هدفك. لا تضِف كلا الإصدارين من حزمة SDK إلى التطبيق نفسه.

اختيار صيغة إطار عمل

توفّر حزمة Cast iOS SDK منتجَين:

• ‫GoogleCastDynamic: إطار العمل الديناميكي وتتضمّن جميع موارد مواد العرض التي تتطلّبها مكوّنات واجهة مستخدم Cast، ولا تتطلّب أي علامات إضافية لبرنامج الربط. يجب أن تستخدم التطبيقات المتوافقة مع Mac Catalyst إطار العمل الديناميكي. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد Mac Catalyst.
• GoogleCastStatic: إطار العمل الثابت ويتطلّب ذلك اتّباع خطوات الإعداد الإضافية الموضّحة في إعداد إطار العمل الثابت.

إعداد إطار العمل الثابت

لا يمكن أن تتضمّن أُطر العمل الثابتة حِزم موارد. نتيجةً لذلك، لا يمكن لـ Swift Package Manager تجميع موارد مواد العرض المطلوبة من خلال مكوّنات واجهة مستخدم Cast (مثل صور واجهة المستخدم ولوحات العمل وملفات الترجمة) تلقائيًا مع منتج GoogleCastStatic. إذا أضفت GoogleCastStatic إلى هدفك، يُرجى إكمال الخطوات التالية:

1. في مشروع Xcode، أضِف العلامات -ObjC -lc++ إلى إعدادات الإصدار > علامات الربط الأخرى.
2. إذا كان تطبيقك يستخدم مكوّنات واجهة مستخدم Cast، أضِف حِزم مواد العرض يدويًا إلى مشروعك:
   1. نزِّل المكتبة الثابتة من عمليات التنزيل. تأكَّد من أنّ إصدار المكتبة الثابتة يتطابق مع إصدار الحزمة التي أضفتها.
   2. ابحث عن مجلد Resources في الدليل الذي تم فك ضغطه واسحب جميع ملفات .bundle إلى مشروع Xcode. ضَع علامة في المربّع "نسخ كل العناصر إذا لزم الأمر"، وأضِفها إلى جميع الأهداف.

ملاحظة: عند تحديث حزمة google-cast-ios-sdk إلى إصدار جديد، يجب استبدال حِزم مواد العرض في مشروعك بالحِزم من المكتبة الثابتة للإصدار نفسه.

إعداد CocoaPods

تحذير: تم إيقاف CocoaPods نهائيًا. الإصدار 4.8.6 هو آخر تحديث تم نشره على CocoaPods. ستتوفّر التحديثات اللاحقة باستخدام Swift Package Manager، وستظل متاحة من خلال التنزيل المباشر.

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

التعليمات التالية مخصّصة لإضافة حزمة تطوير البرامج (SDK) لتطبيقات Cast على iOS إلى مشروعك بدون استخدام Swift Package Manager:

نقطة أساسية: بدءًا من الإصدار 4.8.4، إذا كنت تستخدم مكتبة أخرى تعتمد على Protobuf (مثل Firebase)، سيؤدي استخدام المكتبة الثابتة إلى زيادة حجم التطبيق النهائي.

ننصحك باستخدام المكتبة الثابتة لتجنُّب المشاكل المحتملة المتعلّقة بتوافق الإصدارات مع Protobuf. ومع ذلك، إذا كان اختلاف الحجم يمثّل مشكلة في حالتك، يمكنك تنزيل المكتبة الديناميكية.

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

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

مكتبات الإصدار 4.8.6 من حزمة تطوير البرامج (SDK) لتطبيق الإرسال على أجهزة iOS:

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

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

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

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

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

1. أزِل الإصدار الحالي من GoogleCastSDK إذا كان متوفّرًا.
2. أضِف مكتبة Protobuf الإصدار 3.13 أو إصدارًا أحدث، باتّباع التعليمات الواردة في مستودع Protobuf GitHub.

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

1. في مشروع Xcode، أضِف العلامات -ObjC -lc++ إلى إعدادات الإصدار > علامات الربط الأخرى.
2. ابحث عن مجلد "الموارد" (Resources) في الدليل الذي تم فك ضغطه واسحب جميع ملفات .bundle إلى مشروعك بجانب GoogleCast.xcframework الذي أضفته سابقًا. ضَع علامة في المربّع "نسخ كل العناصر إذا لزم الأمر"، وأضِفها إلى كل الأهداف.

إعداد Mac Catalyst

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