# الأسئلة الشائعة حول iOS SDK ### الأسئلة الشائعة حول تكامل iOS #### س: كيف يمكنني تثبيت Pushwoosh SDK في مشروع iOS الخاص بي؟ يمكنك دمج Pushwoosh SDK باستخدام Swift Package Manager أو CocoaPods. #### س: كيف أقوم بتثبيت Pushwoosh SDK باستخدام Swift Package Manager؟ في Xcode، انتقل إلى قسم **Package Dependencies** وأضف الحزمة باستخدام عنوان URL التالي: `https://github.com/Pushwoosh/Pushwoosh-XCFramework`. #### س: كيف أقوم بتثبيت Pushwoosh SDK باستخدام CocoaPods؟ افتح `Podfile` الخاص بمشروعك وأضف السطر `pod 'PushwooshXCFramework'`. ثم، قم بتشغيل الأمر `pod install` في الطرفية (terminal). #### س: ما هي الصلاحيات (capabilities) التي أحتاج إلى إضافتها إلى مشروعي لتمكين الإشعارات الفورية (Push Notifications)؟ في قسم Signing & Capabilities في إعدادات مشروعك، تحتاج إلى إضافة صلاحيات `Push Notifications` و `Background Modes`. عند إضافة `Background Modes`، تأكد من تحديد مربع `Remote notifications`. #### س: ما هي الصلاحية الإضافية المطلوبة للإشعارات الحساسة للوقت (Time Sensitive Notifications)؟ إذا كنت تنوي استخدام الإشعارات الحساسة للوقت (Time Sensitive Notifications) (iOS 15+)، فأنت بحاجة أيضًا إلى إضافة صلاحية `Time Sensitive Notifications`. #### س: أين أحتاج إلى إضافة كود تهيئة Pushwoosh؟ يجب إضافة كود التهيئة إلى كلاس `AppDelegate` الخاص بك. #### س: ما هو كود التهيئة الذي يجب أن أضيفه في AppDelegate الخاص بـ SwiftUI؟ يرجى الرجوع إلى [مثال كود Swift المقدم لدمج Pushwoosh في مشروع SwiftUI](/ar/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#appdelegate). #### س: ما هو كود التهيئة الذي يجب أن أضيفه في AppDelegate قياسي لـ Swift؟ يرجى الرجوع إلى [مثال كود Swift المقدم لدمج Pushwoosh في مشروع Swift قياسي](/ar/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#appdelegate). #### س: ما هو كود التهيئة الذي يجب أن أضيفه في AppDelegate لـ Objective-C؟ يرجى الرجوع إلى [مثال كود Objective-C المقدم لدمج Pushwoosh في مشروع Objective-C](/ar/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#appdelegate). #### س: ما هي المفاتيح التي أحتاج إلى إضافتها إلى ملف Info.plist الخاص بي؟ تحتاج إلى إضافة مفتاح `Pushwoosh_APPID` بقيمة كود التطبيق (Application Code) الخاص بك ومفتاح `PW_API_TOKEN` بقيمة رمز API الخاص بك في ملف `Info.plist` لتطبيقك. #### س: ما هو الغرض من تتبع تسليم الرسائل؟ يدعم Pushwoosh تتبع أحداث تسليم الإشعارات الفورية باستخدام Notification Service Extension. #### س: كيف أضيف Notification Service Extension إلى مشروعي؟ في Xcode، اذهب إلى **File** > **New** > **Target...**، اختر **Notification Service Extension**، واضغط **Next**. أدخل اسمًا للهدف واضغط **Finish**. عندما يُطلب منك التنشيط، اضغط **Cancel**. #### س: كيف أضيف Pushwoosh SDK إلى Notification Service Extension؟ أضف [مقتطف كود Swift أو Objective-C المقدم](/ar/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#add-pushwoosh-sdk-to-notification-service-extension) إلى ملف `.swift` أو `.m` الرئيسي لـ Notification Service Extension الخاص بك. يستخدم هذا الكود `PWNotificationExtensionManager` للتعامل مع طلب الإشعار. #### س: ما هو الغرض من App Groups؟ صلاحية App Groups مطلوبة للسماح لـ Notification Service Extension بالتواصل مع التطبيق الرئيسي. #### س: كيف أقوم بتمكين App Groups للهدف الرئيسي و Notification Service Extension؟ لكلا الهدفين، اذهب إلى **Signing & Capabilities**، أضف صلاحية **App Groups**، وأنشئ مجموعة جديدة بالضغط على زر +. تأكد من أن اسم المجموعة يبدأ بـ `group.` واستخدم نفس اسم المجموعة لكلا الهدفين. #### س: ما هي المفاتيح التي أحتاج إلى إضافتها إلى Info.plist للهدف الرئيسي لـ App Groups؟ في `Info.plist` للهدف الرئيسي، أضف مفتاح `PW_APP_GROUPS_NAME` واضبط قيمته على اسم مجموعة App Groups الخاصة بك. #### س: ما هي المفاتيح التي أحتاج إلى إضافتها إلى Info.plist لـ Notification Service Extension؟ في `Info.plist` لـ Notification Service Extension، أضف مفتاح `PW_APP_GROUPS_NAME` (مع ضبطه على اسم App Groups الخاص بك) ومفتاح `Pushwoosh_APPID` (مع ضبطه على كود التطبيق الخاص بك). #### س: كيف أتحقق من تكامل Pushwoosh؟ بعد بناء وتشغيل مشروعك، اذهب إلى لوحة تحكم Pushwoosh وأرسل إشعارًا فوريًا إلى تطبيقك. يجب أن ترى الإشعار يظهر على جهازك. #### س: ما هما الاستدعاءان الرئيسيان للتعامل مع الإشعارات الفورية في Pushwoosh SDK؟ الاستدعاءان الرئيسيان هما `onMessageReceived` و `onMessageOpened`. #### س: متى يتم استدعاء `onMessageReceived`؟ يتم استدعاء `onMessageReceived` عندما يتلقى التطبيق إشعارًا فوريًا. #### س: متى يتم استدعاء `onMessageOpened`؟ يتم استدعاء `onMessageOpened` عندما يتفاعل المستخدم مع إشعار فوري ويفتحه. #### س: كيف يمكنني الوصول إلى حمولة (payload) إشعار فوري تم استلامه أو فتحه؟ يمكن الوصول إلى حمولة كائن `PWMessage` (الذي يتم تمريره إلى استدعاءات `onMessageReceived` و `onMessageOpened`) من خلال خاصية `payload` الخاصة به. #### س: كيف يمكنني تعيين معرف مستخدم (user ID) في Pushwoosh؟ استخدم `setUserId(_:)` لكائن `Pushwoosh.sharedInstance()`، ومرر معرف المستخدم كوسيط. #### س: كيف يمكنني تعيين عنوان البريد الإلكتروني للمستخدم في Pushwoosh؟ استخدم `setEmail(_:)` لكائن `Pushwoosh.sharedInstance()`، وقدم البريد الإلكتروني للمستخدم. #### كيف يمكنني تعيين معلومات إضافية للمستخدم كعلامات (tags) في Pushwoosh؟ استخدم `setTags(_:)` لكائن `Pushwoosh.sharedInstance()`، ومرر قاموسًا حيث تكون المفاتيح هي أسماء العلامات والقيم هي قيم العلامات المقابلة. #### كيف يمكنني تتبع حدث مستخدم بسمات إضافية؟ استخدم `postEvent(_:withAttributes:)` لـ `PWInAppManager.shared()`، وقدم اسم الحدث (مثل `"login"`) وقاموسًا من السمات (مثل `"name"`، `"last_login"`). #### س: كيف يمكنني تتبع حدث شراء مستخدم بتفاصيل المنتج؟ استخدم `postEvent(_:withAttributes:)` لـ `PWInAppManager.shared()` مع اسم الحدث `"purchase"` وقاموس يحتوي على تفاصيل المنتج مثل `"product_id"`، `"product_name"`، `"price"`، و `"quantity"`. #### س: كيف أقوم بإعداد مفوض (delegate) للتعامل مع عرض الوسائط الغنية (rich media)؟ في وحدة التحكم في العرض (view controller) أو أي كلاس مناسب آخر، قم بالامتثال لبروتوكول `PWRichMediaPresentingDelegate` واضبط خاصية `delegate` لـ `PWRichMediaManager.shared()` على المثيل الممتثل الخاص بك. #### س: كيف يمكنني تكوين نمط عرض الوسائط الغنية؟ استخدم كائن `PWModalWindowConfiguration.shared()` لتكوين خصائص مثل موضع النافذة المشروطة (modal window) ورسوميات العرض والإخفاء باستخدام `configureModalWindow(with:present:dismiss:)`. #### س: ما هي المعلومات التي يمكنني الوصول إليها في دوال مفوض الوسائط الغنية؟ توفر دوال المفوض الوصول إلى كائن `PWRichMedia`، الذي يحتوي على معلومات حول محتوى الوسائط الغنية، بما في ذلك `pushPayload` الخاص به. توفر دالة `presentingDidFailForRichMedia:withError:` أيضًا كائن `Error` يصف الفشل. ### استكشاف الأخطاء وإصلاحها #### س: خطأ "ملف التزويد الخاص بك لا يحتوي على إدخال APS" إذا رأيت رسالة الخطأ "Your provisioning profile does not have APS entry."، فتأكد من أن ملف التزويد (provisioning profile) الخاص بك متوافق مع الإشعارات الفورية ويحتوي على السلسلة `aps-environment` بقيمة `production` أو `development`. أسهل طريقة للتحقق هي فتح ملف التزويد المحمول في أي محرر نصوص والبحث عن السلسلة `aps-environment`. يجب أن تكون موجودة هناك. إذا كانت موجودة، واستمر ظهور الخطأ، فهذا يعني أن XCode لا يزال يختار ملفًا "غير متوافق مع الإشعارات الفورية". يرجى التأكد من أنك تقوم بالتوقيع بالملف الصحيح - أحيانًا إذا كان لديك ملفان لنفس معرف التطبيق (App ID)، فإن XCode يخلط الأمور ويوقع بالملف القديم. الخطوات الموصى بها هي: 1. [إزالة](https://stackoverflow.com/questions/18923095/delete-provisioning-profile-from-xcode-5) جميع ملفات XCode؛ 2. إضافة الملف الجديد الوحيد؛ 3. إعادة بناء التطبيق. #### س: كيف يبدو رمز الإشعار الفوري (push token) و hwid في iOS؟ رموز الإشعارات الفورية لأجهزة iOS هي سلاسل نصية مكونة من 64 رمزًا سداسيًا عشريًا. مثال على رمز الإشعار الفوري:\ `03df25c845d460bcdad7802d2vf6fc1dfde97283bf75cc993eb6dca835ea2e2f`\ تأكد من أن رموز الإشعارات الفورية لـ iOS التي تستخدمها عند استهداف أجهزة معينة في طلبات API الخاصة بك تكون **بأحرف صغيرة**. تستخدم Pushwoosh معرف IDFV كـ HWID للجهاز. لاحظ أنه قد يتغير في حالة قيام المستخدم بإعادة تثبيت جميع التطبيقات من بائع معين. `CBAF8ED1-17FB-49A3-73BD-DC79B63AEF93` #### س: كيف يمكنني تشغيل وإيقاف اللافتة (banner) أثناء تشغيل تطبيقي؟ بشكل افتراضي، يعرض أحدث إصدار من iOS SDK الخاص بنا لافتة الإشعار عندما يكون التطبيق قيد التشغيل في المقدمة.\ يمكنك التحكم في هذا السلوك عن طريق تغيير العلامات التالية في Info.plist: العلامة `Pushwoosh_ALERT_TYPE` – نوع سلسلة نصية، القيم هي: * `BANNER` – القيمة الافتراضية، تعرض تنبيه لافتة داخل التطبيق * `ALERT` – تنبيه إشعار * `NONE` – لا تعرض الإشعارات عندما يكون التطبيق في المقدمة #### س: كيف أحصل على رمز الإشعار الفوري لجهاز iOS الخاص بي لاستخدامه في الأجهزة التجريبية (Test Devices)؟ للحصول على رمز الإشعار الفوري لجهاز iOS الخاص بك، 1. افتح Xcode => Devices & Simulators؛ 2. قم بتوصيل الجهاز التجريبي بجهاز الكمبيوتر الخاص بك؛ 3. حدد جهازك المتصل في قائمة الأجهزة على اليسار؛ 4. انقر فوق زر Open Console. قم بتشغيل التطبيق الذي تحتاج إلى رمز الإشعار الفوري له، وحدد موقع رمز الإشعار الفوري لجهازك المكون من 64 حرفًا سداسيًا عشريًا في سطر "Registered for push notifications": #### س: لماذا لا يتم مسح الشارات (badges) بعد إلغاء تثبيت تطبيقي وإعادة تثبيته في فترة قصيرة؟ هذا سلوك متوقع - تتم معالجة الشارات بواسطة iOS نفسه ويتم تخزين قيمها في تفضيلات التطبيق، والتي لا تتم إزالتها على الفور عند إلغاء تثبيت تطبيقك. تظل قيمة الشارة هناك لبعض الوقت في حالة إعادة التثبيت الفوري، مما يؤدي إلى عرض نفس الشارات بعد إعادة تثبيت التطبيق.