Live Activity

Uma Live Activity é um cartão que se atualiza em tempo real para que o usuário veja o progresso sem abrir o app (status de voo, entrega, corrida e similares). No iOS, é um pequeno cartão na tela de bloqueio e na Dynamic Island. No Android 16 e posteriores, é o mesmo tipo de cartão, exibido como uma notificação contínua com uma barra de progresso.

Use o elemento Live Activity em uma journey para iniciar, atualizar ou encerrar esse cartão, no iOS, no Android ou em ambos.

Cada elemento executa uma ação:

• Start: criar o cartão.
• Update: alterar um cartão existente.
• End: fechar o cartão.

Para alterar ou fechar o mesmo cartão mais tarde, adicione outro elemento Live Activity e aponte-o de volta para aquele que criou o cartão com Card created by.

Exemplos de casos de uso

Use este elemento sempre que o usuário deve ver um status que continua mudando, sem abrir o app.

• Status de voo: mostre o cartão após o check-in. Mantenha o portão, o status e o horário atualizados durante o voo. Remova o cartão após o pouso.
• Entrega de comida: mostre o cartão quando o pedido for feito. Mantenha o nome do entregador, o horário estimado de chegada e a distância atualizados no caminho. Remova o cartão na entrega.
• Corrida por aplicativo: mostre o cartão quando a corrida for solicitada. Mantenha o motorista, o horário estimado de chegada e a placa atualizados enquanto o motorista se aproxima. Remova o cartão quando a corrida for concluída.
• Pedido ou consulta: mostre o cartão quando o pedido ou agendamento for confirmado. Mantenha o status atualizado à medida que avança. Remova o cartão quando for concluído ou a visita terminar.
• Evento ao vivo: mostre o cartão quando o evento começar. Mantenha o placar, período ou cronograma atualizados enquanto ele acontece. Remova o cartão quando o evento terminar.

Dica

Para journeys completas, veja Como mostrar o status de um voo na tela de bloqueio e Como mostrar o progresso de uma entrega na tela de bloqueio.

Pré-requisitos

Antes de configurar este elemento, verifique o que cada plataforma precisa.

Para o cartão do iOS:

• Suporte a Live Activity do iOS: seu app deve suportar Live Activities. Veja o guia de Live Activities do iOS SDK.
• Um esquema de widget publicado: peça à sua equipe de desenvolvimento para publicar o esquema que corresponde ao tipo de Live Activity no app em Applications → Configure → Live Activity schemas. Eles também podem publicar via API. Para saber o que pertence a um esquema, veja Escrevendo um esquema.
• Widget na lista: depois que o esquema for publicado, selecione-o em Widget neste elemento. Se a lista Widget estiver vazia, o esquema ainda não foi publicado.

Para a notificação do Android:

• Suporte a Android Live Updates: seu app precisa do SDK 6.11+ e do módulo pushwoosh-liveupdates. Nenhum esquema é necessário para o Android. Peça ao seu desenvolvedor Android para confirmar que o módulo está no build.

Configurar o elemento

1. Arraste o elemento Live Activity para a tela.

   

2. Clique duas vezes no elemento para abrir suas configurações.

3. Digite um nome em Step name.

4. Em Action, escolha uma das seguintes opções:

   • Start: criar o cartão Live Activity.
   • Update: alterar o conteúdo de um cartão existente.
   • End: fechar o cartão.

5. Em Platforms, ative iOS Live Activity, Android Live Updates ou ambos. Pelo menos uma plataforma deve permanecer ativada, então você não pode desativar a última. Em Update e End, Platforms mostra as plataformas do elemento Start vinculado e é somente leitura.

   

6. Somente em Start, defina a chave do cartão para que as etapas posteriores de Update e End possam encontrar este cartão:

   • Em Card key: event, selecione o evento que identifica o cartão (por exemplo, o evento de entrada da journey).
   • Em Card key: attribute, selecione o atributo que torna a chave única por viajante. Isso é obrigatório assim que você define Card key: event. Deixá-lo não definido faz com que a seleção do evento não tenha efeito, o mesmo que deixar ambos os campos vazios: um cartão por viajante, endereçado pelo User ID padrão.

   

Vincular Update e End ao cartão correto

Quando Action é Update ou End, use Card created by para apontar para o elemento Start exato que criou este cartão. Caso contrário, Update ou End não o alcançará.

1. Em Card created by, selecione o Step name daquele elemento Start (por exemplo, Order card start).

Depois de escolher Card created by, Card key (from the start element) mostra os valores de Card key: event e Card key: attribute daquele Start. É somente leitura e confirma para qual cartão isso aponta.

Nota

Exemplo: Start é nomeado Order card start. Em Update e End, escolha Order card start em Card created by. Ambas as etapas então alteram ou fecham esse mesmo cartão de pedido.

Escolher o idioma do cartão

Card language se aplica tanto ao cartão do iOS quanto à notificação do Android.

Defina Card language como default ou um código de idioma específico. O conteúdo em default é o padrão de reserva para qualquer idioma que você não preencher separadamente.

Configurar o cartão do iOS

Pule esta seção se apenas Android Live Updates estiver ativado.

Escolher o widget e a versão do esquema

1. Em Widget, selecione o tipo de Live Activity publicado para este cartão. Os campos de conteúdo abaixo vêm dessa escolha. Em Update ou End, Widget é somente leitura, herdado do elemento Card created by.

2. Em Schema version, selecione qual versão publicada do esquema desse widget usar. Os campos Card content vêm dessa versão. Em Update e End, Schema version continua sendo um seletor: você pode escolher uma versão publicada diferente do mesmo widget herdado da que o Start vinculado usou.

   

Definir os atributos fixos do cartão (somente Start)

Em Start, em Card attributes, adicione os campos que permanecem fixos durante toda a vida do cartão, definidos uma vez e nunca mais alterados, como um número de voo ou um ID de pedido. Estes são separados dos campos Card content abaixo. Esses valores podem mudar em Update.

Peça ao seu desenvolvedor iOS a lista exata de Field name. Esses nomes permanecem fixos durante toda a vida do cartão (o tipo ActivityAttributes do app). Não use os nomes variáveis de Card content (o ContentState do app).

1. Clique em Add attribute.
2. Defina Field name e Value para cada atributo que você precisar.

Update e End não definem atributos. O que Start definiu para este cartão permanece fixo.

Cuidado

Os atributos do cartão são enviados exatamente como o tipo ActivityAttributes do seu app espera, campo por campo. Erre um nome, ou deixe-os vazios, e o decodificador do dispositivo rejeita todo o payload. Em um teste real, um Start com flightNumber abriu o cartão, e um Start sem atributos entregou apenas o envelope, sem nada para mostrar na tela de bloqueio.

Preencher o conteúdo do cartão

Em Card content, digite um valor literal ou um placeholder de personalização em cada campo. Um campo aparece para cada propriedade na versão do esquema selecionada.

Pré-preenchimento em Update e End

Em Update ou End, se Card content para o Card language atual estiver vazio (incluindo um idioma que você acabou de adicionar), o Pushwoosh pré-preenche os campos a partir do elemento Start vinculado quando você abre as configurações:

• Mesmo idioma que Start, se esse idioma tiver conteúdo.
• Caso contrário, o conteúdo default de Start.
• Se Start não tiver nenhum dos dois, deixe os campos vazios e preencha-os por conta própria.

Os valores pré-preenchidos permanecem editáveis. Clique em Apply somente quando quiser manter as edições. Apenas abrir o elemento não altera uma journey em execução.

Os campos que você deixar vazios em Update ou End não são enviados. O que o cartão então mostra nesses campos depende do seu app: ele pode manter o valor anterior, limpá-lo ou fazer outra coisa. Pergunte aos seus desenvolvedores como seu app lida com isso.

Em End, Card content é opcional. Um campo que você preenche se torna o último valor mostrado antes de o cartão fechar.

Definir prioridade e tempo de entrega

1. Em Delivery priority, escolha quando o iOS deve entregar esta atualização:

   • Immediate: o iOS entrega imediatamente e pode despertar o telefone (e tocar o som, se você definir um).
   • Quiet: o iOS pode entregar mais tarde junto com outras atualizações e não desperta o telefone imediatamente.
   • Default (batched): o iOS usa sua própria entrega em lote padrão e não desperta o telefone imediatamente.

2. Em Sound, selecione um som da lista. Sua equipe de desenvolvimento adiciona arquivos de som ao pacote do app iOS. Veja Som de push personalizado. O som só toca junto com Alert title ou Alert text, assim como o banner.

3. Dependendo da Action que você definir para este elemento (Start, Update ou End), preencha um dos seguintes:

   • Start ou Update: defina Stale after, min para quantos minutos os dados no cartão devem parecer atualizados. Quando esse tempo terminar, o iOS esmaece os números como desatualizados. O cartão permanece na tela de bloqueio. Para manter os números parecendo atuais, envie outro Update antes de o tempo terminar.
   • End: defina Dismiss after, min para quanto tempo o cartão fechado permanece na tela de bloqueio antes de o iOS removê-lo. Deixe em 0 e o cartão continuará mostrando seu Card content final até que o iOS o retire por conta própria, em até 4 horas.

4. Opcionalmente, defina Relevance score como um número de 1 a 100. Quando uma pessoa tem mais de uma Live Activity ativa do seu app ao mesmo tempo, o iOS mostra primeiro a de pontuação mais alta. Deixe em 0 para não definir uma preferência. O Pushwoosh não envia uma pontuação 0 à Apple de forma alguma. Veja Múltiplas atividades por dispositivo para o quadro completo.

Preencher a notificação do Android

Preencha o título, o texto, a barra de progresso e o horário do cabeçalho da notificação do Android. Esta seção aparece somente quando Android Live Updates está ativado. Ela usa o mesmo Card language do cartão do iOS.

1. Defina Notification title para cada idioma que você preencher para o Android. Em Start e Update, a journey não pode ser executada até que cada um desses idiomas tenha um título. Um idioma sem título mostra um lembrete no formulário.

2. Defina Notification text.

   

3. Configure a barra de progresso:

   • Progress: digite um número ou um placeholder no formato {name} (opcionalmente {name|format} ou {name|format|default}) para a posição da barra, nas mesmas unidades dos comprimentos dos segmentos.
   • Segments: clique em Add segment para cada parte colorida da barra e defina uma Color hexadecimal (#RRGGBB ou #AARRGGBB) e um Length para cada uma. Os comprimentos dos segmentos somados formam a barra completa.
   • Animate the bar without a known end: ative para mostrar uma barra em movimento em vez do valor de Progress.
   • Hide the progress bar: ative para mostrar o cartão sem barra.

   

4. Defina o horário do cabeçalho:

   • Header time: digite um timestamp Unix em segundos (não milissegundos), ou um placeholder, para o momento que o relógio do cabeçalho do cartão deve mostrar. Por exemplo, 1735689600 significa 2025-01-01 00:00 UTC. Se este campo e Header time after, min estiverem definidos, Header time é usado.
   • Header time after, min: defina quantos minutos após o envio o horário do cabeçalho deve mostrar.
   • Run the header time as a timer: ative para mostrar Header time como um relógio em andamento em vez de um valor fixo. Isso revela Count down to the header time.
   • Count down to the header time: ative para fazer uma contagem regressiva até Header time em vez de contar a partir do envio.
   • Hide the header time: ative para mostrar o cartão sem o horário do cabeçalho.

   

Qualquer campo acima pode conter um placeholder, resolvido da mesma forma que os campos Card content do iOS: a partir do evento da journey ou personalizado com um atributo de evento.

Alguns dispositivos Android não mostrarão a notificação

• Android 15 ou anterior, ou um app sem o módulo pushwoosh-liveupdates: o Pushwoosh ainda envia a atualização, mas nada aparece no dispositivo, e nenhum push comum é mostrado no lugar.
• Dispositivos Huawei e Baidu: eles não recebem Android Live Updates. As atualizações vão apenas para dispositivos registrados pelo Firebase Cloud Messaging (FCM).

Tocar na notificação abre o app, assim como um push comum.

Definir o banner de alerta

Esta seção se aplica somente quando iOS Live Activity está ativado. Se apenas Android Live Updates estiver ativado, esses campos ficam ocultos e nada é enviado.

Para as três ações (Start, Update e End):

1. Em Alert title, defina o título do banner mostrado na tela de bloqueio.
2. Em Alert text, defina o texto do banner.

Cuidado

Se tanto Alert title quanto Alert text estiverem vazios, o cartão ainda inicia, atualiza ou encerra, mas a tela de bloqueio não mostra nenhum banner nem toca nenhum som. Preencha pelo menos um dos dois quando esta ação deve aparecer em uma tela bloqueada.

Escolher qual dispositivo recebe o cartão

O endereçamento é definido uma vez, em Start. Deixe ambos os interruptores desligados para enviar o cartão para o dispositivo em que o viajante entrou na journey. Ativar um dos interruptores desativa o outro:

• Send to all devices of this user: enviar para todos os dispositivos registrados sob o User ID daquele viajante, não apenas aquele em que ele entrou.
• Send to the last active device only: enviar para o único dispositivo que aquele User ID usou mais recentemente, em vez de todos os dispositivos ou o dispositivo de entrada.

Dica

Ative Send to the last active device only quando a mesma pessoa puder estar assistindo em um iPhone diferente daquele que entrou na journey.

Em Update e End, verifique Delivery (from the start element). Ele nomeia o modo de endereçamento do Start vinculado. A atualização só pode alcançar o mesmo cartão, então ela sai da mesma forma.

Nota

Ambos os interruptores travam assim que a journey começa a rodar, também em Start. Para alterar o endereçamento depois disso, pause a journey primeiro.

Personalizar o conteúdo

Use isso quando os placeholders em Alert title, Alert text, Card content ou nos campos do Android Notification title, Notification text, Progress ou Header time devem obter valores do evento da journey ou da entrada baseada em API, em vez das tags do dispositivo.

1. Em Overwrite personalization, ative Personalise message with event attributes.
2. Marque a caixa Overwrite placeholder ao lado de cada placeholder que você quer remapear.
3. Mapeie esse placeholder para um atributo de evento.

Salvar o elemento

Clique em Apply para salvar as configurações do elemento. Apply salva este elemento na journey. Não confirma que o cartão apareceu no dispositivo. Depois que a journey estiver em execução, verifique Total entries e desistências nesta etapa, e verifique o cartão em um iPhone de teste, em um dispositivo de teste com Android 16 ou posterior, ou em ambos, dependendo das plataformas que você ativou.

Limitações

• Estatísticas do elemento: nesta etapa, verifique Total entries, a linha Delivery (modo de endereçamento) e as desistências (No recipient for the card, Live Activity send failed). Use No recipient for the card para ver que o envio de mensagens não encontrou nenhum dispositivo para as plataformas ativadas naquele modo, não que o dispositivo não tinha um token de Live Activity. Esta etapa não relata se o dispositivo mostrou o cartão ou se o usuário o abriu.
• O som não é garantido em cada atualização: o iOS limita a taxa de alertas de Live Activity por conta própria. Uma atualização idêntica pode tocar um som uma vez e chegar em silêncio na próxima.
• Muitas ações Start seguidas durante os testes: se você enviar cerca de dez ações Start para a mesma pessoa em um curto período de tempo (por exemplo, ao testar a journey), a Apple pode parar de mostrar novos cartões e não retornar um erro. Na journey, a pessoa ainda pode parecer entregue. Deixe um intervalo entre as execuções de teste.