الوسائط الغنية المشروطة لـ tvOS

بدءًا من إصدار Pushwoosh SDK 6.11.0، لديك القدرة على إرسال الوسائط الغنية المشروطة (Modal Rich Media) إلى أجهزة tvOS (Apple TV).

توفر الوسائط الغنية المشروطة لـ tvOS عرض محتوى تفاعلي قائم على HTML مُحسَّن للتنقل باستخدام جهاز التحكم عن بعد لـ Apple TV. يمكن تخصيص الوسائط الغنية بمواضع ورسوم متحركة مختلفة ودعم للتنقل بالتركيز.

تنبيه

إشعارات الدفع القياسية غير مدعومة على tvOS. لا يعرض Apple TV لافتات أو تنبيهات إشعارات الدفع التقليدية. يمكن فقط عرض محتوى الوسائط الغنية الذي يتم تسليمه من خلال إشعارات الدفع الصامتة باستخدام وحدة PushwooshTVOS.

لمزيد من المعلومات حول صفحات الوسائط الغنية، يرجى الرجوع إلى دليلنا.

التثبيت

وحدة PushwooshTVOS اختيارية ويمكن دمجها في مشروع tvOS الخاص بك باستخدام Swift Package Manager أو CocoaPods.

Swift Package Manager

أضف حزمة Pushwoosh إلى مشروع tvOS الخاص بك:

1. في Xcode، حدد File ← Add Package Dependencies…
2. أدخل عنوان URL للمستودع: https://github.com/Pushwoosh/Pushwoosh-XCFramework
3. حدد أحدث إصدار
4. أضف الأطر التالية إلى هدف tvOS الخاص بك:
   • PushwooshFramework
   • PushwooshCore
   • PushwooshBridge
   • PushwooshLiveActivities
   • PushwooshTVOS

CocoaPods

أضف إلى Podfile الخاص بك:

target 'YourTvOSApp' do
  platform :tvos, '13.0'

  pod 'PushwooshXCFramework'
  pod 'PushwooshXCFramework/PushwooshTVOS'
end

ثم قم بتشغيل:

pod install

التكامل الأساسي

1. تكوين Pushwoosh في AppDelegate الخاص بك

استورد الوحدات المطلوبة وقم بتكوين Pushwoosh باستخدام رمز التطبيق الخاص بك:

import UIKit
import PushwooshTVOS
import PushwooshFramework

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Configure Pushwoosh with your app code
        Pushwoosh.TVoS.setAppCode("XXXXX-XXXXX")

        // Register for push notifications
        Pushwoosh.TVoS.registerForTvPushNotifications()

        return true
    }
}

2. التعامل مع تسجيل رمز الجهاز

نفذ معالج رمز الجهاز لتسجيل الجهاز مع Pushwoosh:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Pushwoosh.TVoS.registerForTvPushNotifications(withToken: deviceToken) { error in
        if let error = error {
            print("Failed to register: \(error)")
        } else {
            print("Successfully registered for push notifications")
        }
    }
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    Pushwoosh.TVoS.handleTvPushRegistrationFailure(error)
}

3. التعامل مع إشعارات الدفع الواردة

عالج إشعارات الدفع الواردة التي تحتوي على محتوى وسائط غنية:

func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {

    // Handle push notification and display rich media if present
    if Pushwoosh.TVoS.handleTVOSPush(userInfo: userInfo) {
        completionHandler(.newData)
    } else {
        completionHandler(.noData)
    }
}

ملاحظة

يدعم tvOS فقط إشعارات الدفع الصامتة مع علامة content-available: 1. عند إرسال إشعارات الدفع إلى أجهزة Apple TV من خلال Pushwoosh، تأكد من:

• تمكين علامة “content-available” في حمولة إشعار الدفع الخاص بك
• تضمين محتوى الوسائط الغنية في الإشعار

تكوين الوسائط الغنية

تحديد الموضع

يمكن وضع الوسائط الغنية المشروطة لـ tvOS في خمسة مواقع على الشاشة:

// موضع الوسط (الافتراضي)
Pushwoosh.TVoS.configureRichMediaWith(position: .center, presentAnimation: .none, dismissAnimation: .none)

// الجانب الأيسر من الشاشة
Pushwoosh.TVoS.configureRichMediaWith(position: .left, presentAnimation: .fromLeft, dismissAnimation: .toLeft)

// الجانب الأيمن من الشاشة
Pushwoosh.TVoS.configureRichMediaWith(position: .right, presentAnimation: .fromRight, dismissAnimation: .toRight)

// أعلى الشاشة
Pushwoosh.TVoS.configureRichMediaWith(position: .top, presentAnimation: .fromTop, dismissAnimation: .toTop)

// أسفل الشاشة
Pushwoosh.TVoS.configureRichMediaWith(position: .bottom, presentAnimation: .fromBottom, dismissAnimation: .toBottom)

خيارات الموضع المتاحة:

enum PWTVOSRichMediaPosition {
    case center     // المحتوى في وسط الشاشة (الافتراضي)
    case left       // المحتوى في الجانب الأيسر من الشاشة
    case right      // المحتوى في الجانب الأيمن من الشاشة
    case top        // المحتوى في أعلى الشاشة
    case bottom     // المحتوى في أسفل الشاشة
}

رسوم متحركة للظهور

تحكم في كيفية ظهور محتوى الوسائط الغنية على الشاشة:

enum PWTVOSRichMediaPresentAnimation {
    case none        // لا توجد رسوم متحركة، يظهر المحتوى فورًا (الافتراضي)
    case fromTop     // ينزلق المحتوى من أعلى الشاشة
    case fromBottom  // ينزلق المحتوى من أسفل الشاشة
    case fromLeft    // ينزلق المحتوى من الجانب الأيسر للشاشة
    case fromRight   // ينزلق المحتوى من الجانب الأيمن للشاشة
}

رسوم متحركة للاختفاء

تحكم في كيفية اختفاء محتوى الوسائط الغنية من الشاشة:

enum PWTVOSRichMediaDismissAnimation {
    case none       // لا توجد رسوم متحركة، يختفي المحتوى فورًا (الافتراضي)
    case toTop      // ينزلق المحتوى إلى خارج الشاشة من الأعلى
    case toBottom   // ينزلق المحتوى إلى خارج الشاشة من الأسفل
    case toLeft     // ينزلق المحتوى إلى خارج الشاشة من اليسار
    case toRight    // ينزلق المحتوى إلى خارج الشاشة من اليمين
}

أمثلة على التكوين

تكوين الوسائط الغنية لتظهر على الجانب الأيسر مع رسوم متحركة:

Pushwoosh.TVoS.configureRichMediaWith(
    position: .left,
    presentAnimation: .fromBottom,
    dismissAnimation: .toLeft
)

تكوين الوسائط الغنية لتظهر في الأسفل مع رسوم متحركة انزلاقية:

Pushwoosh.TVoS.configureRichMediaWith(
    position: .bottom,
    presentAnimation: .fromBottom,
    dismissAnimation: .toBottom
)

تكوين الوسائط الغنية لتظهر في الوسط بدون رسوم متحركة:

Pushwoosh.TVoS.configureRichMediaWith(
    position: .center,
    presentAnimation: .none,
    dismissAnimation: .none
)

تكوين زر الإغلاق

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

// إخفاء زر الإغلاق الخاص بالنظام
Pushwoosh.TVoS.configureCloseButton(false)

تنبيه

إذا قمت بإخفاء زر الإغلاق، تأكد من أن محتوى HTML للوسائط الغنية يتضمن زرًا مع الإجراء closeInApp للسماح للمستخدمين بإغلاق المحتوى:

<button onclick="closeInApp()">Close</button>

التنقل بالتركيز لـ Apple TV

تدير tvOS SDK تلقائيًا التنقل بالتركيز لجهاز التحكم عن بعد لـ Apple TV. ستكون العناصر التفاعلية (الأزرار، الروابط) في محتوى HTML للوسائط الغنية قابلة للتركيز باستخدام جهاز التحكم عن بعد لـ Apple TV.

سلوك التركيز

• يتم اكتشاف العناصر القابلة للتركيز تلقائيًا في محتوى HTML
• يمكن للمستخدمين التنقل بين العناصر باستخدام لوحة الاتجاهات على جهاز التحكم عن بعد لـ Apple TV
• يتلقى العنصر الذي يتم التركيز عليه حاليًا تمييزًا بصريًا
• يمكن للمستخدمين تنشيط العناصر التي يتم التركيز عليها بالضغط على الزر الأوسط في جهاز التحكم عن بعد
• زر الإغلاق الخاص بالنظام (عندما يكون مرئيًا) هو أيضًا جزء من التنقل بالتركيز

أفضل الممارسات لمحتوى HTML

عند إنشاء محتوى HTML للوسائط الغنية لـ tvOS:

1. استخدم عناصر HTML التفاعلية القياسية: <button>، <a>، <input />
2. تأكد من وجود مساحة كافية بين العناصر التفاعلية لإشارة تركيز واضحة
3. اختبر المحتوى الخاص بك باستخدام محاكي Apple TV للتحقق من التنقل بالتركيز
4. فكر في استخدام أهداف لمس أكبر مقارنة بـ iOS (يوصى بعرض لا يقل عن 250pt)

مثال تكامل كامل

إليك مثال كامل يوضح جميع الميزات:

import UIKit
import PushwooshTVOS
import PushwooshFramework

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // تكوين Pushwoosh
        Pushwoosh.TVoS.setAppCode("XXXXX-XXXXX")

        // تكوين مظهر الوسائط الغنية
        Pushwoosh.TVoS.configureRichMediaWith(
            position: .center,
            presentAnimation: .fromBottom,
            dismissAnimation: .toTop
        )

        // إظهار زر الإغلاق (الافتراضي)
        Pushwoosh.TVoS.configureCloseButton(true)

        // التسجيل لإشعارات الدفع
        Pushwoosh.TVoS.registerForTvPushNotifications()

        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Pushwoosh.TVoS.registerForTvPushNotifications(withToken: deviceToken) { error in
            if let error = error {
                print("Failed to register: \(error)")
            } else {
                print("Successfully registered")
            }
        }
    }

    func application(_ application: UIApplication,
                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
        Pushwoosh.TVoS.handleTvPushRegistrationFailure(error)
    }

    func application(_ application: UIApplication,
                     didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                     fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {

        if Pushwoosh.TVoS.handleTVOSPush(userInfo: userInfo) {
            completionHandler(.newData)
        } else {
            completionHandler(.noData)
        }
    }
}

استكشاف الأخطاء وإصلاحها

مشاكل التنقل بالتركيز

إذا كان التنقل بالتركيز لا يعمل بشكل صحيح:

1. تحقق من أن محتوى HTML الخاص بك يستخدم عناصر تفاعلية قياسية (<button>، <a>)
2. اختبر في محاكي Apple TV للتحقق من سلوك التركيز
3. تأكد من أن العناصر التفاعلية لها حجم ومسافة كافية
4. تحقق من أن HTML/CSS الخاص بك لا يتعارض مع حالات التركيز

مثال على جهاز حقيقي

إليك كيف تبدو الوسائط الغنية على جهاز Apple TV حقيقي:

تُظهر لقطة الشاشة محتوى الوسائط الغنية المعروض على Apple TV مع:

• تخطيط HTML مخصص مع خلفيات متدرجة
• أزرار تفاعلية مُحسَّنة لجهاز التحكم عن بعد لـ Apple TV
• دعم التنقل بالتركيز لجميع العناصر التفاعلية

المراجع

• كود مصدر iOS SDK
• إرشادات الواجهة البشرية لـ tvOS
• إنشاء محتوى الوسائط الغنية