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

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

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

<video src="/tv_os_rich_media.webm" title="مثال على الوسائط الغنية لـ tvOS" autoplay loop muted playsinline />

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

> لمزيد من المعلومات حول صفحات الوسائط الغنية، يرجى الرجوع إلى [دليلنا](/ar/product/content/rich-media).

## التثبيت

وحدة 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 الخاص بك:

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

  pod 'PushwooshXCFramework'
  pod 'PushwooshXCFramework/PushwooshTVOS'
end
```

ثم قم بتشغيل:

```bash
pod install
```

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

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

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

```swift
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:

```swift
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. التعامل مع إشعارات الدفع الواردة

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

```swift
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)
    }
}
```

<Aside type="note">
يدعم tvOS فقط إشعارات الدفع الصامتة مع علامة `content-available: 1`. عند إرسال إشعارات الدفع إلى أجهزة Apple TV من خلال Pushwoosh، تأكد من:
- تمكين علامة "content-available" في حمولة إشعار الدفع الخاص بك
- تضمين محتوى الوسائط الغنية في الإشعار
</Aside>

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

### تحديد الموضع

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

```swift
// موضع الوسط (الافتراضي)
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)
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```html
<button onclick="closeInApp()">Close</button>
```
</Aside>

## التنقل بالتركيز لـ 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)

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

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

```swift
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 حقيقي:

![الوسائط الغنية لـ tvOS على جهاز Apple TV](/tv_os_simulator.webp)

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

## المراجع

-   [كود مصدر iOS SDK](https://github.com/Pushwoosh/pushwoosh-ios-sdk)
-   [إرشادات الواجهة البشرية لـ tvOS](https://developer.apple.com/design/human-interface-guidelines/tvos)
-   [إنشاء محتوى الوسائط الغنية](/ar/product/content/rich-media)