Rich Media Modal para tvOS

A partir da versão 6.11.0 do SDK da Pushwoosh, você tem a capacidade de enviar Rich Media Modal para dispositivos tvOS (Apple TV).

O Rich Media Modal para tvOS oferece uma exibição de conteúdo interativo baseado em HTML, otimizado para a navegação com o controle remoto da Apple TV. O rich media pode ser personalizado com diferentes posições, animações e suporte à navegação por foco.

Cuidado

Notificações push padrão não são suportadas no tvOS. A Apple TV não exibe banners ou alertas de notificação push tradicionais. Apenas conteúdo Rich Media entregue através de notificações push silenciosas pode ser exibido usando o módulo PushwooshTVOS.

Para mais informações sobre páginas de Rich Media, consulte nosso guia.

Instalação

O módulo PushwooshTVOS é opcional e pode ser integrado ao seu projeto tvOS usando o Swift Package Manager ou CocoaPods.

Swift Package Manager

Adicione o pacote Pushwoosh ao seu projeto tvOS:

1. No Xcode, selecione File → Add Package Dependencies…
2. Insira a URL do repositório: https://github.com/Pushwoosh/Pushwoosh-XCFramework
3. Selecione a versão mais recente
4. Adicione os seguintes frameworks ao seu alvo tvOS:
   • PushwooshFramework
   • PushwooshCore
   • PushwooshBridge
   • PushwooshLiveActivities
   • PushwooshTVOS

CocoaPods

Adicione ao seu Podfile:

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

  pod 'PushwooshXCFramework'
  pod 'PushwooshXCFramework/PushwooshTVOS'
end

Em seguida, execute:

pod install

Integração básica

1. Configure o Pushwoosh no seu AppDelegate

Importe os módulos necessários e configure o Pushwoosh com o código da sua aplicação:

import UIKit
import PushwooshTVOS
import PushwooshFramework

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // Configure o Pushwoosh com o código do seu aplicativo
        Pushwoosh.TVoS.setAppCode("XXXXX-XXXXX")

        // Registre-se para notificações push
        Pushwoosh.TVoS.registerForTvPushNotifications()

        return true
    }
}

2. Lidar com o registro do token do dispositivo

Implemente o manipulador de token do dispositivo para registrar o dispositivo na Pushwoosh:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Pushwoosh.TVoS.registerForTvPushNotifications(withToken: deviceToken) { error in
        if let error = error {
            print("Falha ao registrar: \(error)")
        } else {
            print("Registrado com sucesso para notificações push")
        }
    }
}

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

3. Lidar com notificações push recebidas

Processe as notificações push recebidas com conteúdo rich media:

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

    // Lide com a notificação push e exiba o rich media se presente
    if Pushwoosh.TVoS.handleTVOSPush(userInfo: userInfo) {
        completionHandler(.newData)
    } else {
        completionHandler(.noData)
    }
}

Nota

O tvOS suporta apenas notificações push silenciosas com a flag content-available: 1. Ao enviar notificações push para dispositivos Apple TV através da Pushwoosh, certifique-se de:

• Habilitar a flag “content-available” no payload da sua notificação push
• Incluir conteúdo Rich Media na notificação

Configuração de Rich Media

Posicionamento

O Rich Media Modal para tvOS pode ser posicionado em cinco locais na tela:

// Posição central (padrão)
Pushwoosh.TVoS.configureRichMediaWith(position: .center, presentAnimation: .none, dismissAnimation: .none)

// Lado esquerdo da tela
Pushwoosh.TVoS.configureRichMediaWith(position: .left, presentAnimation: .fromLeft, dismissAnimation: .toLeft)

// Lado direito da tela
Pushwoosh.TVoS.configureRichMediaWith(position: .right, presentAnimation: .fromRight, dismissAnimation: .toRight)

// Topo da tela
Pushwoosh.TVoS.configureRichMediaWith(position: .top, presentAnimation: .fromTop, dismissAnimation: .toTop)

// Parte inferior da tela
Pushwoosh.TVoS.configureRichMediaWith(position: .bottom, presentAnimation: .fromBottom, dismissAnimation: .toBottom)

Opções de posição disponíveis:

enum PWTVOSRichMediaPosition {
    case center     // Conteúdo posicionado no centro da tela (padrão)
    case left       // Conteúdo posicionado no lado esquerdo da tela
    case right      // Conteúdo posicionado no lado direito da tela
    case top        // Conteúdo posicionado no topo da tela
    case bottom     // Conteúdo posicionado na parte inferior da tela
}

Animações de apresentação

Controle como o conteúdo rich media aparece na tela:

enum PWTVOSRichMediaPresentAnimation {
    case none        // Sem animação, o conteúdo aparece imediatamente (padrão)
    case fromTop     // O conteúdo desliza do topo da tela
    case fromBottom  // O conteúdo desliza da parte inferior da tela
    case fromLeft    // O conteúdo desliza do lado esquerdo da tela
    case fromRight   // O conteúdo desliza do lado direito da tela
}

Animações de dispensa

Controle como o conteúdo rich media desaparece da tela:

enum PWTVOSRichMediaDismissAnimation {
    case none       // Sem animação, o conteúdo desaparece imediatamente (padrão)
    case toTop      // O conteúdo desliza para fora pelo topo da tela
    case toBottom   // O conteúdo desliza para fora pela parte inferior da tela
    case toLeft     // O conteúdo desliza para fora pelo lado esquerdo da tela
    case toRight    // O conteúdo desliza para fora pelo lado direito da tela
}

Exemplos de configuração

Configure o rich media para aparecer no lado esquerdo com animações:

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

Configure o rich media para aparecer na parte inferior com animações de deslize:

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

Configure o rich media para aparecer centralizado sem animações:

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

Configuração do botão Fechar

Por padrão, um botão Fechar é exibido na parte inferior das apresentações de rich media. Você pode ocultar este botão se necessário:

// Ocultar o botão Fechar do sistema
Pushwoosh.TVoS.configureCloseButton(false)

Cuidado

Se você ocultar o botão Fechar, certifique-se de que seu conteúdo HTML de rich media inclua um botão com a ação closeInApp para permitir que os usuários dispensem o conteúdo:

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

Navegação por foco para Apple TV

O SDK do tvOS gerencia automaticamente a navegação por foco para o controle remoto da Apple TV. Elementos interativos (botões, links) em seu conteúdo HTML de rich media serão focáveis usando o controle remoto da Apple TV.

Comportamento do foco

• Elementos focáveis são detectados automaticamente no conteúdo HTML
• Os usuários podem navegar entre os elementos usando o direcional do controle remoto da Apple TV
• O elemento atualmente focado recebe um destaque visual
• Os usuários podem ativar elementos focados pressionando o botão central no controle remoto
• O botão Fechar do sistema (quando visível) também faz parte da navegação por foco

Melhores práticas para conteúdo HTML

Ao criar conteúdo HTML para rich media do tvOS:

1. Use elementos HTML interativos padrão: <button>, <a>, <input />
2. Garanta espaçamento suficiente entre os elementos interativos para uma indicação clara do foco
3. Teste seu conteúdo com o simulador da Apple TV para verificar a navegação por foco
4. Considere usar alvos de toque maiores em comparação com o iOS (largura mínima recomendada de 250pt)

Exemplo de integração completa

Aqui está um exemplo completo mostrando todos os recursos:

import UIKit
import PushwooshTVOS
import PushwooshFramework

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

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

        // Configure a aparência do rich media
        Pushwoosh.TVoS.configureRichMediaWith(
            position: .center,
            presentAnimation: .fromBottom,
            dismissAnimation: .toTop
        )

        // Mostrar botão de fechar (padrão)
        Pushwoosh.TVoS.configureCloseButton(true)

        // Registre-se para notificações 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("Falha ao registrar: \(error)")
            } else {
                print("Registrado com sucesso")
            }
        }
    }

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

Solução de problemas

Problemas de navegação por foco

Se a navegação por foco não estiver funcionando corretamente:

1. Verifique se o seu conteúdo HTML usa elementos interativos padrão (<button>, <a>)
2. Teste no simulador da Apple TV para verificar o comportamento do foco
3. Certifique-se de que os elementos interativos tenham tamanho e espaçamento suficientes
4. Verifique se o seu HTML/CSS não interfere nos estados de foco

Exemplo em dispositivo real

Veja como o rich media se parece em um dispositivo Apple TV real:

A captura de tela mostra o conteúdo rich media exibido na Apple TV com:

• Layout HTML personalizado com fundos gradientes
• Botões interativos otimizados para o controle remoto da Apple TV
• Suporte à navegação por foco para todos os elementos interativos

Referências

• Código Fonte do SDK para iOS
• Diretrizes de Interface Humana do tvOS
• Criando Conteúdo Rich Media