Configuração Modal Genérica (CMS VTEX)

Visão geral

Este artigo orienta a criação e configuração do componente Modal Genérica no Headless CMS da VTEX. Use este guia para configurar título, descrição, imagem, botão de ação, destino e regras de aparição do modal no aplicativo.

Antes de começar

Tenha acesso ao menu Headless CMS.
Confirme se você possui permissão para criar, editar, salvar e publicar documentos no CMS.
Defina previamente o objetivo do modal, como ativar notificações, direcionar para uma coleção, abrir uma página de produto ou exibir uma mensagem informativa.

Passo a passo

1. Crie o componente

Acesse o menu "Headless CMS" e selecione a opção "Criar documento". Nele será exibida a opção de "Modal Genérica".

Selecione esta opção e prossiga para o próximo passo.

2. Configure os campos do modal

Ao acessar o componente criado, altere para a aba "Settings" e siga as orientações abaixo para o correto preenchimento dos campos:

Campo	Descrição
Título	Campo obrigatório. É o cabeçalho principal exibido no modal. O texto é renderizado centralizado e limitado a 2 linhas. Caso ultrapasse esse limite, o conteúdo é cortado com reticências. Recomenda-se textos curtos e objetivos.
Descrição	Campo opcional. Corpo de texto do modal, suportando formatação rica (negrito, itálico, listas) através do editor de texto. Utilize para inserir o conteúdo explicativo ou informativo do modal.
Imagem	Campo opcional. Imagem de destaque exibida no corpo do modal, acima do título e da descrição. Só é renderizada se uma imagem for de fato enviada. Caso o campo esteja vazio, nenhum espaço é reservado para ela. Arraste e solte um arquivo ou clique para selecionar. Recomenda-se imagens leves e bem proporcionadas para telas de celular.
Texto do botão	Campo obrigatório. Define o rótulo do botão de chamada para ação (CTA) principal do modal. Utilize textos de ação claros, como "Ativar", "Ver Coleção" ou "Entendi".
Selecionar Ação do Botão	Campo obrigatório. Define o comportamento executado ao tocar no botão principal. As opções disponíveis são: activateNotifications: Solicita ao usuário a permissão do sistema operacional para receber notificações push. O modal só será exibido se o usuário ainda não tiver concedido essa permissão e se as configurações globais de notificação do aplicativo permitirem essa abordagem. Ao clicar no botão, o app dispara o fluxo nativo de solicitação de permissão. destination: Redireciona o usuário para uma tela específica dentro ou fora do aplicativo. Ao selecionar esta opção, é obrigatório preencher também os campos Selecionar tipo de destino e ID relacionado ao tipo de destino.
Selecionar Tipo de Destino	Campo opcional, mas obrigatório quando a ação do botão for destination. Define a categoria de redirecionamento. As opções disponíveis são: Collection: Abre a vitrine de produtos (PLP) filtrada por uma coleção da VTEX. No campo ID relacionado ao tipo de destino, informe o ID numérico da coleção (ex: 150). Category: Abre a vitrine de produtos filtrada por uma categoria da VTEX. No campo ID relacionado ao tipo de destino, informe o ID numérico ou o caminho da categoria (ex: 10 ou 10/12). Product: Abre diretamente a Página de Detalhes do Produto (PDP). No campo ID relacionado ao tipo de destino, informe o ID do produto na VTEX (ex: 200456). Search: Abre a tela de busca do aplicativo já executando uma pesquisa. No campo ID relacionado ao tipo de destino, informe o termo de busca textual (ex: casaco de couro). Webview: Abre uma página web de forma integrada dentro do aplicativo. No campo ID relacionado ao tipo de destino, informe a URL completa (ex: https://meusite.com/regulamento ). Link: Abre uma URL no navegador externo do celular ou processa um Deep Link interno do app. No campo ID relacionado ao tipo de destino, informe a URL completa ou o Deep Link (ex: https://google.com ).
ID Relacionado ao Tipo de Destino	Campo opcional, mas obrigatório quando a ação do botão for destination. O conteúdo a ser preenchido varia conforme o Tipo de Destino selecionado, conforme descrito acima.
Selecionar Aparição	Campo obrigatório. Controla a política e a frequência com que o modal será exibido para o usuário. As opções disponíveis são: firstSession: O modal é exibido apenas na primeira sessão detectada do usuário no aplicativo. Não volta a aparecer nas sessões seguintes. orderFinished: O modal é exibido após a conclusão de um pedido pelo usuário. inactive: O modal é desativado e não é mais exibido. periodic: O modal é exibido de forma recorrente, respeitando um intervalo de tempo configurável. O intervalo é definido no campo Período de Aparição (ms). O aplicativo registra localmente no celular do usuário a data e hora da última exibição, usando o identificador único do modal para esse controle. A reexibição só ocorre após o tempo configurado ter decorrido.
Período de Aparição (ms)	Campo opcional. Utilizado exclusivamente quando a aparição for configurada como periodic. O valor deve ser informado em milissegundos. Exemplos comuns: 1 dia: 86400000 3 dias: 259200000 7 dias: 604800000 30 dias: 2592000000 Se o campo for deixado em branco, o sistema assume o valor padrão de 7 dias (604.800.000 ms).

Finalização

Após a criação e configuração do componente, é necessário salvá-lo e publicá-lo para que ele fique disponível e seja exibido no aplicativo.

Perguntas frequentes

O campo Imagem é obrigatório?

Não. A imagem é opcional. Se nenhuma imagem for enviada, o modal será exibido sem reservar espaço para esse conteúdo.

Quando devo usar a ação activateNotifications?

Use essa ação quando o objetivo do modal for solicitar ao usuário a permissão do sistema operacional para receber notificações push. O modal só será exibido se o usuário ainda não tiver concedido a permissão e se as configurações globais do aplicativo permitirem esse fluxo.

Quando devo usar a ação destination?

Use a ação destination quando o botão principal precisar direcionar o usuário para uma tela específica, como coleção, categoria, produto, busca, webview, URL externa ou deep link. Nesse caso, também é necessário preencher o tipo de destino e o ID relacionado.

O que preencher no campo ID Relacionado ao Tipo de Destino?

O valor depende do tipo de destino selecionado. Para coleção, informe o ID da coleção; para categoria, informe o ID ou caminho da categoria; para produto, informe o ID do produto; para busca, informe o termo pesquisado; e para webview ou link, informe a URL completa ou deep link.

O que acontece se eu configurar a aparição como periodic?

O modal passa a ser exibido de forma recorrente, respeitando o intervalo configurado em milissegundos no campo Período de Aparição. O aplicativo registra localmente no celular do usuário a última exibição e só mostra o modal novamente após o período definido.

Qual é o período padrão quando o campo Período de Aparição fica em branco?

Se a aparição estiver configurada como periodic e o campo Período de Aparição não for preenchido, o sistema assume o valor padrão de 7 dias, equivalente a 604.800.000 ms.

Preciso salvar e publicar o componente?

Sim. Após configurar o componente, é necessário salvar e publicar o documento para que o modal fique disponível e possa ser exibido no aplicativo.