Referência da tag de pesquisa no catálogo

O que você vai aprender

Saiba como usar a tag de catálogo, que permite que você faça referência a informações específicas de produtos do seu catálogo nos seus e-mails, SMS e mensagens push. Isso é útil quando você quer criar recomendações de produtos personalizadas ou cruzar informações de produtos. Por exemplo, se você estiver usando seu próprio mecanismo de recomendação, poderá enviar suas próprias recomendações de produtos como dados de evento ou de perfil para a Klaviyo e, em seguida, usar esses dados em modelos.

A tag {% catalog %}

A tag {% catalog %} usa a seguinte sintaxe:

{% catalog "itemID" unpublished="cancel" %}
...
{% endcatalog %}

Substitua itemID pelo ID do item exibido na página de detalhes do produto no Klaviyo. O valor deve corresponder ao ID do item armazenado no seu catálogo; use um SKU somente se ele também for o ID do item no catálogo. Mantenha aspas em volta de um ID literal. Ao usar uma variável de evento ou de perfil, deixe a variável sem aspas, como mostrado nos exemplos abaixo.

Incluir unpublished="cancel" impede que a mensagem seja enviada se o item referenciado estiver não publicado no seu catálogo da Klaviyo. Esse argumento é opcional. Sem isso, um item não publicado ainda pode aparecer na mensagem.

• Se qualquer consulta usando unpublished="cancel" encontrar um item não publicado no momento da consulta, a mensagem inteira será ignorada para esse destinatário.
• Para uma mensagem de fluxo, abra as análises e selecione Atividade do destinatário > Ignorado. No menu suspenso Tipo, selecione Ignorado: item de catálogo indisponível. Esta lista inclui perfis cujas mensagens foram ignoradas porque não foi possível encontrar um item referenciado ou porque um item não publicado foi pesquisado com unpublished="cancel". Um item pode ser despublicado porque está fora de estoque ou indisponível no seu catálogo por outro motivo.

Ao usar este recurso, entre as tags de abertura e fechamento do catálogo, você pode referenciar dados específicos do item associado ao itemID no catálogo de produtos do Klaviyo.

Os seguintes dados estão disponíveis para referência dentro de um bloco {% catalog %}.

Pode haver campos de dados adicionais disponíveis que são considerados metadados. Para referenciar uma dessas propriedades adicionais do item, você pode usar a sintaxe de variável: {{ catalog_item.metadata.color }}. Nesse caso, a variável vai trazer o valor de "cor" associado ao item armazenado nos metadados do item.

Para acessar uma prévia de todos os detalhes disponíveis armazenados em um item — incluindo todos os metadados — adicione o snippet abaixo a um bloco de texto em um modelo de teste e atualize itemID com o ID do item de um dos produtos atuais no seu catálogo.

{% catalog "itemID" %}
{{ catalog_item }}
{% endcatalog %}

Em seguida, visualize a mensagem. Essa visualização fornece uma versão bruta de todos os dados disponíveis dos seus produtos.

Filtragem por ID do catálogo

Se você tiver vários catálogos, use o argumento catalog_id na tag de abertura {% catalog %} para especificar um catálogo. Você também deve incluir integration, com ambos os valores entre aspas. Por exemplo, você pode ter um catálogo sincronizado por meio de uma integração da Klaviyo, como a Shopify, um catálogo sincronizado via API ou um feed de catálogo personalizado. O valor da integração deve corresponder à origem do catálogo. O exemplo abaixo usa integration="api" para extrair uma descrição do produto de um catálogo de API.

Primeiro, encontre o ID do catálogo:

1. No Klaviyo, acesse Conteúdo > Produtos.
2. Use o filtro Opções de catálogo para selecionar o catálogo que você quer usar. A seleção padrão é Todos os catálogos.

3. Copie o ID do catálogo da URL.
   

Em seguida, encontre o ID do item:

1. Depois de selecionar o catálogo, selecione o produto que você quer usar no catálogo.
2. Na página de detalhes do produto, você verá o ID do item.
   

Para o exemplo acima, o código ficaria assim:

{% catalog "SAMPLE-DATA-ITEM-15" integration="api" catalog_id="1060935"%} {{ catalog_item.description }}{% endcatalog %}

Substitua o ID do item de exemplo e o ID do catálogo pelos seus próprios valores; em seguida, visualize a prévia da mensagem e verifique se ela mostra os detalhes do produto esperados. Se a pesquisa não encontrar uma correspondência no catálogo que você especificar, ela pode recorrer a outro catálogo na sua conta.

Filtragem por localidade

Se o seu catálogo contiver dados de produto localizados, como um catálogo da Shopify com dados localizados sincronizados com a Klaviyo, você poderá pesquisar um produto por localidade. Inclua o idioma e a região, usando códigos de idioma e país de 2 letras das normas ISO 639 e ISO 3166, respectivamente. Por exemplo, language='fr' e region='CA' solicitam dados de produto em francês para o Canadá. Se um produto localizado não puder ser encontrado, as informações padrão do produto serão usadas.

{% catalog "SAMPLE-DATA-ITEM-15" integration="api" catalog_id="1060935" language='fr' region='CA' %} {{ catalog_item.description }}{% endcatalog %}

Procure um ID de item enviado com um evento

O uso de uma busca no catálogo com um evento é mais comum nos seguintes cenários:

• Se você estiver usando integrações personalizadas em que as recomendações de produtos são passadas junto com um evento para serem exibidas na mensagem. Por exemplo, uma mensagem de carrinho abandonado em que recomendações exclusivas são geradas com base nos itens visualizados. Em vez de preencher na mensagem o único item que um cliente visualizou, você pode gerar e preencher um conjunto de itens recomendados com base nesse item visualizado. É necessário enviar um conjunto de IDs de produto para a Klaviyo junto com o evento.
• Se você estiver usando uma integração personalizada e preferir não enviar todos os detalhes do produto que precisam estar em uma mensagem. Por exemplo, com uma mensagem de carrinho abandonado, envie apenas os IDs de produto de todos os itens abandonados, e a Klaviyo pode procurar cada um para extrair todos os detalhes relevantes. Não é necessário que todo evento contenha nome do produto, preço, imagem etc., já que tudo isso pode ser preenchido apenas enviando o ID do produto para a Klaviyo e, em seguida, consultando as informações no seu catálogo de produtos da Klaviyo.

Ao usar uma tag {% catalog %} com um evento, a busca se baseia no Item ID do item do catálogo (que será o Product ID ou o SKU, dependendo das integrações).

Para um evento em que o valor de identificação enviado é o ID do item, as tags de consulta aparecerão assim:

{% catalog event.ItemID %}
...
{% endcatalog %}

Dentro deste bloco {% catalog %}, adicione tags de modelo para os dados que você gostaria de preencher sobre cada item (por exemplo, título ou imagem).

Por exemplo, usando os dados do item de catálogo de exemplo abaixo, podemos criar um bloco {% catalog %} que faz referência a informações importantes do produto:

Dados do item do catálogo:

{
  "description": "Standard issue for all Klaviyos. This t-shirt has the Klaviyo logo on the front and mark diagram on the back.",
  "url": "https://klaviyogear.myshopify.com/collections/klaviyo-classics/products/short-sleeve-t-shirt-1",
  "title": "Classic Klaviyo T-Shirt",
  "featured_image": {
    "full": {
      "src": "https://www.klaviyo.com/media/images/examples/products/klaviyo-tshirt-full.png"
    },
    "thumbnail": {
      "src": "https://www.klaviyo.com/media/images/examples/products/klaviyo-tshirt-thumbnail.png"
    }
  },
  "id": "KLAVIYO-TSHIRT",
  "metadata": {
    "Color": "Grey",
    "Design": "Standard"
  }
}

Sintaxe do bloco do modelo:

O exemplo de HTML a seguir insere a imagem, o título e a descrição do item para cada item em event.Items. Ele pressupõe que cada item tenha um valor de SKU que corresponda ao ID do item no seu catálogo da Klaviyo. Se o seu evento usar uma propriedade diferente para o ID do item do catálogo, substitua item.SKU por essa propriedade. Use os exemplos de HTML em um e-mail; para SMS ou push, use as tags do catálogo com campos de texto, em vez de marcação HTML.

{% for item in event.Items %}
	{% catalog item.SKU %}
 		<img src="{{ catalog_item.featured_image.full.src }}"/>
 		{{ catalog_item.title }}
 		{{ catalog_item.description }}
 	{% endcatalog %}
{% endfor %}

Se a pesquisa não conseguir encontrar o item que está procurando, a mensagem será ignorada e não será enviada.

Procure um ID do item como uma propriedade personalizada

Se você estiver usando seu próprio mecanismo de recomendação, pode passar os IDs de itens recomendados para perfis no Klaviyo como uma Propriedades do perfil personalizada. Usando uma tag {% catalog %}, você pode fazer referência a informações de qualquer um desses produtos ao enviar mensagens para esse cliente.

Se a pesquisa não conseguir encontrar o item que está procurando, a mensagem será ignorada e não será enviada.

Sintaxe para vários IDs de item armazenados em uma única propriedade

Armazene Recommended Products como uma lista de IDs de itens, como ["KLAVIYO-TSHIRT", "KLAVIYO-HAT"]. Substitua esses IDs de exemplo por IDs do seu catálogo e substitua o nome da propriedade no código se o seu for diferente.

{% for item in person|lookup:'Recommended Products' %}{% catalog item %} 

<img src="{{ catalog_item.featured_image.thumbnail.src }}" style="display: inline-block; border: none" width="150px" />

<p>{{ catalog_item.title }} {% endcatalog %}</p>

{% endfor %}

Sintaxe para um único ID de item em uma Propriedades do perfil

Armazene um único ID de item como um valor de texto em Recommended Products, como KLAVIYO-TSHIRT. Use o nome da propriedade e o ID do item da sua própria conta.

{% catalog person|lookup:"Recommended Products" %} 

<img style="display: inline-block; border: none;" src="{{ catalog_item.featured_image.thumbnail.src }}" width="150px"/>

  <p>{{ catalog_item.title }} {% endcatalog %}</p>

Sobre a tag has_category

Use a tag has_category para determinar se um item no seu catálogo faz parte de uma categoria específica. Ela deve ser usada dentro de uma tag de pesquisa de catálogo para um item específico.

Use o código de exemplo abaixo para usar esta tag, substituindo itemID por um ID de produto do seu catálogo e category_name por todo ou parte de um nome de categoria.

{% catalog "itemID" %}
{{ catalog_item.title }}
{% has_category catalog_item "category_name" as in_category %}
{% if in_category %}
I am on sale!
{% else %}
{% endif %}
{% endcatalog %}

Este exemplo exibe o título do produto e, em seguida, verifica se o produto está em uma categoria, category_name. Se isso for avaliado como true, a mensagem "Estou em promoção!" aparecerá após o título do produto.

Recursos adicionais