> ## 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.

# Biblioteca JS

> Instale e configure o widget Kleep AI Sizing em qualquer loja virtual usando nossa biblioteca JavaScript.

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)

<Warning>
  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).
</Warning>

<Note>
  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.
</Note>

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](/pt-BR/cookie-consent). Copie-o a partir daí.

## 2. Instalação

Para começar, inclua o arquivo JavaScript do widget no seu projeto.

Antes de `</body>`, adicione:

```html theme={null}
<script src="https://module.kleep.ai/api/widget"></script>
```

<Tip>
  **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:

  ```html theme={null}
  <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.
</Tip>

## 3. Métodos

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

1. Inicialize o widget com `kleep.load`:

   ```html theme={null}
   <script>kleep.load({ /* ...params */ })</script>
   ```

2. Adicione um contêiner onde o widget deve ser exibido na página do produto:

   ```html theme={null}
   <div id="kleep-container"></div>
   ```

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

#### 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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). 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 |

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

<Warning>
  **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"`).
</Warning>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

#### Exemplo

```javascript theme={null}
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
  }
})
```

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

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

  | `variantId` | Tamanho |
  | ----------- | ------- |
  | `a`         | 34      |
  | `b`         | 36      |
  | `c`         | 38      |
  | `d`         | 40      |
  | `e`         | 42      |
</Tip>

### 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`

```javascript theme={null}
kleep.track("product_viewed", {
  productId: "123ABC456"
})
```

#### `product_added_to_cart`

```javascript theme={null}
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`

```javascript theme={null}
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](/pt-BR/cookie-consent).