> ## 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 secção mostra como adicionar o Kleep AI Sizing à sua Loja Shopify.
Siga o nosso tutorial Tango para adicionar o botão Kleep à sua loja em temas Online Store 2.0.
## Guia de Integração Shopify V1
## 1. Dimensionamento
Esta secção mostra como adicionar o Kleep AI Sizing ao código da sua loja Shopify.
Veja o tutorial Tango passo a passo para instalar o Kleep numa loja Shopify V1.
### Passos
**Passo 1: Ativar o App Embed**
Certifique-se de que a aplicação Kleep está ativada nos seus App embeds.
**Passo 2: Renderizar o snippet do botão**
Cole o seguinte código onde pretende 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 ficheiro do snippet do botão**
Crie um novo ficheiro com o nome `kleep-button.liquid` dentro da pasta `snippets`. Insira o seguinte conteúdo:
```jsx theme={null}
```
**Passo 4: Adicionar opções ao esquema de Definições**
Adicione as seguintes opções ao seu esquema de Definiçõ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 os seus próprios estilos CSS:
* Para alterar o aspeto (cores, espaçamento, tipos de letra, etc.), cole o seu CSS na caixa **"Input custom CSS styles"** nas definiçõ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 noutros 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 do Tema Shopify. Configure os visuais nas definições do bloco de informações do produto.
2. Se pretender adicionar um botão secundário, terá de criar um novo ficheiro com o nome `kleep-secondary-button.liquid` dentro da pasta `snippets`. Insira o seguinte conteúdo:
```
```
Cole o seguinte código onde pretende 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, deve adicionar um snippet Liquid manualmente.
### Passo 1 - Criar um snippet
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 snippet dentro do template de produto
Insira esta linha onde pretende que o botão apareça:
```jsx theme={null}
{% render 'kleep-similar-button' %}
```
Posição típica: abaixo dos seletores de variante ou perto do formulário Adicionar ao Carrinho.
### Passo 3 - Ativar o modo correto para temas V1
Como os temas V1 não podem inserir 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)**
Os temas Shopify modernos suportam app embeds e blocos personalizados. Não são necessárias alterações de código.
### Passo 1 — Ativar o Kleep App Embed
1. Vá a **Loja Online → Temas → Personalizar**.
2. Abra a secção **App embeds**.
3. Ative a **Aplicação Kleep.**
4. Guarde o tema.
Isto ativa o script principal que gere a lógica de Produtos Similares.
Em seguida, localize **"Show recommended products"**
### Passo 2 — Selecionar o modo de visualização de Produtos Similares
Dentro da configuração do widget Kleep, escolha como os Produtos Similares devem aparecer na Página de Produto:
* disabled – desativa completamente a funcionalidade
* popup – adiciona automaticamente um popup acima dos seletores de variante/tamanho no ambiente de trabalho, e substitui o botão predefinido no móvel
* button – insere automaticamente um botão CTA perto da área Adicionar ao Carrinho quando a variante selecionada está esgotada
* custom\_buttons – desativa todo o posicionamento automático; o comerciante 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 no tema
* button+custom – mantém o botão CTA automático e também ativa quaisquer botões personalizados adicionados no tema
Depois disso, basta guardar o tema e aparecerá imediatamente na sua loja (página de 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á ao template de **Página de produto**.
3. Na secção desejada, clique em **Adicionar Bloco**.
4. Selecione **Kleep Similar Button**.
5. Guarde o tema.
Os botões personalizados só aparecerão quando a variante selecionada estiver esgotada.
## Adicionar Múltiplos Botões de "Produtos Similares" (Principal e Secundário)
Pode adicionar qualquer número de botões de Produtos Similares na Página de Produto.
Isto funciona tanto para temas OS 2.0 como para temas V1 / legacy.
## Ativar um Modo que Suporte Botões Personalizados
Para permitir múltiplos botões, o widget deve estar definido para um dos seguintes modos:
* custom\_buttons
* popup+custom
* button+custom
Estes modos ativam o posicionamento manual, para que os comerciantes possam inserir tantos botões quantos necessários.
## Para Online Store 2.0 (Temas Modernos)
Os temas OS 2.0 permitem adicionar botões visualmente através do Editor de Tema.
Passos:
* Vá a Loja Online → Personalizar
* Abra o template de Página de produto
* Clique em Adicionar bloco → Kleep Similar Button
* Adicione o botão onde pretender
* Repita se pretender 2+ botões na página
Todos os botões aparecem automaticamente apenas quando a variante selecionada está esgotada.
## Para Temas V1 / Legacy
Os temas legacy não suportam blocos, mas pode renderizar o snippet múltiplas vezes.
Insira este snippet onde pretende 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 ao snippet 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 ao snippet → todos os botões funcionam automaticamente quando a variante está esgotada.
***
**Posição do CTA no PDP**
A posição é definida por seletores DOM dentro de `KleepSDK.getConstants().`
`targetProductInfoBlockQueries` – onde estão as informações do produto. É um array de seletores que apontam para o contentor principal dos detalhes do produto (título, preço, tamanhos, etc.). O script itera por estes seletores e usa o primeiro que encontra como ponto de inserção do CTA ou dos popups.
`targetVariantQueries` – onde estão as opções de tamanho/variante: Uma vez encontrado o bloco de informações do produto, o script pesquisa no seu interior por elementos de variante (como seletores de tamanho). Cada `
**Passo 2: Renderizar o snippet do botão**
Cole o seguinte código onde pretende 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 ficheiro do snippet do botão**
Crie um novo ficheiro com o nome `kleep-button.liquid` dentro da pasta `snippets`. Insira 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 **"Show recommended products"**
### Passo 2 — Selecionar o modo de visualização de Produtos Similares
Dentro da configuração do widget Kleep, escolha como os Produtos Similares devem aparecer na Página de Produto:
* disabled – desativa completamente a funcionalidade
* popup – adiciona automaticamente um popup acima dos seletores de variante/tamanho no ambiente de trabalho, e substitui o botão predefinido no móvel
* button – insere automaticamente um botão CTA perto da área Adicionar ao Carrinho quando a variante selecionada está esgotada
* custom\_buttons – desativa todo o posicionamento automático; o comerciante 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 no tema
* button+custom – mantém o botão CTA automático e também ativa quaisquer botões personalizados adicionados no tema
Depois disso, basta guardar o tema e aparecerá imediatamente na sua loja (página de 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á ao template de **Página de produto**.
3. Na secção desejada, clique em **Adicionar Bloco**.
4. Selecione **Kleep Similar Button**.
5. Guarde o tema.
Os botões personalizados só aparecerão quando a variante selecionada estiver esgotada.
## Adicionar Múltiplos Botões de "Produtos Similares" (Principal e Secundário)
Pode adicionar qualquer número de botões de Produtos Similares na Página de Produto.
Isto funciona tanto para temas OS 2.0 como para temas V1 / legacy.
## Ativar um Modo que Suporte Botões Personalizados
Para permitir múltiplos botões, o widget deve estar definido para um dos seguintes modos:
* custom\_buttons
* popup+custom
* button+custom
Estes modos ativam o posicionamento manual, para que os comerciantes possam inserir tantos botões quantos necessários.
## Para Online Store 2.0 (Temas Modernos)
Os temas OS 2.0 permitem adicionar botões visualmente através do Editor de Tema.
Passos:
* Vá a Loja Online → Personalizar
* Abra o template de Página de produto
* Clique em Adicionar bloco → Kleep Similar Button
* Adicione o botão onde pretender
* Repita se pretender 2+ botões na página
Todos os botões aparecem automaticamente apenas quando a variante selecionada está esgotada.
## Para Temas V1 / Legacy
Os temas legacy não suportam blocos, mas pode renderizar o snippet múltiplas vezes.
Insira este snippet onde pretende 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 ao snippet 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 ao snippet → todos os botões funcionam automaticamente quando a variante está esgotada.
***
**Posição do CTA no PDP**
A posição é definida por seletores DOM dentro de `KleepSDK.getConstants().`
`targetProductInfoBlockQueries` – onde estão as informações do produto. É um array de seletores que apontam para o contentor principal dos detalhes do produto (título, preço, tamanhos, etc.). O script itera por estes seletores e usa o primeiro que encontra como ponto de inserção do CTA ou dos popups.
`targetVariantQueries` – onde estão as opções de tamanho/variante: Uma vez encontrado o bloco de informações do produto, o script pesquisa no seu interior por elementos de variante (como seletores de tamanho). Cada `