> ## 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 via a nossa biblioteca JavaScript.

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)

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

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

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

## 2. Instalação

Para começar, inclua o ficheiro 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 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:

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

## 3. Métodos

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

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

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

2. Adicione um contentor onde o widget deve ser apresentado na página de produto:

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

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

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

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

<Accordion title="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
</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, pode utilizar esta configuração de teste:

  * `public_id`: `"aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"`
  * `product_id`: `"12345"`
  * `variantId`s a utilizar para os callbacks (com o respetivo 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, 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`

```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 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](/pt/cookie-consent).