Biblioteca JS - Kleep Docs

Este guia cobre a instalação do widget Kleep AI Sizing em qualquer loja usando a nossa biblioteca JavaScript. Utilize-o juntamente 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 frontend nas suas páginas de produto.

1. Consentimento de cookies (requisito legal)

Carregar o Kleep processa dados pessoais através de cookies e tecnologias semelhantes. Deve, portanto, condicionar legalmente o carregamento do Kleep ao consentimento prévio do visitante em relação aos cookies — não chame kleep.load (nem carregue a biblioteca) até que o visitante tenha aceite os cookies relevantes na sua Plataforma de Gestão de Consentimento (CMP).

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

O seu CMP deve expor duas finalidades de tratamento, e o Kleep só pode ser carregado após o visitante ter consentido em ambas. A redação exata a apresentar no seu banner — em 15 idiomas — está disponível na página Cookies, CMP e Privacidade de Dados. Copie-a a partir daí.

2. Instalação

Para começar, inclua o ficheiro 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 executa silenciosamente. Para imprimir os logs completos [KLEEP] [Widget] (fluxo de carregamento, parâmetros, criação do CTA, etc.) na consola do seu browser, adicione ?debug=true ao URL da biblioteca:

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

Este flag no URL é a única forma de ativar os logs detalhados — não existe uma opção debug no kleep.load(...). Os avisos críticos (idioma lang/market não suportado, incompatibilidade product_id/selectors, chamada dupla a kleep.load) são sempre mostrados, mesmo sem este flag. Remova ?debug=true em produção.

3. Métodos

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

Inicialize o widget com kleep.load:

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

Adicione um contentor onde o widget deve ser apresentado na página de produto:
```
<div id="kleep-container"></div>
```

Esta div é utilizada para inserir o nosso botão no interior. Deixamos o estilo CSS do botão a seu cargo 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 durante o onboarding	obrigatório
`product_id`	string \| array	ID(s) de produto do PDP em que `kleep.load` é chamado. Uma string única aplica-se a todos os seletores; um array deve corresponder a `selectors.sizing` (ver aviso abaixo).	obrigatório
`customer_id`	string	ID do cliente ligado (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`. Consulte a lista de idiomas suportados abaixo.	obrigatório
`market`	string	Código de país (localização do visitante do website). Siga o ISO 3166-1 alpha-2. Padrão: `null`. Consulte a lista de mercados suportados abaixo.	opcional
`selectors.sizing`	array	Seletores HTML do(s) contentor(es) do botão de dimensionamento. Passe múltiplos para adicionar vários CTAs no mesmo PDP.	obrigatório
`getSizes`	função async	Retorna os tamanhos disponíveis como um array de `{ variantId, quantity }` para que o widget possa verificar se os tamanhos recomendados estão em stock.	obrigatório para esse uso, caso contrário opcional
`addToCart`	função async	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 async	Recebe um `variantId` como entrada e seleciona a variante correspondente na interface da sua loja (permite ao cliente saltar um clique).	obrigatório para esse uso, caso contrário opcional

Se lang ou market não seguirem as respetivas convenções ou não forem suportados, verá um aviso na consola.

Correspondência entre product_id e selectors.sizing. Estes dois parâmetros controlam qual produto é apresentado em qual contentor, pelo que têm de estar alinhados:

Um produto num ou vários contentores → passe product_id como uma string única. O mesmo produto é aplicado a todos os seletores em selectors.sizing.
Produtos diferentes, um por contentor → passe product_id como um array com o mesmo comprimento que selectors.sizing. São emparelhados por índice, pelo que a ordem deve corresponder (product_id[0] → selectors.sizing[0], etc.).

Se product_id for um array com um comprimento diferente do de selectors.sizing, nenhum CTA é apresentado e um aviso é registado na consola (apresenta 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 de que necessita não estiver na lista abaixo, contacte o seu representante Kleep.

fr — Francês (padrão)
br — Português do Brasil
da — Dinamarquês
de — Alemão
en — Inglês
es — Espanhol
fi — Finlandês
it — Italiano
ja — Japonês
ko — Coreano
nl — Neerlandês
pl — Polaco
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, pode utilizar esta configuração de teste:

public_id: "aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"
product_id: "12345"
variantIds a utilizar para os callbacks (com o respetivo 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, o seu website pode reconstruir componentes ou recarregar variáveis de estado, fazendo com que o CTA do Kleep desapareça. Chame kleep.createButton para o fazer reaparecer. Não são necessários parâmetros — reutiliza a informação fornecida ao chamar kleep.load, pelo que certifique-se de que kleep.load foi executado primeiro.

3.3. `kleep.track` — Ativar tracking e acesso ao Dashboard

Para além da funcionalidade de dimensionamento, adicionamos tracking para que possa medir o desempenho da solução no seu website. Utilize kleep.track(event_type, event_info) para enviar informação cada vez que um evento rastreado ocorre. Rastreamos três eventos:

Tipo de evento	Acionador	Prioridade
`product_viewed`	Quando o PDP é visualizado	`obrigatório`
`product_added_to_cart`	Quando o produto é adicionado ao carrinho	`obrigatório`
`checkout_completed`	Quando a encomenda é confirmada 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 o ID interno do Kleep

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

null — se o visitante não utilizou o Kleep, ou
um UUID — se o visitante tem um ID de tracking Kleep

Cookies e privacidade de dados

O Kleep está totalmente condicionado ao consentimento do visitante: o script só carrega após a recolha do consentimento através do seu CMP, e deve condicionar o seu carregamento em conformidade. Para a lista completa de trackers, os dados processados, as finalidades e bases legais, alojamento, subprocessadores 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 — Apresentar o CTA do Kleep

​Parâmetros

​Exemplo

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

​3.3. kleep.track — Ativar tracking e acesso ao Dashboard

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Obter o 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` — Apresentar o CTA do Kleep

Parâmetros

Exemplo

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

3.3. `kleep.track` — Ativar tracking e acesso ao Dashboard

`product_viewed`

`product_added_to_cart`

`checkout_completed`

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

Cookies e privacidade de dados