FAQ CMS — Guia do Headless CMS VTEX para App Commerce
Documentação passo a passo de como operar o CMS do App: configurar o projeto, criar a Home, página de Categorias, Landing Pages e componentes (banner, prateleira, scroll infinito, blog).
Configurações Iniciais
Os primeiros passos para habilitar e estruturar o CMS do App na sua loja VTEX — do acesso e permissões à criação das páginas obrigatórias (Home, Categorias) e Landing Pages.
O CMS (Content Management System) serve para configurar o conteúdo exibido no app — Home, banners, vitrines/prateleiras e landing pages — consumindo dados e estruturas já existentes na VTEX.
O que o CMS controla
Conteúdo da Home do app.
Landing pages / campanhas (ex.: Páscoa, Sale, Natal).
Banners (com ou sem ação).
Prateleiras de produtos (coleções / categorias).
Scroll infinito de produtos.
Integração de blog via URL (WordPress).
O que o CMS NÃO controla
Funcionalidades do app (busca, PDP, carrinho/checkout) — já implementadas.
Mudanças estruturais/visuais que exigem código (ex.: header/logo).
O CMS fica dentro da área de administração da VTEX, em Storefront → Headless CMS.
Menu Storefront da VTEX com a opção Headless CMS destacada
É preciso criar e configurar um projeto no Headless CMS, vinculando as URLs de Content-Types que habilitam os tipos de página e os componentes.
1
Acesse o Admin da VTEX da loja.
2
Vá em Storefront → Headless.
3
Crie um novo projeto para o app (ex.: “app”).
Tela do Headless CMS com botão para criar um novo projeto
4
Abra o projeto recém-criado.
Projeto aberto no Headless CMS pronto para configuração
5
Na tela de criação do projeto, cole as duas URLs fornecidas pelo time técnico nos campos sobre Content-Types: (1) URL de Sessões/Componentes (blocos suportados); (2) URL de Tipos de Conteúdo (Home, Categorias, Landing Page).
6
Salve as configurações clicando no botão “Criar”. Confirme que o projeto aparece como criado e que as opções de criação de página estão disponíveis.
Configuração do projeto com URLs de Content-Types preenchidas
7
A partir dessa configuração, o projeto deve exibir as páginas e componentes que precisam/podem ser configuradas.
Crie uma página do tipo Home (apenas 1 por projeto) e adicione os componentes iniciais, como Banners e Prateleiras.
1
Dentro do projeto, clique em “Criar novo documento”.
2
Selecione o tipo Home.
Lista de tipos de página disponíveis, com Home em destaque
3
Nomeie a página como “Home” — essa é uma orientação obrigatória para o correto funcionamento.
Campo de nome da página preenchido como Home
4
Clique no “+” para adicionar componentes (ex.: Banners, Prateleiras).
Botão de adicionar componente na página Home do CMS
5
Configure cada componente adicionado (detalhes de cada componente nas seções seguintes). Salve o rascunho.
Componente Banners sendo selecionado para a Home
6
Clique em Publicar.
Botão Publicar exibido ao salvar a Home
7
Confirme que a Home aparece na hierarquia de páginas do projeto.
Hierarquia de páginas do app com a Home já publicada
Crie a página do tipo Categorias (apenas 1 por projeto) e configure a lista de categorias/subcategorias, com ícones e ações quando necessário.
1
Dentro do projeto, clique em Criar novo documento.
2
Selecione o tipo Categorias.
Seleção do tipo Categorias ao criar uma nova página
3
Clique no “+” e adicione o componente de lista de categorias.
Adição do componente lista de categorias
4
Preencha as informações do componente escolhido, clique em Salvar e depois em Publicar. A página precisa ser nomeada como “Categorias”.
Formulário do componente de categorias com botões Salvar e Publicar
5
Cadastre as categorias (título) e, se necessário, subcategorias.
Cadastro de categorias e subcategorias
6
Adicione subcategorias vinculadas à categoria pai.
Subcategorias aninhadas no CMS
7
Opcional: adicione ícone para cada categoria/subcategoria.
8
Opcional: defina a ação (ex.: abrir vitrine, abrir link, campanha Black Friday etc.).
Configuração de ações (abrir vitrine, abrir link) em uma categoria
Árvore de Categorias e Ações Disponíveis
A árvore de categorias no CMS reflete a estrutura cadastrada na VTEX. Ao configurar as categorias, é possível organizar a navegação em níveis hierárquicos com subcategorias (categorias filhas) vinculadas a cada categoria pai. Ações disponíveis:
Abrir vitrine — exibe os produtos da categoria no formato padrão.
Abrir link — redireciona para uma URL específica.
Campanha — direciona para uma página de campanha configurada.
Landing Pages podem ser criadas em quantidade ilimitada e servem para campanhas (ex.: Sale, promoções, datas especiais, coleções/lançamentos) e páginas institucionais (política de troca, quem somos, regulamentos).
1
Dentro do projeto, clique em Criar novo documento.
2
Selecione o tipo Landing Page.
Seleção do tipo Landing Page ao criar uma nova página
3
Defina um nome identificável (ex.: “Sale”, “politica-troca”, “quem-somos”).
Campo de nome da Landing Page preenchido
4
Adicione componentes no topo conforme objetivo (ex.: Banner promocional).
Componente de topo sendo adicionado à Landing Page
5
Configure o banner promocional principal da campanha.
Banner principal da Landing Page configurado
6
Adicione prateleira de produtos e/ou scroll infinito quando a página exigir vitrine.
7
Para páginas institucionais, use componente de texto livre/HTML quando disponível.
Componente de texto livre em Landing Page institucional
8
Use o componente HTML para conteúdo mais elaborado.
Componente HTML em Landing Page
9
Salvar e Publicar.
Landing Page finalizada com botões Salvar e Publicar
Configurações Avançadas
Como configurar em detalhes cada componente disponível no CMS (Banner, Prateleira, Scroll Infinito e Blog), agendamento, deep links, diretrizes mobile e como resolver problemas comuns durante a operação.
O banner permite subir imagens e, opcionalmente, definir uma ação ao clicar — abrindo um produto, categoria, landing page ou link externo.
1
Abra o documento (Home ou Landing Page) onde deseja inserir o banner.
2
Clique no botão “+” (adicionar componente).
Botão de adicionar componente no documento
3
Selecione o componente “Banner”.
Seleção do componente Banner na lista
4
Dentro do componente, clique em “Nova mídia” para adicionar imagens ou vídeos.
Opção Nova mídia para adicionar imagens ao banner
5
Escolha a imagem do banner.
Seletor de imagem do banner
6
Defina a ação do banner (opcional): abrir categoria, busca, produto, coleção, link externo etc. Veja a tabela de ações abaixo.
7
Configure as opções adicionais conforme necessário.
8
Salve o rascunho.
9
Clique em “Publicar”.
Publicação do banner aplicada no app
Proporção de Imagem (Aspect Ratio)
Ao cadastrar um banner, é necessário definir a proporção da imagem. A proporção é representada por uma divisão (ex.: 2:1, 4:3, 16:9). Todos os banners do mesmo bloco devem usar a mesma proporção para manter consistência visual no carrossel.
Se você não sabe a proporção exata, pode usar a própria resolução da imagem como proporção (ex.: 732x497).
Todos os banners do mesmo bloco devem ter a mesma proporção para manter a consistência visual do carrossel.
Tamanho recomendado das imagens
Use as dimensões abaixo como referência. A largura recomendada é de 1080 px para garantir qualidade em telas de alta resolução (retina).
Proporção
Dimensão recomendada
Uso ideal
2:1
1080 × 540 px
Carrossel principal da Home — banner horizontal padrão
4:3
1080 × 810 px
Banners levemente retangulares
16:9
1080 × 607 px
Formato widescreen
1:1
1080 × 1080 px
Banners quadrados
3:4
810 × 1080 px
Banners verticais / formato retrato
Como usar vídeos no banner
Além de imagens, é possível adicionar vídeos ao banner. Para uma boa experiência, siga estas orientações:
Ao clicar em “Nova mídia”, selecione a opção de vídeo em vez de imagem.
Obrigatório: adicione uma imagem de capa (thumbnail). Sem ela, o banner exibirá uma tela escura enquanto o vídeo carrega, prejudicando a experiência.
Mantenha o arquivo leve — máximo de 2 MB. Vídeos pesados comprometem a performance do app em conexões móveis.
Formato recomendado: MP4.
O que informar em cada tipo de ação
Banners podem ter links configurados para direcionar o usuário ao tocar. A tabela abaixo explica o que preencher em cada campo:
Tipo de ação
O que acontece
O que informar no campo
Produto
Abre a página de detalhe do produto no app
ID do produto ou slug na VTEX (ex.: 123456 ou mochila-preta)
Categoria
Abre a vitrine da categoria
Caminho/path da categoria na VTEX (ex.: /roupas/masculino/calcados) — consulte em Catálogo → Categorias
Coleção
Abre a vitrine da coleção
ID numérico da coleção na VTEX (ex.: 147) — consulte em Catálogo → Coleções
Landing Page
Abre uma Landing Page criada no CMS
Nome/slug exato da Landing Page no CMS (ex.: black-friday)
URL externa
Abre link no navegador do dispositivo
URL completa com protocolo (ex.: https://seusite.com.br/pagina)
Sem ação
Banner apenas visual, sem redirecionamento
Deixe o campo em branco
Agendamento de Banners
É possível definir uma data de início e uma data de fim para exibição do banner:
No campo de agendamento, defina a data de início — o banner ficará cadastrado no CMS, mas só será exibido no app a partir dessa data.
Defina a data de fim — o banner deixará de ser exibido automaticamente nessa data.
A prateleira exibe produtos com base em uma coleção/categoria existente na VTEX. É necessário informar o ID correto da coleção ou o caminho/path da categoria (ex.: “/roupas/masculino/calcados”).
1
Acesse a página desejada no CMS.
2
Clique no botão “+” e selecione “Prateleira de produto”.
Adição do componente Prateleira de produto
3
Defina o nome/título que aparecerá no app acima da prateleira.
4
Informe a origem dos produtos: Coleção ou Categoria.
5
Preencha o ID (coleção) ou caminho/path (categoria) correspondente. Veja como localizar cada um abaixo.
Configuração de ID de coleção ou caminho de categoria na prateleira
6
Salve.
7
Clique em “Publicar”.
Coleções vs Categorias
As prateleiras de produtos podem ser alimentadas de duas formas:
Por Coleção: coleções são mais flexíveis porque permitem agrupar produtos de diferentes categorias em uma única prateleira. Ideal para campanhas temáticas ou seleções curadas.
Por Categoria: filtrar por categoria mostra todos os produtos daquela categoria. É uma opção mais direta, mas menos flexível que as coleções.
Como localizar o ID de Coleção ou o Caminho de Categoria na VTEX
O que preencher no campo varia conforme a origem escolhida:
Origem
Resultado esperado
Onde encontrar na VTEX
Exemplo
Coleção
Sempre um ID numérico
Admin VTEX → Catálogo → Coleções → clique na coleção → anote o ID exibido
147
Categoria
Sempre um caminho/path
Admin VTEX → Catálogo → Categorias → clique na categoria → copie o caminho exibido
/roupas/masculino/calcados
Ordenação e Quantidade
Ao configurar uma prateleira, é possível ajustar:
Quantidade de produtos: defina quantos produtos serão exibidos na prateleira.
Ordem de exibição: configure a ordenação dos produtos (ex.: mais vendidos, mais recentes, preço, etc.).
O CMS permite agendar a exibição de componentes (banners, blocos de conteúdo) com data de início e data de fim. Dessa forma, o conteúdo é cadastrado com antecedência e publicado automaticamente no período programado.
1
Ao criar ou editar um componente (ex.: banner), localize o campo de agendamento.
2
No campo “Data de fim”, defina quando o conteúdo deixará de ser exibido.
3
Salve as alterações. O conteúdo ficará cadastrado no CMS, mas só aparecerá no app dentro do período programado.
4
Após a campanha, remova manualmente o conteúdo expirado para manter o CMS organizado.
Deep links são URLs especiais que direcionam o usuário para uma página ou seção específica dentro do app, em vez de abrir o navegador. No CMS, os deep links podem ser configurados em banners e outros componentes.
Destinos disponíveis para deep links
Destino
O que abre no app
Página de produto
Página de detalhe de um produto específico dentro do app
Categoria
Vitrine de uma categoria específica
Coleção
Vitrine de uma coleção de produtos
Landing Page
Uma landing page configurada no CMS
URL externa
Abre o link no navegador do dispositivo (fora do app)
Onde configurar deep links
Os deep links podem ser configurados nos seguintes componentes do CMS:
Banners — ao configurar o link de destino de um banner (campo de ação).
Outros componentes — em qualquer campo de link disponível nos blocos do CMS.
Sim. Todo conteúdo publicado no CMS é refletido automaticamente no app. Os usuários não precisam atualizar o app nas lojas (App Store / Google Play) para ver novos banners, prateleiras ou landing pages.
Entendendo os dois tipos de atualização
Tipo de alteração
Requer publicação no console da Eitri?
Como visualizar
Novo banner, prateleira ou landing page publicados no CMS
Não
Feche e abra o app. Pode levar alguns minutos para o cache atualizar.
Novas funcionalidades, correções de bugs, mudanças no layout
Sim (via console da Eitri)
A publicação no console da Eitri envia a nova versão direto para o app — sem passar pela App Store / Play Store. Feche e abra o app para receber a atualização.
O scroll infinito exibe uma lista contínua de produtos que carrega mais itens à medida que o usuário rola a tela.
1
Abra o documento (Home ou Landing Page) onde deseja inserir o scroll infinito.
2
Clique em “+” e selecione “Scroll infinito de produtos”.
Adição do componente Scroll infinito de produtos
3
Configure a origem dos produtos (coleção ou categoria).
4
Salvar e Publicar.
Publicação do componente Scroll infinito
O CMS não possui um editor de blog nativo, mas permite integrar conteúdo de blog externo (ex.: WordPress) via URL diretamente no app.
1
Adicione o componente Blog na página desejada.
2
Defina o título que aparecerá no app.
3
Informe o número de posts a exibir.
4
Cole a URL do blog (feed RSS ou página).
Configuração de URL, título e limite de posts do Blog
5
Salvar e Publicar.
Diferente dos sites, apps mobile seguem diretrizes do Google (Android) e da Apple (iOS) que desaconselham o uso de modais e pop-ups, pois interrompem a navegação, prejudicam a usabilidade em telas menores e podem penalizar o app nas lojas.
Os cenários abaixo cobrem a maior parte dos casos de suporte: publicação, componentes ausentes, banners, prateleiras, páginas e agendamento.
