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 produto ao qual você está fazendo referência. Este é o ID do produto sincronizado do seu próprio catálogo de produtos. Observação: essa busca é especificamente pelo ID do produto, e não pelo SKU.

Incluir unpublished="cancel" vai garantir que você não envie sua mensagem caso o item referenciado seja despublicado. Esse argumento é opcional.

• Se algum item mencionado na sua mensagem não estiver publicado no seu catálogo no momento da consulta, a mensagem inteira será ignorada.
• Para uma determinada mensagem de fluxo, você pode navegar até Análises > Atividade do destinatário > Outros e ver uma lista intitulada Ignorado: item de catálogo indisponível. Essa lista inclui todos os perfis que foram ignorados porque um item apresentado na mensagem estava fora de estoque ou indisponível 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 a seguir a um bloco de texto em um modelo de teste e atualize itemID com o ID do produto de um dos produtos atuais do 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, pode especificar de qual catálogo quer extrair usando a tag {{catalog id}}. Por exemplo, você pode ter um catálogo sincronizado por uma integração do Klaviyo, como a Shopify, um catálogo sincronizado via API ou um feed de catálogo personalizado. Os detalhes da tag podem variar de acordo com sua integração. No exemplo a seguir, vários catálogos são sincronizados com a mesma conta do Klaviyo, e queremos extrair a descrição de um produto específico contido em um catálogo de API.

Primeiro, encontre o ID do catálogo:

1. No Klaviyo, acesse Conteúdo > Produtos.
2. Selecione o catálogo que você quer usar no menu suspenso 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 %}

Filtragem por localidade

Catálogos com reconhecimento de localidade, como o catálogo da Shopify no Klaviyo, podem ser pesquisados por localidade. O idioma e a região da localidade podem ser referenciados com o código de país e idioma de duas letras usando os padrões ISO 3166 e 639. Se não for possível encontrar um produto localizado, serão usadas as informações padrão do produto.

{% 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ções personalizada e preferir não enviar todos os detalhes do produto que precisam entrar em uma mensagem. Por exemplo, em uma mensagem de carrinho abandonado, envie apenas os IDs de produto de todos os itens abandonados, e a Klaviyo pode pesquisar cada um para inserir 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 ao passar apenas o ID do produto para a Klaviyo e, em seguida, pesquisar 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 %}

Neste bloco {% catalog %}, adicione tags de modelo para os dados que você gostaria de preencher para cada item (ou seja, título, imagem etc.)

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:

A sintaxe do bloco {% catalog %} a seguir extrairia a imagem do item, o título do item e a descrição do item do seu catálogo, para cada item no evento:

{% 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

{% 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

{% 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