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

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

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

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

إعداد Xcode

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

1. إضافة حزمة Cast iOS SDK 4.8.6 إلى مشروعك

   في حال استخدام 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). تتوفّر حزمة Cast iOS SDK من مستودع google-cast-ios-sdk على GitHub.

لإضافة حزمة تطوير البرامج (SDK) لنظام التشغيل iOS في Cast إلى مشروعك في 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) لنظام التشغيل iOS الخاصة بـ Cast إلى مشروعك بدون استخدام أداة 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. اتّبِع عملية الإعداد اليدوي لإضافة إطار العمل إلى مشروعك. بعد ذلك، استبعِد Cast SDK بشكل مشروط من هدف Mac كما هو موضّح في مستندات Apple. يتم تجميع المكتبات الثابتة مسبقًا لبنية iOS، ما يؤدي إلى حدوث خطأ في الرابط عند الإنشاء مقابل هدف Mac.