> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleep.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Shopify: Botão CTA e Produtos Similares
## Guia de Integração Shopify V2
Esta seção mostra como adicionar o Kleep AI Sizing à sua loja Shopify.
Siga nosso tutorial Tango para adicionar o botão Kleep à sua loja em temas da Online Store 2.0.
## Guia de Integração Shopify V1
## 1. Dimensionamento
Esta seção mostra como adicionar o Kleep AI Sizing ao código da sua loja Shopify.
Assista ao tutorial passo a passo do Tango para instalar o Kleep em uma loja Shopify V1.
### Passos
**Passo 1: Ativar o App Embed**
Certifique-se de que o aplicativo Kleep está ativado nos seus App embeds.
**Passo 2: Renderizar o trecho do botão**
Cole o código a seguir onde deseja que o Kleep apareça. Deve fazer parte do bloco `Product info` dentro da pasta `snippets`.
```jsx theme={null}
{% render 'kleep-button', cms: section.settings %}
```
**Passo 3: Criar o arquivo do trecho do botão**
Crie um novo arquivo chamado `kleep-button.liquid` dentro da pasta `snippets`. Coloque o seguinte conteúdo:
```jsx theme={null}
```
**Passo 4: Adicionar opções ao esquema de configurações**
Adicione as seguintes opções ao seu esquema de configurações no final da página:
```jsx theme={null}
{
"type": "header",
"content": "Button text",
"info": "If you enable this feature, the button text you enter will be replaced for all languages in your store"
},
{
"type": "checkbox",
"default": false,
"id": "custom_button_text_toggle",
"label": "Enable custom button text"
},
{
"type": "text",
"id": "custom_find_size_text",
"label": "Find my best size text",
"info": "What text will display instead of \"Find my best size\"?"
},
{
"type": "text",
"id": "custom_recommended_size_text",
"label": "Recommended size text",
"info": "What text will display instead of \"Recommended size\"?"
},
{
"type": "header",
"content": "Image"
},
{
"type": "url",
"id": "image_url",
"label": "Url Image"
},
{
"type": "range",
"id": "image_size",
"min": 0,
"max": 80,
"step": 2,
"unit": "px",
"label": "Image size (square)",
"default": 20
},
{
"type": "header",
"content": "CSS Styles"
},
{
"type": "checkbox",
"default": true,
"id": "default_font_family",
"label": "Font du thème",
"info": "Si coché, la variable css `--font-body-family` est utilisée"
},
{
"type": "font_picker",
"id": "font_family",
"label": "Font Family",
"default": "helvetica_n4"
},
{
"type": "select",
"id": "text_style",
"label": "Style texte",
"default": "normal",
"options": [
{
"label": "Normal",
"value": "normal"
},
{
"label": "Italic",
"value": "italic"
},
{
"label": "Oblique",
"value": "oblique"
}
]
},
{
"type": "select",
"id": "text_transform",
"label": "Texte transformation",
"default": "none",
"options": [
{
"label": "Normal",
"value": "none"
},
{
"label": "Capitalize",
"value": "capitalize"
},
{
"label": "Uppercase",
"value": "uppercase"
},
{
"label": "Lowercase",
"value": "lowercase"
}
]
},
{
"type": "select",
"id": "text_weight",
"label": "Poid texte",
"default": "400",
"options": [
{
"label": "100",
"value": "100"
},
{
"label": "200",
"value": "200"
},
{
"label": "300",
"value": "300"
},
{
"label": "400",
"value": "400"
},
{
"label": "500",
"value": "500"
},
{
"label": "600",
"value": "600"
},
{
"label": "700",
"value": "700"
},
{
"label": "800",
"value": "800"
},
{
"label": "900",
"value": "900"
}
]
},
{
"type": "range",
"id": "text_size",
"min": 2,
"max": 50,
"step": 2,
"unit": "px",
"label": "Taille police",
"default": 16
},
{
"type": "checkbox",
"id": "text_underline",
"label": "Texte soulignage",
"default": false
},
{
"type": "range",
"id": "text_underline_offset",
"min": 1,
"max": 20,
"step": 1,
"unit": "px",
"label": "Offset underline",
"default": 2
},
{
"type": "color",
"id": "text_color",
"label": "Couleur texte du bouton",
"default": "#ffffff"
},
{
"type": "color",
"id": "bg_color",
"label": "Couleur fond",
"default": "#000000"
},
{
"type": "color",
"id": "border_color",
"label": "Couleur bordures",
"default": "#000000"
},
{
"type": "range",
"id": "border_width",
"min": 0,
"max": 8,
"step": 1,
"unit": "px",
"label": "Épaisseur bordures",
"default": 0
},
{
"type": "header",
"content": "CSS Styles",
"info": "Espacements"
},
{
"type": "checkbox",
"id": "center",
"label": "Centrer le bouton",
"default": false,
"info": "Cela remplacera le 'Margin horizontal'"
},
{
"type": "range",
"id": "margin_y",
"min": 0,
"max": 80,
"step": 2,
"unit": "px",
"label": "Margin vertical",
"default": 0
},
{
"type": "range",
"id": "margin_x",
"min": 0,
"max": 80,
"step": 2,
"unit": "px",
"label": "Margin horizontal",
"default": 0
},
{
"type": "range",
"id": "padding_t",
"min": 0,
"max": 40,
"step": 2,
"unit": "px",
"label": "Padding top",
"default": 12
},
{
"type": "range",
"id": "padding_r",
"min": 0,
"max": 40,
"step": 2,
"unit": "px",
"label": "Padding right",
"default": 16
},
{
"type": "range",
"id": "padding_b",
"min": 0,
"max": 40,
"step": 2,
"unit": "px",
"label": "Padding bottom",
"default": 12
},
{
"type": "range",
"id": "padding_l",
"min": 0,
"max": 40,
"step": 2,
"unit": "px",
"label": "Padding left",
"default": 16
},
{
"type": "range",
"id": "border_radius",
"min": 0,
"max": 40,
"step": 2,
"unit": "px",
"label": "Bordures arrondies",
"default": 0
}
```
Para adicionar seus próprios estilos CSS:
* Para alterar a aparência (cores, espaçamento, fontes, etc.), cole seu CSS na caixa **"Input custom CSS styles"** nas configurações do Kleep App Embed.
Por exemplo:
**Passo 5: Adicionar traduções em inglês**
Adicione traduções em inglês aos locales do seu tema.
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "Find my ideal size",
"with_hash": "Ideal size"
}
},
"recommended": {
"text": {
"btn": "View similar",
"hint": "Size unavailable",
"link": "See similar products"
}
},
"search": {
"text": {
"inputPlaceholder": "Search...",
"productsBlockTitle": "Products",
"clearButton": "Clear"
}
},
"searchPage": {
"text": {
"header": "search results",
"query": "Results for",
"submit": "Search",
"input": "Search the store",
"viewProduct": "View product"
}
}
}
```
**Passo 6: Adicionar traduções em outros idiomas**
Adicione outras traduções aos locales do seu tema.
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "Trouver ma taille idéale",
"with_hash": "Taille idéale"
}
},
"recommended": {
"text": {
"btn": "Voir similaire",
"hint": "Taille indisponible",
"link": "Voir des produits similaires"
}
},
"search": {
"text": {
"inputPlaceholder": "Recherche...",
"productsBlockTitle": "Produits",
"clearButton": "Effacer"
}
},
"searchPage": {
"text": {
"header": "résultats de la recherche",
"query": "Résultats pour",
"submit": "Recherche",
"input": "Rechercher dans la boutique",
"viewProduct": "Voir le produit"
}
}
}
```
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "Trova la mia taglia ideale",
"with_hash": "Taglia ideale"
}
},
"recommended": {
"text": {
"btn": "Visualizza simili",
"hint": "Taglia non disponibile",
"link": "Visualizza prodotti simili"
}
},
"search": {
"text": {
"inputPlaceholder": "Cerca...",
"productsBlockTitle": "Prodotti",
"clearButton": "Cancella"
}
},
"searchPage": {
"text": {
"header": "risultati della ricerca",
"query": "Risultati per",
"submit": "Cerca",
"input": "Cerca nel negozio",
"viewProduct": "Visualizza prodotto"
}
}
}
```
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "Finde meine ideale Größe",
"with_hash": "Ideale Größe"
}
},
"recommended": {
"text": {
"btn": "Ähnliche Ansicht",
"hint": "Größe nicht verfügbar",
"link": "Ähnliche Produkte ansehen"
}
},
"search": {
"text": {
"inputPlaceholder": "Suchen...",
"productsBlockTitle": "Produkte",
"clearButton": "Klar"
}
},
"searchPage": {
"text": {
"header": "Suchergebnisse",
"query": "Ergebnisse für",
"submit": "Suchen",
"input": "Durchsuchen Sie den Shop",
"viewProduct": "Produkt ansehen"
}
}
}
```
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "Encontrar mi talla ideal",
"with_hash": "Talla ideal"
}
},
"recommended": {
"text": {
"btn": "Ver similares",
"hint": "Talla no disponible",
"link": "Ver productos similares"
}
},
"search": {
"text": {
"inputPlaceholder": "Buscar...",
"productsBlockTitle": "Productos",
"clearButton": "Borrar"
}
},
"searchPage": {
"text": {
"header": "resultados de búsqueda",
"query": "Resultados para",
"submit": "Buscar",
"input": "Buscar en la tienda",
"viewProduct": "Ver producto"
}
}
}
```
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "自分に合うサイズを探す",
"with_hash": "好みのサイズ"
}
},
"recommended": {
"text": {
"btn": "類似商品を見る",
"hint": "サイズがありません",
"link": "類似商品を見る"
}
},
"search": {
"text": {
"inputPlaceholder": "検索...",
"productsBlockTitle": "商品",
"clearButton": "クリア"
}
},
"searchPage": {
"text": {
"header": "検索結果",
"query": "検索結果",
"submit": "検索",
"input": "ストアを検索",
"viewProduct": "商品を見る"
}
}
}
```
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "내 이상적인 사이즈 찾기",
"with_hash": "추천 사이즈"
}
},
"recommended": {
"text": {
"btn": "유사한 상품 보기",
"hint": "사용 불가",
"link": "유사한 상품 보기"
}
},
"search": {
"text": {
"inputPlaceholder": "검색...",
"productsBlockTitle": "상품",
"clearButton": "지우기"
}
},
"searchPage": {
"text": {
"header": "검색 결과",
"query": "다음에 대한 결과",
"submit": "검색",
"input": "매장 검색",
"viewProduct": "상품 보기"
}
}
}
```
```jsx theme={null}
"kleep": {
"button": {
"text": {
"without_hash": "Encontrar meu tamanho ideal",
"with_hash": "Tamanho recomendado"
}
},
"recommended": {
"text": {
"btn": "Ver similar",
"hint": "Tamanho indisponível",
"link": "Ver produtos similares"
}
},
"search": {
"text": {
"inputPlaceholder": "Pesquisar...",
"productsBlockTitle": "Produtos",
"clearButton": "Limpar"
}
},
"searchPage": {
"text": {
"header": "resultados da pesquisa",
"query": "Resultados para",
"submit": "Pesquisar",
"input": "Pesquisar na loja",
"viewProduct": "Ver produto"
}
}
}
```
1. Valide as atualizações na área de personalização de temas do Shopify. Configure os visuais nas configurações do bloco de informações do produto.
2. Se quiser adicionar um botão secundário, você precisará criar um novo arquivo chamado `kleep-secondary-button.liquid` dentro da pasta `snippets`. Coloque o seguinte conteúdo:
```
```
Cole o código a seguir onde deseja que o Kleep apareça. Deve fazer parte do bloco `Product info` dentro da pasta `snippets`.
```jsx theme={null}
{% render 'kleep-secondary-button', cms: section.settings %}
```
## 2. Produtos Similares
***
### Instalar "Produtos Similares" para Temas Shopify V1
Neste caso, você deve adicionar um trecho Liquid manualmente.
### Passo 1 - Criar um trecho
Crie:
`snippets/kleep-similar-button.liquid`
Insira o seguinte código:
```jsx theme={null}
{% assign cms = block.settings %}
{% assign domain = shop.domain %}
{% assign translated_similar = '' %}
{% assign translated_similar_missing = true %}
{%- assign domain_key = domain | prepend: 'www.' | append: '.recommended' -%}
{% assign raw_domain_similar = domain_key | t %}
{% unless raw_domain_similar contains 'Translation missing'
or raw_domain_similar contains domain
%}
{% assign translated_similar = raw_domain_similar %}
{% assign translated_similar_missing = false %}
{% endunless %}
{%- if translated_similar_missing -%}
{% assign raw_global_similar = 'kleep.recommended.text.btn' | t %}
{% unless raw_global_similar contains 'Translation missing' %}
{% assign translated_similar = raw_global_similar %}
{% assign translated_similar_missing = false %}
{% endunless %}
{%- endif %}
```
### Passo 2 - Renderizar o trecho no template de produto
Insira esta linha onde deseja que o botão apareça:
```jsx theme={null}
{% render 'kleep-similar-button' %}
```
Posicionamento típico: abaixo dos seletores de variante ou próximo ao formulário de Adicionar ao Carrinho.
### Passo 3 - Ativar o modo correto para temas V1
Como os temas V1 não suportam blocos OS2.0, o widget deve usar um dos seguintes modos:
* `custom_buttons`
* `popup+custom`
* `button+custom`
### **Instalar "Produtos Similares" para Lojas V2 (Online Store 2.0)**
Temas modernos do Shopify suportam app embeds e blocos personalizados. Nenhuma alteração de código é necessária.
### Passo 1 — Ativar o App Embed do Kleep
1. Vá em **Loja Online → Temas → Personalizar**.
2. Abra a seção **App embeds**.
3. Ative o **Aplicativo Kleep.**
4. Salve o tema.
Isso ativa o script principal que gerencia a lógica de Produtos Similares.
Em seguida, localize a opção **"Mostrar produtos recomendados"**
### Passo 2 — Selecionar o modo de exibição de Produtos Similares
Nas configurações do widget Kleep, escolha como os Produtos Similares devem aparecer na Página do Produto:
* disabled – desativa completamente o recurso
* popup – adiciona automaticamente um popup acima dos seletores de variante/tamanho no desktop e substitui o botão padrão no mobile
* button – insere automaticamente um botão CTA próximo à área de Adicionar ao Carrinho quando a variante selecionada está fora de estoque
* custom\_buttons – desativa todo o posicionamento automático; o lojista deve adicionar um ou mais blocos "Kleep Similar Button" manualmente
* popup+custom – mantém o popup automático e também ativa quaisquer botões personalizados adicionados ao tema
* button+custom – mantém o botão CTA automático e também ativa quaisquer botões personalizados adicionados ao tema
Depois disso, basta salvar o tema e ele aparecerá imediatamente na sua loja (página do produto).
**Passo 3 — Adicionar Botões Personalizados (apenas para custom\_buttons, popup+custom, button+custom)**
Se o modo selecionado incluir botões personalizados:
1. Abra **Loja Online → Personalizar**.
2. Vá para o template de **Página do produto**.
3. Na seção desejada, clique em **Adicionar Bloco**.
4. Selecione **Kleep Similar Button**.
5. Salve o tema.
Os botões personalizados aparecerão apenas quando a variante selecionada estiver fora de estoque.
## Adicionar Múltiplos Botões de "Produtos Similares" (Principal e Secundário)
Você pode adicionar qualquer número de botões de Produtos Similares na Página do Produto.
Isso funciona tanto para temas OS 2.0 quanto para temas V1 / legados.
## Ativar um Modo que Suporte Botões Personalizados
Para permitir múltiplos botões, o widget deve ser configurado para um dos seguintes modos:
* custom\_buttons
* popup+custom
* button+custom
Esses modos ativam o posicionamento manual, permitindo que os lojistas insiram quantos botões forem necessários.
## Para Online Store 2.0 (Temas Modernos)
Os temas OS 2.0 permitem adicionar botões visualmente pelo Editor de Temas.
Passos:
* Vá em Loja Online → Personalizar
* Abra o template de Página do produto
* Clique em Adicionar bloco → Kleep Similar Button
* Adicione o botão onde quiser
* Repita se desejar 2+ botões na página
Cada botão aparece automaticamente apenas quando a variante selecionada está fora de estoque.
## Para Temas V1 / Legados
Temas legados não suportam blocos, mas você pode renderizar o trecho várias vezes.
Insira este trecho onde quiser um botão:
`{% render 'kleep-similar-button' %}`
Para criar múltiplos botões, basta colocar este código em diferentes áreas do template de produto.
Cada chamada do trecho cria um botão adicional.
### Resumo
Para adicionar múltiplos botões de Produtos Similares:
Ative qualquer modo com botões personalizados → adicione vários blocos OS 2.0 ou múltiplas chamadas de trecho → todos os botões funcionam automaticamente quando a variante está fora de estoque.
***
**Localização do CTA na PDP**
A localização é definida por seletores DOM dentro de `KleepSDK.getConstants().`
`targetProductInfoBlockQueries` – onde está a informação do produto. Este é um array de seletores que apontam para o contêiner principal dos detalhes do produto (título, preço, tamanhos, etc.). O script itera por esses seletores e usa o primeiro encontrado como ponto de inserção para o CTA ou popups.
`targetVariantQueries` – onde estão as opções de tamanho/variante: Após encontrar o bloco de informações do produto, o script busca dentro dele elementos de variante (como seletores de tamanho). Cada `
**Passo 2: Renderizar o trecho do botão**
Cole o código a seguir onde deseja que o Kleep apareça. Deve fazer parte do bloco `Product info` dentro da pasta `snippets`.
```jsx theme={null}
{% render 'kleep-button', cms: section.settings %}
```
**Passo 3: Criar o arquivo do trecho do botão**
Crie um novo arquivo chamado `kleep-button.liquid` dentro da pasta `snippets`. Coloque o seguinte conteúdo:
**Passo 5: Adicionar traduções em inglês**
Adicione traduções em inglês aos locales do seu tema.
Em seguida, localize a opção **"Mostrar produtos recomendados"**
### Passo 2 — Selecionar o modo de exibição de Produtos Similares
Nas configurações do widget Kleep, escolha como os Produtos Similares devem aparecer na Página do Produto:
* disabled – desativa completamente o recurso
* popup – adiciona automaticamente um popup acima dos seletores de variante/tamanho no desktop e substitui o botão padrão no mobile
* button – insere automaticamente um botão CTA próximo à área de Adicionar ao Carrinho quando a variante selecionada está fora de estoque
* custom\_buttons – desativa todo o posicionamento automático; o lojista deve adicionar um ou mais blocos "Kleep Similar Button" manualmente
* popup+custom – mantém o popup automático e também ativa quaisquer botões personalizados adicionados ao tema
* button+custom – mantém o botão CTA automático e também ativa quaisquer botões personalizados adicionados ao tema
Depois disso, basta salvar o tema e ele aparecerá imediatamente na sua loja (página do produto).
**Passo 3 — Adicionar Botões Personalizados (apenas para custom\_buttons, popup+custom, button+custom)**
Se o modo selecionado incluir botões personalizados:
1. Abra **Loja Online → Personalizar**.
2. Vá para o template de **Página do produto**.
3. Na seção desejada, clique em **Adicionar Bloco**.
4. Selecione **Kleep Similar Button**.
5. Salve o tema.
Os botões personalizados aparecerão apenas quando a variante selecionada estiver fora de estoque.
## Adicionar Múltiplos Botões de "Produtos Similares" (Principal e Secundário)
Você pode adicionar qualquer número de botões de Produtos Similares na Página do Produto.
Isso funciona tanto para temas OS 2.0 quanto para temas V1 / legados.
## Ativar um Modo que Suporte Botões Personalizados
Para permitir múltiplos botões, o widget deve ser configurado para um dos seguintes modos:
* custom\_buttons
* popup+custom
* button+custom
Esses modos ativam o posicionamento manual, permitindo que os lojistas insiram quantos botões forem necessários.
## Para Online Store 2.0 (Temas Modernos)
Os temas OS 2.0 permitem adicionar botões visualmente pelo Editor de Temas.
Passos:
* Vá em Loja Online → Personalizar
* Abra o template de Página do produto
* Clique em Adicionar bloco → Kleep Similar Button
* Adicione o botão onde quiser
* Repita se desejar 2+ botões na página
Cada botão aparece automaticamente apenas quando a variante selecionada está fora de estoque.
## Para Temas V1 / Legados
Temas legados não suportam blocos, mas você pode renderizar o trecho várias vezes.
Insira este trecho onde quiser um botão:
`{% render 'kleep-similar-button' %}`
Para criar múltiplos botões, basta colocar este código em diferentes áreas do template de produto.
Cada chamada do trecho cria um botão adicional.
### Resumo
Para adicionar múltiplos botões de Produtos Similares:
Ative qualquer modo com botões personalizados → adicione vários blocos OS 2.0 ou múltiplas chamadas de trecho → todos os botões funcionam automaticamente quando a variante está fora de estoque.
***
**Localização do CTA na PDP**
A localização é definida por seletores DOM dentro de `KleepSDK.getConstants().`
`targetProductInfoBlockQueries` – onde está a informação do produto. Este é um array de seletores que apontam para o contêiner principal dos detalhes do produto (título, preço, tamanhos, etc.). O script itera por esses seletores e usa o primeiro encontrado como ponto de inserção para o CTA ou popups.
`targetVariantQueries` – onde estão as opções de tamanho/variante: Após encontrar o bloco de informações do produto, o script busca dentro dele elementos de variante (como seletores de tamanho). Cada `