Filtrar itens de catálogo por intervalo de datas

Este exemplo mostra como um marketplace fictício de ingressos usa seleções de catálogo e expressões de data em Liquid para enviar por e-mail aos consumidores apenas eventos que ocorrerão nos próximos sete dias a partir do momento do envio. Você cria uma seleção com filtros de tempo contínuos e, em seguida, renderiza os itens correspondentes do catálogo em uma Campaign ou mensagem de Canvas.

Sobre este exemplo

MovieCanon, um marketplace fictício de ingressos, usa esse padrão para garantir que as Campaigns de e-mail listem apenas shows e concertos relevantes no tempo.

O padrão usa dois recursos da Braze juntos:

• Uma seleção de catálogo com filtros de campo time cujos valores são snippets Liquid que calculam uma janela de tempo contínua no momento do envio
• A tag Liquid {% catalog_selection_items %} no corpo da mensagem para renderizar as linhas correspondentes do catálogo

Considerações

• Crie um campo time no catálogo para a coluna de data/hora que você deseja filtrar, não um campo de string. Armazene os valores no formato ISO 8601, como 2026-06-20T19:30:00Z. Para os tipos compatíveis, consulte Tipos de dados compatíveis.
• Os operadores before e after usam comparações estritas. Eventos exatamente iguais a um timestamp limite podem ser excluídos. Use timestamps completos quando precisar que a janela comece no momento do envio. Valores somente de data YYYY-MM-DD são convertidos para meia-noite UTC naquele dia.
• O Liquid nos filtros de seleção é avaliado no momento do envio. A variável 'now' reflete quando a mensagem é renderizada, normalmente em UTC. Confirme se a janela resultante corresponde à sua intenção em diferentes fusos horários.
• Connected Content, Content Blocks, tags de catálogo e abort_message não são compatíveis com valores de filtro de seleção de catálogo. Se um filtro incluir uma tag não permitida, a seleção não retorna nenhum item sem gerar um erro.
• Você pode adicionar até 10 filtros por seleção e retornar até 50 itens. Ajuste a janela de sete dias alterando os segundos adicionados a 'now' (604800 = 7 dias multiplicados por 86400 segundos por dia).
• Os arrays de resultado de seleção de catálogo são indexados a partir de zero (items[0] é o primeiro item).
• Teste o Liquid dos filtros, o Liquid da mensagem e a lógica de interrupção fora do seu espaço de trabalho de produção antes de enviar para públicos de produção.

Configuração

Este exemplo assume um catálogo chamado live_events com os seguintes campos:

Se você ainda não tem um catálogo semelhante, crie um catálogo e faça upload ou sincronize seus dados de eventos primeiro.

Etapa 1: Criar a seleção de catálogo

1. Acesse Data Settings > Catalogs e selecione o catálogo live_events.
2. Abra a guia Selection e selecione Create Selection.
3. Nomeie a seleção como seven_day_window e adicione uma descrição opcional, como “Eventos que ocorrem nos próximos sete dias.”
4. Defina um Results limit para o número máximo de eventos a retornar (até 50).
5. Não salve ainda. Adicione os filtros de data nas próximas etapas.

Etapa 2: Adicionar o filtro de limite superior

Adicione um filtro no campo event_date_time:

No campo de valor do filtro, insira este snippet Liquid. Ele calcula um timestamp sete dias a partir do momento do envio:

1

{% assign seven_days = 'now' | date: '%s' | plus: 604800 %}{{ seven_days | date: "%Y-%m-%dT%H:%M:%SZ" }}

Isso define o limite superior da janela para que apenas eventos antes desse timestamp sejam incluídos.

Etapa 3: Adicionar o filtro de limite inferior

Adicione um segundo filtro no mesmo campo:

Insira este snippet Liquid para o limite inferior. Ele usa o horário atual de envio para que eventos que já começaram sejam excluídos:

1

{{ 'now' | date: "%Y-%m-%dT%H:%M:%SZ" }}

Juntos, os dois filtros retornam itens do catálogo em que event_date_time é posterior ao horário atual de envio e anterior a sete dias a partir do horário de envio. Selecione Create Selection para salvar.

Etapa 4: Referenciar a seleção em uma mensagem

Na sua Campaign ou mensagem de Canvas, insira o Liquid que busca itens da seleção. Você pode usar Add personalization (Catalog Items > Use a selection) ou colar a tag manualmente:

1
2
3
4
5
6
7
8

{% catalog_selection_items live_events seven_day_window %}
Here are some upcoming events:

{{ items[0].event_name }} — ${{ items[0].ticket_price }}
{{ items[0].city }} · {{ items[0].venue }}

{{ items[1].event_name }} — ${{ items[1].ticket_price }}
{{ items[1].city }} · {{ items[1].venue }}

Substitua os índices de array fixos por um loop se precisar renderizar um número variável de resultados.

Etapa 5: Lidar com resultados vazios

Quando nenhum item do catálogo corresponde à seleção, o array items fica vazio e o bloco com a tag não renderiza nada. Para pular o envio ou exibir um conteúdo de fallback, envolva a tag em uma condicional:

1
2
3
4
5
6
7

{% catalog_selection_items live_events seven_day_window %}
{% if items.size == 0 %}
{% abort_message('Catalog selection returned 0 items') %}
{% endif %}

Here are some upcoming events:
{{ items[0].event_name }}

Para saber mais, consulte Interrompendo mensagens.

Artigos relacionados

• Criar um catálogo
• Seleções
• Usando catálogos em Campaigns
• Filtro date do Liquid
• Biblioteca de casos de uso do Liquid