Rich media modal pour tvOS

À partir de la version 6.11.0 du SDK Pushwoosh, vous avez la possibilité d’envoyer des Rich Media modaux aux appareils tvOS (Apple TV).

Le Rich Media modal pour tvOS offre un affichage de contenu interactif basé sur HTML, optimisé pour la navigation avec la télécommande de l’Apple TV. Le rich media peut être personnalisé avec différentes positions, animations et prend en charge la navigation par focus.

Attention

Les notifications push standard ne sont pas prises en charge sur tvOS. L’Apple TV n’affiche pas les bannières ou alertes de notification push traditionnelles. Seul le contenu Rich Media, livré via des notifications push silencieuses, peut être affiché à l’aide du module PushwooshTVOS.

Pour plus d’informations sur les pages Rich Media, veuillez consulter notre guide.

Installation

Le module PushwooshTVOS est optionnel et peut être intégré à votre projet tvOS en utilisant Swift Package Manager ou CocoaPods.

Swift Package Manager

Ajoutez le package Pushwoosh à votre projet tvOS :

1. Dans Xcode, sélectionnez File → Add Package Dependencies…
2. Saisissez l’URL du dépôt : https://github.com/Pushwoosh/Pushwoosh-XCFramework
3. Sélectionnez la dernière version
4. Ajoutez les frameworks suivants à votre cible tvOS :
   • PushwooshFramework
   • PushwooshCore
   • PushwooshBridge
   • PushwooshLiveActivities
   • PushwooshTVOS

CocoaPods

Ajoutez à votre Podfile :

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

  pod 'PushwooshXCFramework'
  pod 'PushwooshXCFramework/PushwooshTVOS'
end

Puis exécutez :

pod install

Intégration de base

1. Configurez Pushwoosh dans votre AppDelegate

Importez les modules requis et configurez Pushwoosh avec votre code d’application :

import UIKit
import PushwooshTVOS
import PushwooshFramework

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // Configurez Pushwoosh avec votre code d'application
        Pushwoosh.TVoS.setAppCode("XXXXX-XXXXX")

        // S'inscrire aux notifications push
        Pushwoosh.TVoS.registerForTvPushNotifications()

        return true
    }
}

2. Gérez l’enregistrement du token de l’appareil

Implémentez le gestionnaire de token de l’appareil pour enregistrer l’appareil auprès de Pushwoosh :

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Pushwoosh.TVoS.registerForTvPushNotifications(withToken: deviceToken) { error in
        if let error = error {
            print("Échec de l'enregistrement : \(error)")
        } else {
            print("Enregistrement réussi pour les notifications push")
        }
    }
}

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

3. Gérez les notifications push entrantes

Traitez les notifications push entrantes contenant du rich media :

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

    // Gérez la notification push et affichez le rich media s'il est présent
    if Pushwoosh.TVoS.handleTVOSPush(userInfo: userInfo) {
        completionHandler(.newData)
    } else {
        completionHandler(.noData)
    }
}

Note

tvOS ne prend en charge que les notifications push silencieuses avec l’indicateur content-available: 1. Lors de l’envoi de notifications push aux appareils Apple TV via Pushwoosh, assurez-vous de :

• Activer l’indicateur « content-available » dans la charge utile de votre notification push
• Inclure du contenu Rich Media dans la notification

Configuration du Rich Media

Positionnement

Le Rich Media modal pour tvOS peut être positionné à cinq endroits sur l’écran :

// Position centrale (par défaut)
Pushwoosh.TVoS.configureRichMediaWith(position: .center, presentAnimation: .none, dismissAnimation: .none)

// Côté gauche de l'écran
Pushwoosh.TVoS.configureRichMediaWith(position: .left, presentAnimation: .fromLeft, dismissAnimation: .toLeft)

// Côté droit de l'écran
Pushwoosh.TVoS.configureRichMediaWith(position: .right, presentAnimation: .fromRight, dismissAnimation: .toRight)

// Haut de l'écran
Pushwoosh.TVoS.configureRichMediaWith(position: .top, presentAnimation: .fromTop, dismissAnimation: .toTop)

// Bas de l'écran
Pushwoosh.TVoS.configureRichMediaWith(position: .bottom, presentAnimation: .fromBottom, dismissAnimation: .toBottom)

Options de position disponibles :

enum PWTVOSRichMediaPosition {
    case center     // Contenu positionné au centre de l'écran (par défaut)
    case left       // Contenu positionné sur le côté gauche de l'écran
    case right      // Contenu positionné sur le côté droit de l'écran
    case top        // Contenu positionné en haut de l'écran
    case bottom     // Contenu positionné en bas de l'écran
}

Animations d’apparition

Contrôlez la manière dont le contenu rich media apparaît à l’écran :

enum PWTVOSRichMediaPresentAnimation {
    case none        // Pas d'animation, le contenu apparaît immédiatement (par défaut)
    case fromTop     // Le contenu glisse depuis le haut de l'écran
    case fromBottom  // Le contenu glisse depuis le bas de l'écran
    case fromLeft    // Le contenu glisse depuis le côté gauche de l'écran
    case fromRight   // Le contenu glisse depuis le côté droit de l'écran
}

Animations de disparition

Contrôlez la manière dont le contenu rich media disparaît de l’écran :

enum PWTVOSRichMediaDismissAnimation {
    case none       // Pas d'animation, le contenu disparaît immédiatement (par défaut)
    case toTop      // Le contenu glisse vers le haut de l'écran
    case toBottom   // Le contenu glisse vers le bas de l'écran
    case toLeft     // Le contenu glisse vers le côté gauche de l'écran
    case toRight    // Le contenu glisse vers le côté droit de l'écran
}

Exemples de configuration

Configurez le rich media pour qu’il apparaisse sur le côté gauche avec des animations :

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

Configurez le rich media pour qu’il apparaisse en bas avec des animations de glissement :

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

Configurez le rich media pour qu’il apparaisse centré sans animations :

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

Configuration du bouton Fermer

Par défaut, un bouton Fermer est affiché en bas des présentations rich media. Vous pouvez masquer ce bouton si nécessaire :

// Masquer le bouton Fermer du système
Pushwoosh.TVoS.configureCloseButton(false)

Attention

Si vous masquez le bouton Fermer, assurez-vous que votre contenu HTML rich media inclut un bouton avec l’action closeInApp pour permettre aux utilisateurs de fermer le contenu :

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

Navigation par focus pour l’Apple TV

Le SDK tvOS gère automatiquement la navigation par focus pour la télécommande de l’Apple TV. Les éléments interactifs (boutons, liens) de votre contenu HTML rich media seront focalisables à l’aide de la télécommande de l’Apple TV.

Comportement du focus

• Les éléments focalisables sont automatiquement détectés dans le contenu HTML
• Les utilisateurs peuvent naviguer entre les éléments à l’aide du pavé directionnel de la télécommande de l’Apple TV
• L’élément actuellement focalisé reçoit une mise en évidence visuelle
• Les utilisateurs peuvent activer les éléments focalisés en appuyant sur le bouton central de la télécommande
• Le bouton Fermer du système (lorsqu’il est visible) fait également partie de la navigation par focus

Bonnes pratiques pour le contenu HTML

Lors de la création de contenu HTML pour le rich media tvOS :

1. Utilisez des éléments HTML interactifs standard : <button>, <a>, <input />
2. Assurez-vous qu’il y a suffisamment d’espace entre les éléments interactifs pour une indication claire du focus
3. Testez votre contenu avec le simulateur Apple TV pour vérifier la navigation par focus
4. Envisagez d’utiliser des cibles tactiles plus grandes que pour iOS (largeur minimale de 250 pt recommandée)

Exemple d’intégration complet

Voici un exemple complet montrant toutes les fonctionnalités :

import UIKit
import PushwooshTVOS
import PushwooshFramework

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

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

        // Configurez l'apparence du rich media
        Pushwoosh.TVoS.configureRichMediaWith(
            position: .center,
            presentAnimation: .fromBottom,
            dismissAnimation: .toTop
        )

        // Affichez le bouton Fermer (par défaut)
        Pushwoosh.TVoS.configureCloseButton(true)

        // S'inscrire aux notifications push
        Pushwoosh.TVoS.registerForTvPushNotifications()

        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Pushwoosh.TVoS.registerForTvPushNotifications(withToken: deviceToken) { error in
            if let error = error {
                print("Échec de l'enregistrement : \(error)")
            } else {
                print("Enregistrement réussi")
            }
        }
    }

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

Dépannage

Problèmes de navigation par focus

Si la navigation par focus ne fonctionne pas correctement :

1. Vérifiez que votre contenu HTML utilise des éléments interactifs standard (<button>, <a>)
2. Testez dans le simulateur Apple TV pour vérifier le comportement du focus
3. Assurez-vous que les éléments interactifs ont une taille et un espacement suffisants
4. Vérifiez que votre HTML/CSS n’interfère pas avec les états de focus

Exemple sur un appareil réel

Voici à quoi ressemble le rich media sur un appareil Apple TV réel :

La capture d’écran montre le contenu rich media affiché sur Apple TV avec :

• Une mise en page HTML personnalisée avec des arrière-plans en dégradé
• Des boutons interactifs optimisés pour la télécommande de l’Apple TV
• La prise en charge de la navigation par focus pour tous les éléments interactifs

Références

• Code source du SDK iOS
• Directives de l’interface humaine pour tvOS
• Création de contenu Rich Media