Biblioteca JS - Kleep Docs

Este guia abrange a instalação do widget Kleep AI Sizing em qualquer loja virtual usando nossa biblioteca JavaScript. Use-o junto com o guia de integração de backend específico da plataforma (Prestashop, Magento, WooCommerce, WShop, etc.) — que trata da ingestão de dados, enquanto este guia trata do CTA de frontend nas suas páginas de produto.

1. Consentimento de cookies (requisito legal)

Carregar o Kleep processa dados pessoais por meio de cookies e tecnologias similares. Portanto, você deve legalmente condicionar o carregamento do Kleep ao consentimento prévio do visitante para cookies — não chame kleep.load (nem carregue a biblioteca) até que o visitante tenha aceitado os cookies relevantes na sua Plataforma de Gerenciamento de Consentimento (CMP).

Concretamente: condicione a tag <script src="https://module.kleep.ai/api/widget"> e a chamada kleep.load(...) ao callback de consentimento da sua CMP, para que sejam executados somente após o consentimento ser concedido para ambas as finalidades. Se o consentimento for posteriormente retirado, pare de carregar o Kleep em visualizações de página subsequentes.

Sua CMP deve expor duas finalidades de tratamento, e o Kleep só pode ser carregado após o visitante ter consentido com ambas. O texto exato a exibir no seu banner — em 15 idiomas — está na página Cookies, CMP e Privacidade de Dados. Copie-o a partir daí.

2. Instalação

Para começar, inclua o arquivo JavaScript do widget no seu projeto. Antes de </body>, adicione:

<script src="https://module.kleep.ai/api/widget"></script>

Ver os logs durante a integração. Por padrão, o widget opera silenciosamente. Para imprimir os logs completos [KLEEP] [Widget] (fluxo de carregamento, parâmetros, criação do CTA, etc.) no console do navegador, adicione ?debug=true à URL da biblioteca:

<script src="https://module.kleep.ai/api/widget?debug=true"></script>

Este parâmetro de URL é a única forma de ativar os logs detalhados — não há opção debug no kleep.load(...). Avisos críticos (idioma/mercado lang/market não suportados, incompatibilidade de product_id/selectors, chamada dupla de kleep.load) são sempre exibidos, mesmo sem este parâmetro. Remova ?debug=true em produção.

3. Métodos

3.1. `kleep.load` — Exibir o CTA do Kleep

Inicialize o widget com kleep.load:

<script>kleep.load({ /* ...params */ })</script>

Adicione um contêiner onde o widget deve ser exibido na página do produto:
```
<div id="kleep-container"></div>
```

Esta div é usada para inserir nosso botão dentro. Deixamos a estilização CSS do botão para você durante a implementação.

Parâmetros

kleep.load deve ser chamado em cada página de produto (PDP) para carregar o CTA do Kleep, com os seguintes parâmetros:

Parâmetro	Tipo	Descrição	Prioridade
`public_id`	UUID	O UUID fornecido a você durante o onboarding	obrigatório
`product_id`	string \| array	ID(s) de produto da PDP na qual `kleep.load` é chamado. Uma string única se aplica a todos os seletores; um array deve corresponder a `selectors.sizing` (veja o aviso abaixo).	obrigatório
`customer_id`	string	ID do cliente conectado (deve corresponder ao que é enviado via transferências de dados)	opcional
`lang`	string	Idioma atual da página. Siga o ISO 639-1. Padrão: `fr`. Veja a lista de idiomas suportados abaixo.	obrigatório
`market`	string	Código do país (localização do visitante do site). Siga o ISO 3166-1 alpha-2. Padrão: `null`. Veja a lista de mercados suportados abaixo.	opcional
`selectors.sizing`	array	Seletores HTML do(s) contêiner(es) do botão de dimensionamento. Passe múltiplos para adicionar vários CTAs na mesma PDP.	obrigatório
`getSizes`	função assíncrona	Retorna os tamanhos disponíveis como um array de `{ variantId, quantity }` para que o widget possa verificar se os tamanhos recomendados estão em estoque.	obrigatório para esse uso, caso contrário opcional
`addToCart`	função assíncrona	Recebe um `variantId` como entrada e adiciona a variante de produto correspondente ao carrinho.	obrigatório para esse uso, caso contrário opcional
`selectSize`	função assíncrona	Recebe um `variantId` como entrada e seleciona a variante correspondente na UI da sua loja virtual (permite ao cliente pular um clique).	obrigatório para esse uso, caso contrário opcional

Se lang ou market não seguirem suas respectivas convenções ou não forem suportados, um aviso será exibido no console.

Correspondência entre product_id e selectors.sizing. Esses dois controlam qual produto é exibido em qual contêiner, portanto devem estar alinhados:

Um produto em um ou vários contêineres → passe product_id como uma string única. O mesmo produto é aplicado a todos os seletores em selectors.sizing.
Produtos diferentes, um por contêiner → passe product_id como um array com o mesmo comprimento que selectors.sizing. Eles são emparelhados por índice, então a ordem deve corresponder (product_id[0] → selectors.sizing[0], e assim por diante).

Se product_id for um array cujo comprimento seja diferente de selectors.sizing, nenhum CTA é renderizado e um aviso é registrado no console (imprime ambos os comprimentos e valores). Por exemplo, product_id: ["sku-1"] (1 item) com dois seletores falha silenciosamente — corrija repetindo o id (["sku-1", "sku-1"]) ou passando-o como string ("sku-1").

Idiomas suportados (ISO 639-1)

Se um idioma que você precisa não estiver na lista abaixo, entre em contato com seu representante Kleep.

fr — Francês (padrão)
br — Português brasileiro
da — Dinamarquês
de — Alemão
en — Inglês
es — Espanhol
fi — Finlandês
it — Italiano
ja — Japonês
ko — Coreano
nl — Holandês
pl — Polonês
pt — Português
sv — Sueco
zh — Chinês

Mercados suportados (ISO 3166-1 alpha-2)

AF, AX, AL, DZ, AD, AO, AI, AG, AR, AM, AW, AC, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CA, CV, BQ, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, HR, CU, CW, CY, CZ, CI, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MQ, MR, MU, YT, MX, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MK, NO, OM, PK, PS, PA, PG, PY, PE, PH, PN, PL, PT, QA, CM, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, KR, SS, ES, LK, VC, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TA, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, WF, EH, YE, ZM, ZW, ZZ

Exemplo

kleep.load({
  public_id: "UUID",
  product_id: ["id_1", "id_2"],
  customer_id: "customer_test",
  lang: "fr-FR",
  market: "EU",
  selectors: {
    sizing: ["#kleep-container-1", "#kleep-container-2"]
  },
  getSizes: async () => {
    return [
      { variantId: "variant-XYZ-XS", quantity: true },
      { variantId: "variant-XYZ-S", quantity: true },
      { variantId: "variant-XYZ-M", quantity: false },
      { variantId: "variant-XYZ-L", quantity: false },
      { variantId: "variant-XYZ-XL", quantity: true },
    ]
  },
  addToCart: async variantId => {
    document.querySelector(".sizes").value = variantId
    document.querySelector(".addToCart").click()
  },
  selectSize: async variantId => {
    document.querySelector(".sizes").value = variantId
  }
})

Durante a implementação, você pode usar esta configuração de teste:

public_id: "aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"
product_id: "12345"
variantIds para usar nos callbacks (com o rótulo de tamanho correspondente):

`variantId`	Tamanho
`a`	34
`b`	36
`c`	38
`d`	40
`e`	42

3.2. `kleep.createButton` — Recriar o CTA do Kleep

Em alguns casos, seu site pode reconstruir componentes ou recarregar variáveis de estado, fazendo o CTA do Kleep desaparecer. Chame kleep.createButton para fazê-lo reaparecer. Nenhum parâmetro é necessário — ele reutiliza as informações fornecidas quando kleep.load foi chamado, portanto certifique-se de que kleep.load foi executado primeiro.

3.3. `kleep.track` — Ativar rastreamento e acesso ao Painel

Além da funcionalidade de dimensionamento, adicionamos rastreamento para que você possa medir o desempenho da solução no seu site. Use kleep.track(event_type, event_info) para enviar informações toda vez que um evento rastreado ocorrer. Rastreamos três eventos:

Tipo de evento	Acionador	Prioridade
`product_viewed`	Ao visualizar a PDP	`obrigatório`
`product_added_to_cart`	Ao adicionar produto ao carrinho	`obrigatório`
`checkout_completed`	Ao confirmar pedido após o pagamento	`obrigatório`

`product_viewed`

kleep.track("product_viewed", {
  productId: "123ABC456"
})

`product_added_to_cart`

kleep.track("product_added_to_cart", {
  productId: "123ABC456",
  variantId: "123ABC456-00R",
  cart: [
    {
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 2,
      price: {
        amount: "50",
        currencyCode: "EUR"
      }
    },
    {
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 1,
      price: {
        amount: "40",
        currencyCode: "USD"
      }
    }
    // ...
  ],
})

`checkout_completed`

kleep.track("checkout_completed", {
  orderId: "000001",
  cart: [
    {
      lineItemId: "000001#1",
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 2,
      price: {
        amount: "50",
        currencyCode: "EUR"
      }
    },
    {
      lineItemId: "000000#2",
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 1,
      price: {
        amount: "40",
        currencyCode: "USD"
      }
    }
    // ...
  ],
})

3.4. `kleep.getTrackingId` — Obter ID interno do Kleep

Para casos de uso personalizados, você pode recuperar um dos IDs internos do Kleep para o visitante. Retorna:

null — se o visitante não usou o Kleep, ou
um UUID — se o visitante possui um ID de rastreamento do Kleep

Cookies e privacidade de dados

O Kleep é totalmente controlado pelo consentimento do visitante: o script só carrega após a coleta do consentimento pela sua CMP, e você deve condicionar o carregamento de acordo. Para a lista completa de rastreadores, os dados processados, as finalidades e bases legais, hospedagem, suboperadores e segurança, consulte Cookies, CMP e Privacidade de Dados.

​1. Consentimento de cookies (requisito legal)

​2. Instalação

​3. Métodos

​3.1. kleep.load — Exibir o CTA do Kleep

​Parâmetros

​Exemplo

​3.2. kleep.createButton — Recriar o CTA do Kleep

​3.3. kleep.track — Ativar rastreamento e acesso ao Painel

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Obter ID interno do Kleep

​Cookies e privacidade de dados

1. Consentimento de cookies (requisito legal)

2. Instalação

3. Métodos

3.1. `kleep.load` — Exibir o CTA do Kleep

Parâmetros

Exemplo

3.2. `kleep.createButton` — Recriar o CTA do Kleep

3.3. `kleep.track` — Ativar rastreamento e acesso ao Painel

`product_viewed`

`product_added_to_cart`

`checkout_completed`

3.4. `kleep.getTrackingId` — Obter ID interno do Kleep

Cookies e privacidade de dados