Modale Rich Media für tvOS

Ab der Pushwoosh SDK-Version 6.11.0 haben Sie die Möglichkeit, modale Rich Media an tvOS-Geräte (Apple TV) zu senden.

Modale Rich Media für tvOS bietet eine interaktive HTML-basierte Inhaltsanzeige, die für die Navigation mit der Fernbedienung von Apple TV optimiert ist. Die Rich Media kann mit verschiedenen Positionen, Animationen und Unterstützung für die Fokus-Navigation angepasst werden.

Vorsicht

Standard-Push-Benachrichtigungen werden auf tvOS nicht unterstützt. Apple TV zeigt keine herkömmlichen Push-Benachrichtigungsbanner oder -warnungen an. Nur Rich-Media-Inhalte, die über stille Push-Benachrichtigungen zugestellt werden, können mit dem PushwooshTVOS-Modul angezeigt werden.

Weitere Informationen zu Rich-Media-Seiten finden Sie in unserem Leitfaden.

Installation

Das PushwooshTVOS-Modul ist optional und kann über den Swift Package Manager oder CocoaPods in Ihr tvOS-Projekt integriert werden.

Swift Package Manager

Fügen Sie das Pushwoosh-Paket zu Ihrem tvOS-Projekt hinzu:

1. Wählen Sie in Xcode File → Add Package Dependencies…
2. Geben Sie die Repository-URL ein: https://github.com/Pushwoosh/Pushwoosh-XCFramework
3. Wählen Sie die neueste Version aus
4. Fügen Sie die folgenden Frameworks zu Ihrem tvOS-Ziel hinzu:
   • PushwooshFramework
   • PushwooshCore
   • PushwooshBridge
   • PushwooshLiveActivities
   • PushwooshTVOS

CocoaPods

Fügen Sie dies zu Ihrer Podfile hinzu:

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

  pod 'PushwooshXCFramework'
  pod 'PushwooshXCFramework/PushwooshTVOS'
end

Führen Sie dann aus:

pod install

Grundlegende Integration

1. Konfigurieren Sie Pushwoosh in Ihrem AppDelegate

Importieren Sie die erforderlichen Module und konfigurieren Sie Pushwoosh mit Ihrem Anwendungscode:

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. Behandeln der Device-Token-Registrierung

Implementieren Sie den Device-Token-Handler, um das Gerät bei Pushwoosh zu registrieren:

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. Behandeln eingehender Push-Benachrichtigungen

Verarbeiten Sie eingehende Push-Benachrichtigungen mit Rich-Media-Inhalten:

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

Hinweis

tvOS unterstützt nur stille Push-Benachrichtigungen mit dem content-available: 1-Flag. Wenn Sie Push-Benachrichtigungen über Pushwoosh an Apple TV-Geräte senden, stellen Sie sicher, dass Sie:

• das „content-available“-Flag in Ihrer Push-Benachrichtigungs-Payload aktivieren
• Rich-Media-Inhalte in die Benachrichtigung aufnehmen

Rich-Media-Konfiguration

Positionierung

Modale Rich Media für tvOS kann an fünf Stellen auf dem Bildschirm positioniert werden:

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

// Left side of the screen
Pushwoosh.TVoS.configureRichMediaWith(position: .left, presentAnimation: .fromLeft, dismissAnimation: .toLeft)

// Right side of the screen
Pushwoosh.TVoS.configureRichMediaWith(position: .right, presentAnimation: .fromRight, dismissAnimation: .toRight)

// Top of the screen
Pushwoosh.TVoS.configureRichMediaWith(position: .top, presentAnimation: .fromTop, dismissAnimation: .toTop)

// Bottom of the screen
Pushwoosh.TVoS.configureRichMediaWith(position: .bottom, presentAnimation: .fromBottom, dismissAnimation: .toBottom)

Verfügbare Positionsoptionen:

enum PWTVOSRichMediaPosition {
    case center     // Content positioned at the center of the screen (default)
    case left       // Content positioned at the left side of the screen
    case right      // Content positioned at the right side of the screen
    case top        // Content positioned at the top of the screen
    case bottom     // Content positioned at the bottom of the screen
}

Präsentationsanimationen

Steuern Sie, wie Rich-Media-Inhalte auf dem Bildschirm erscheinen:

enum PWTVOSRichMediaPresentAnimation {
    case none        // No animation, content appears immediately (default)
    case fromTop     // Content slides in from the top of the screen
    case fromBottom  // Content slides in from the bottom of the screen
    case fromLeft    // Content slides in from the left side of the screen
    case fromRight   // Content slides in from the right side of the screen
}

Ausblendanimationen

Steuern Sie, wie Rich-Media-Inhalte vom Bildschirm verschwinden:

enum PWTVOSRichMediaDismissAnimation {
    case none       // No animation, content disappears immediately (default)
    case toTop      // Content slides out to the top of the screen
    case toBottom   // Content slides out to the bottom of the screen
    case toLeft     // Content slides out to the left side of the screen
    case toRight    // Content slides out to the right side of the screen
}

Konfigurationsbeispiele

Konfigurieren Sie Rich Media so, dass sie auf der linken Seite mit Animationen erscheint:

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

Konfigurieren Sie Rich Media so, dass sie unten mit Slide-Animationen erscheint:

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

Konfigurieren Sie Rich Media so, dass sie zentriert ohne Animationen erscheint:

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

Konfiguration der Schließen-Schaltfläche

Standardmäßig wird am unteren Rand von Rich-Media-Präsentationen eine Schließen-Schaltfläche angezeigt. Sie können diese Schaltfläche bei Bedarf ausblenden:

// Hide the system Close button
Pushwoosh.TVoS.configureCloseButton(false)

Vorsicht

Wenn Sie die Schließen-Schaltfläche ausblenden, stellen Sie sicher, dass Ihr Rich-Media-HTML-Inhalt eine Schaltfläche mit der closeInApp-Aktion enthält, damit Benutzer den Inhalt schließen können:

<button onclick="closeInApp()">Schließen</button>

Fokus-Navigation für Apple TV

Das tvOS SDK verwaltet automatisch die Fokus-Navigation für die Fernbedienung von Apple TV. Interaktive Elemente (Schaltflächen, Links) in Ihrem Rich-Media-HTML-Inhalt sind mit der Apple TV-Fernbedienung fokussierbar.

Fokus-Verhalten

• Fokussierbare Elemente werden automatisch im HTML-Inhalt erkannt
• Benutzer können mit dem Steuerkreuz der Apple TV-Fernbedienung zwischen den Elementen navigieren
• Das aktuell fokussierte Element wird visuell hervorgehoben
• Benutzer können fokussierte Elemente durch Drücken der mittleren Taste auf der Fernbedienung aktivieren
• Die System-Schaltfläche „Schließen“ (sofern sichtbar) ist ebenfalls Teil der Fokus-Navigation

Best Practices für HTML-Inhalte

Beim Erstellen von HTML-Inhalten für tvOS Rich Media:

1. Verwenden Sie standardmäßige interaktive HTML-Elemente: <button>, <a>, <input />
2. Stellen Sie sicher, dass zwischen interaktiven Elementen genügend Abstand für eine klare Fokusanzeige vorhanden ist
3. Testen Sie Ihre Inhalte mit dem Apple TV-Simulator, um die Fokus-Navigation zu überprüfen
4. Erwägen Sie die Verwendung größerer Touch-Ziele im Vergleich zu iOS (empfohlene Mindestbreite 250pt)

Vollständiges Integrationsbeispiel

Hier ist ein vollständiges Beispiel, das alle Funktionen zeigt:

import UIKit
import PushwooshTVOS
import PushwooshFramework

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // Configure Pushwoosh
        Pushwoosh.TVoS.setAppCode("XXXXX-XXXXX")

        // Configure rich media appearance
        Pushwoosh.TVoS.configureRichMediaWith(
            position: .center,
            presentAnimation: .fromBottom,
            dismissAnimation: .toTop
        )

        // Show close button (default)
        Pushwoosh.TVoS.configureCloseButton(true)

        // Register for push notifications
        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)
        }
    }
}

Fehlerbehebung

Probleme mit der Fokus-Navigation

Wenn die Fokus-Navigation nicht ordnungsgemäß funktioniert:

1. Überprüfen Sie, ob Ihr HTML-Inhalt standardmäßige interaktive Elemente (<button>, <a>) verwendet
2. Testen Sie im Apple TV-Simulator, um das Fokus-Verhalten zu überprüfen
3. Stellen Sie sicher, dass interaktive Elemente eine ausreichende Größe und einen ausreichenden Abstand haben
4. Überprüfen Sie, ob Ihr HTML/CSS die Fokus-Zustände nicht beeinträchtigt

Beispiel auf einem echten Gerät

So sieht die Rich Media auf einem echten Apple TV-Gerät aus:

Der Screenshot zeigt den auf Apple TV angezeigten Rich-Media-Inhalt mit:

• Benutzerdefiniertem HTML-Layout mit Verlaufs-Hintergründen
• Interaktiven Schaltflächen, die für die Fernbedienung von Apple TV optimiert sind
• Unterstützung der Fokus-Navigation für alle interaktiven Elemente

Referenzen

• iOS SDK Quellcode
• tvOS Human Interface Guidelines
• Erstellen von Rich-Media-Inhalten