Shopify Integration Guide

This guide walks you through installing Kleep on your Shopify store. Kleep offers three main features: an intelligent size guide (Kleep Sizing), similar product recommendations (Kleep Similar Products), and an optimised product search (Kleep Search).

1. Pre-Onboarding Checklist

Before starting the integration, please gather the following information: Company Information

Legal company details (for contract and billing):
Company type:
- Monobrand (e.g., Eric Bompard)
- Multibrand owner (e.g, sœur / frere)
- Multibrand (showroom)
Main contact (name, email, phone):
Technical contact (name, email) — person who will handle the integration:
Agency contact (if applicable):
Billing contact:

Billing information

Payment method preference
- Direct debit (preferred) — https://pay.gocardless.com/BRT000352V7T67Q
- Bank transfer (alternative)

Store Configuration

List of Shopify environments (production, staging, dev, etc.):
Store URL(s) for each environment:
Go-live target date:

Environments Do you have multiple environments ? ⚠️ For each environment selected, you will need to provide the Shopify store URL and configure the Kleep app separately. Returns Provider Do you use a returns management provider? If you selected a provider, how are returns transmitted?

SFTP
Provider API
Other: ___

2. Functionalities

Kleep is integrated within your store by installing a custom app that was created beforehand. It allows to:

Add our CTA “Find my size” on your product pages
Customize its UI directly in the Theme Editor

Our app also creates automated flows of Products, Orders and Returns Data in order to stay up to date. These data are retrieved on a daily basis. Upon installation, the app creates a WebPixel which is used to track multiple metrics from which we derive the ROI of the solution.

3. Installation

Kleep handles the installation and configuration of the app for you. After sharing your .myshopify.com domain and Collaborator Code, you’ll receive a Collaborator Access request. Upon accepting this request, you’ll have to add an additional authorization to create a WebPixel which we cannot request on our end. It is used to track our solution’s ROI. You can follow this quick tutorial: https://app.tango.us/app/workflow/-----Kleep-sur-votre-Shopify---valider-les-autorisations-cbf4a2e93921474c8dd69fe1edd36807 Need help to find your Collaborator Code? https://app.tango.us/app/workflow/Trouver-son-Code-Collaborateur-sur-Shopify-b11350edbfd0470b9fd7a1054e8f4882

Product Data Mapping

Field	Description	Where to find it
Category	Product type (shirts, pants, dresses, etc.)	Product type, Tags, or Metafields
Gender	Men, Women, or Unisex	Tags or Metafields
Children	Yes/No — is this a kids product?	Tags or Metafields
Brand Reference (MPN/SKU)	The brand’s internal product code	SKU field or Metafields

How to Configure

Go to your Kleep Dashboard
Navigate to Settings → Data Mapping
For each field above, select where Kleep should look for the data
Map your values to Kleep’s standard values

Example mapping for Gender:

Your value	Kleep value
`homme`, `man`, `male`	`MAN`
`femme`, `woman`, `female`	`WOMAN`
`mixte`, `unisex`	`UNISEX`

💡 Tip: Kleep will automatically scan your recent products to suggest mappings. You can review and adjust them in the dashboard.

Size Systems Configuration Kleep supports multiple size systems (FR, UK, US, IT, SML, etc.). You need to specify which systems your brand uses. In the Kleep Dashboard:

Go to Settings → Size Systems
Select the size systems you use for each product category:
- Clothing (e.g., FR, SML)
- Shoes (e.g., EU, UK, US)
- Children (e.g., Age-based, Height-based)
- Lingerie (e.g., FR, Cup sizes)

⚠️ Important: Incorrect size system configuration will affect size recommendations accuracy.

Kleep needs to identify the following information from your Shopify products:

5. Similar Products Feature

Similar Products suggests alternative products when a size is out of stock. This feature increases conversions by offering relevant alternatives to customers. Available Display Modes

Mode	Description
Popup (auto)	Automatic popup on size hover (desktop) / button (mobile)
Button (auto)	Automatic CTA button near cart when out of stock
Custom buttons only	You manually place buttons via the theme editor
Popup + custom	Automatic popup + additional custom buttons
Button + custom	Automatic button + additional custom buttons

Configuration Step 1: Choose the Display Mode In the Kleep App Embed settings, find the “Show recommended products” option and select your desired mode from the dropdown menu.

Similar Products Mode Selection Adding Custom Buttons (for custom modes) If you’ve chosen a mode with “custom”, you can add buttons at specific locations:

Go to the Product page template in the theme editor
In the desired section, click Add block
Click the Apps tab and select “Kleep Similar Button”
Position the block where you want it and save

Add Kleep Similar Button Block

💡 Tip: Similar Products buttons only appear when a variant is out of stock. It’s normal if you don’t see them on all products.

Adding Multiple Buttons You can add any number of Similar Products buttons on the Product Page. To allow multiple buttons, the widget must be set to one of: custom_buttons, popup+custom, or button+custom. For OS 2.0 themes:

Go to Online Store → Customize
Open the Product page template
Click Add block → Kleep Similar Button
Repeat if you want 2+ buttons on the page

Every button automatically appears only when the selected variant is out of stock.

6. Kleep Search Feature

Kleep Search replaces the native Shopify search with an optimised search featuring size filters and personalised recommendations. Step 1: Enable Custom Search In the Kleep App Embed settings, enable the “Enable custom search” option.

Enable Custom Search Step 2: Access the Search Template In the theme editor, click the dropdown menu at the top (defaults to “Home page”) and select “Search” from the template list.

Select Search Template Step 3: Hide the Native Search In the Template section, hide or remove the native “Search results” block by clicking the eye icon.

Hide Native Search Step 4: Add the Kleep Search Block Click Add section, then in the Apps tab, select “Search” (kleep-dev).

Add Kleep Search Block Step 5: Configure Options Click the Search block you added to access settings: number of results, grid/list display, search delay, etc.

Search Configuration Options

7. Returns Integration (Optional)

If you use a returns management platform, Kleep can integrate return data to improve size recommendations. Supported Returns Providers

Global-e
Aftership
Fast Return
Return Go
Other (contact us)

Configuration

In the Kleep Dashboard, go to Settings → Returns
Select your returns provider
Follow the provider-specific instructions to connect your account

📧 If your provider is not listed, contact us at support@kleep.ai — we can set up a custom integration via SFTP or API.

8. Event Tracking & Analytics

Kleep automatically tracks user interactions for analytics. Make sure tracking is working correctly before go-live. Events Tracked

Event	Description
`kleep_button_click`	User clicked the size guide button
`kleep_drawer_open`	Size guide drawer opened
`kleep_size_recommended`	A size recommendation was displayed
`kleep_add_to_cart`	User added product to cart from Kleep
`kleep_similar_click`	User clicked on a similar product

Verification To verify events are firing correctly:

Open your browser’s Developer Tools (F12)
Go to the Network tab
Filter by “kleep”
Interact with the size guide button
You should see API calls for each event

⚠️ Before go-live: Ensure at least 5 events are triggered and payloads are valid. Complete one full user journey (button click → size recommendation → add to cart) to validate the integration.

9. CSS Customization

You can customize the appearance of Kleep elements (buttons, popups, search) by adding custom CSS. Where to Add CSS In the Kleep App Embed settings, you’ll find an “Input custom CSS styles” field. Paste your custom CSS there.

Custom CSS Field Example Customization

Code

.kleep-button {
  all: unset;
  font-style: normal;
  font-size: 1.3rem;
  font-weight: 400;
  text-transform: none;
  color: rgb(0, 0, 0);
  background-color: rgb(255, 255, 255);
  padding: 0;
  margin: 0;
  border: none;
  border-radius: 0;
  cursor: pointer;
  display: inline-block;
  position: relative;
}

10. Multiple Environments

If you have multiple Shopify environments (dev, staging, production), you need to configure Kleep for each one. Setup for Each Environment

Production store — Main store, fully configured
Staging/Dev stores — For testing before pushing to production

For each environment:

Install the Kleep app
Enable the App Embed
Contact your Kleep CSM to link the environment to your account

💡 Tip: Always test changes on staging before applying to production.

Environment-Specific URLs Provide your Kleep CSM with:

Production URL: https://www.yourbrand.com
Staging URL: https://staging.yourbrand.com (if applicable)
Dev URL: https://dev.yourbrand.com (if applicable)

10.5 CTA Button & Similar Products — Full Installation Guide

For the complete technical reference on installing the Kleep CTA button and Similar Products feature (including all Liquid code, settings schema, and secondary button setup), refer to the dedicated guide below: CTA Button & Similar Products — Full Installation Guide

11. Vintage Themes - Size Guide Setup

Vintage themes (also called “legacy” or created before Online Store 2.0) don’t support App Blocks. Installation requires Liquid code modifications.

⚠️ Important: This section requires Shopify development knowledge (Liquid).

Prerequisites

Access to the theme code editor (Online Store → Themes → Edit code)
Kleep App Embed must be enabled (see Section 3)

Step 1: Enable the App Embed Make sure the Kleep App is activated in your App embeds (same as Section 3). Step 2: Call the Snippet Paste the following code where you want Kleep to appear. It must be part of Product info block within snippets folder:

Code

{% render 'kleep-button', cms: section.settings %}

Step 3: Create the Button Snippet Create a new file named kleep-button.liquid within your snippets folder. Put the following content inside:

Code

<button
  type="button"
  style="display: none;{% if cms.font_family and cms.default_font_family == false %}font-family: '{{ cms.font_family }}' ;{% endif %}font-style: {{ cms.text_style }}; font-size: {{ cms.text_size }}px; font-weight: {{ cms.text_weight }}; text-transform: {{ cms.text_transform }}; color: {{ cms.text_color }}; background-color: {{ cms.bg_color }}; padding: {{ cms.padding_t }}px {{ cms.padding_r }}px {{ cms.padding_b }}px {{ cms.padding_l }}px;{% if cms.center %} margin: {{ cms.margin_y }}px auto;{% else %} margin: {{ cms.margin_y }}px {{ cms.margin_x }}px;{% endif %}; border: {{ cms.border_color }} {{ cms.border_width }}px solid; border-radius: {{ cms.border_radius }}px;"
  class="kleep-button"
  id="kleep-size-button"
  data-product-id="{{ product.id }}"
>
  <span class="kleep-wrapper-content">
    {% if cms.text_underline %}
      <span
        style="position: absolute; width: calc(100% + 2px); height: 1px; bottom: -{{ cms.text_underline_offset }}px; left: 0; background-color: {{ cms.text_color }};"
      ></span>
    {% endif %}

    {% if cms.image_url != blank %}
      <img
        height="{{ cms.image_size }}"
        width="{{ cms.image_size }}"
        src="{{ cms.image_url }}"
        loading="lazy"
        alt="Kleep button image"
      >
    {% endif %}

    <span class="kleep-btn-text">
      <span class="kleep-default">
        {% if cms.custom_button_text_toggle %}
          {{ cms.custom_find_size_text }}
        {% else %}
          {{ 'blocks.button.text.without_hash' | t }}
        {% endif %}
      </span>
      <span style="display: none;" class="kleep-custom">
        {% if cms.custom_button_text_toggle %}
          {{ cms.custom_recommended_size_text }}{% if localization.language.iso_code == "fr" %}&nbsp;{% endif %}<span class="kleep-colon">:</span>
        {% else %}
          {{ 'blocks.button.text.with_hash' | t }}{% if localization.language.iso_code == "fr" %}&nbsp;{% endif %}<span class="kleep-colon">:</span>
        {% endif %}
        <span class="kleep-custom-res"></span>
      </span>
    </span>
  </span>

  <span
    style="display: none; color: {{ cms.text_color }}; border-top-color: {{ cms.text_color }};"
    class="kleep-spinner"
    id="size-spinner"
  ></span>
</button>

Step 4: Add Settings Schema Add the following options to your Settings schema at the end of the section file:

Code

{
  "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": "Theme font",
  "info": "If checked, the css variable `--font-body-family` is used"
},
{
  "type": "font_picker",
  "id": "font_family",
  "label": "Font Family",
  "default": "helvetica_n4"
},
{
  "type": "select",
  "id": "text_style",
  "label": "Text style",
  "default": "normal",
  "options": [
    { "label": "Normal", "value": "normal" },
    { "label": "Italic", "value": "italic" },
    { "label": "Oblique", "value": "oblique" }
  ]
},
{
  "type": "select",
  "id": "text_transform",
  "label": "Text 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": "Text weight",
  "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": "Font size",
  "default": 16
},
{
  "type": "checkbox",
  "id": "text_underline",
  "label": "Text underline",
  "default": false
},
{
  "type": "range",
  "id": "text_underline_offset",
  "min": 1,
  "max": 20,
  "step": 1,
  "unit": "px",
  "label": "Underline offset",
  "default": 2
},
{
  "type": "color",
  "id": "text_color",
  "label": "Button text color",
  "default": "#ffffff"
},
{
  "type": "color",
  "id": "bg_color",
  "label": "Background color",
  "default": "#000000"
},
{
  "type": "color",
  "id": "border_color",
  "label": "Border color",
  "default": "#000000"
},
{
  "type": "range",
  "id": "border_width",
  "min": 0,
  "max": 8,
  "step": 1,
  "unit": "px",
  "label": "Border width",
  "default": 0
},
{
  "type": "header",
  "content": "Spacing"
},
{
  "type": "checkbox",
  "id": "center",
  "label": "Center the button",
  "default": false,
  "info": "This will override 'Horizontal margin'"
},
{
  "type": "range",
  "id": "margin_y",
  "min": 0,
  "max": 80,
  "step": 2,
  "unit": "px",
  "label": "Vertical margin",
  "default": 0
},
{
  "type": "range",
  "id": "margin_x",
  "min": 0,
  "max": 80,
  "step": 2,
  "unit": "px",
  "label": "Horizontal margin",
  "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": "Border radius",
  "default": 0
}

Step 5: Validate Validate updates in the Shopify Theme Customize area. Configure visuals within product information block settings. Optional: Secondary Button If you want to add a secondary button, create a new file named kleep-secondary-button.liquid within your snippets folder:

Code

<div class="kleep-secondary-button-box">
    <button
            type="button"
            style="{% if cms.kleep_font_family and cms.kleep_default_font_family == false %}font-family: '{{ cms.kleep_font_family }}' ;{% endif %}font-style: {{ cms.kleep_text_style }}; font-size: {{ cms.kleep_text_size }}px; font-weight: {{ cms.kleep_text_weight }}; text-transform: {{ cms.kleep_text_transform }}; color: {{ cms.kleep_text_color }}; background-color: {{ cms.kleep_bg_color }}; {% if cms.kleep_center %} margin: {{ cms.kleep_margin_y }}px auto;{% else %} margin: {{ cms.kleep_margin_y }}px {{ cms.kleep_margin_x }}px;{% endif %}; border: {{ cms.kleep_border_color }} {{ cms.kleep_border_width }}px solid; border-radius: {{ cms.kleep_border_radius }}px;"
            class="kleep-secondary-button"
            onclick="kleep_cta();"
            data-product-id="{{ product.id }}"
    >
    <span class="kleep-wrapper-content">
      {% if cms.kleep_text_underline %}
          <span style="position: absolute; width: calc(100% + 2px); height: 1px; bottom: -{{ cms.kleep_text_underline_offset }}px; left: 0; background-color: {{ cms.kleep_text_color }};"></span>
      {% endif %}

        {% if cms.kleep_image_url != blank %}
            <img height="{{ cms.kleep_image_size }}" width="{{ cms.kleep_image_size }}" src="{{ cms.kleep_image_url }}"
                 loading="lazy" alt="Kleep button image">
        {% endif %}

      <span class="kleep-secondary-btn-text">
        <span class="kleep-secondary-default">
          {{ 'kleep.button.text.without_hash' | t }}
        </span>
        <span style="display: none;" class="kleep-secondary-custom">
          {{ 'kleep.button.text.with_hash' | t }}:
          <span class="kleep-secondary-custom-res"></span>
        </span>
      </span>
    </span>

        <span
                style="display: none; color: {{ cms.kleep_text_color }}; border-top-color: {{ cms.kleep_text_color }};"
                class="kleep-secondary-spinner"
        ></span>
    </button>
</div>

Paste the following code where you want Kleep to appear. It must be part of Product info block within snippets folder.

Code

{% render 'kleep-secondary-button', cms: section.settings %}

12. Vintage Themes - Similar Products Setup

Step 1: Create the Snippet Create a file snippets/kleep-similar-button.liquid with the following code:

Code

{% 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 %}

<button
  type="button"
  class="kleep-similar-btn {{ block.settings.extra_classes }}"
  data-kleep-similar
  data-product-id="{{ product.id }}"
  {% if product.selected_or_first_available_variant %}
    data-variant-id="{{ product.selected_or_first_available_variant.id }}"
  {% endif %}
  style="
    display:none; align-items:center; gap:.5rem;
    {% if block.settings.center %}margin: {{ block.settings.margin_y }}px auto; justify-content:center;{% else %}margin: {{ block.settings.margin_y }}px {{ block.settings.margin_x }}px;{% endif %}
  "
>
  <span>
    {% if cms.custom_text != blank %}
      {{ cms.custom_text }}
    {% else %}
      {% if translated_similar_missing %}
        {{ 'kleep.recommended.text.btn' | t }}
      {% else %}
        {{ translated_similar }}
      {% endif %}
    {% endif %}
  </span>
</button>

Step 2: Render the Snippet Insert this line wherever you want the button to appear:

Code
```
{% render 'kleep-similar-button' %}
```

Typical placement: under the variant selectors or near the Add to Cart form. Step 3: Enable the Correct Mode Because vintage themes cannot insert OS 2.0 blocks, the widget must use one of:

custom_buttons
popup+custom
button+custom

Adding Multiple Buttons To create multiple buttons, simply place the snippet code in different areas of the product template:

Code
```
{% render 'kleep-similar-button' %}
```

Each snippet call creates an additional button. Every button automatically appears only when the selected variant is out of stock.

13. Translations (i18n)

Add the following translations to your theme locale files. English (en.json)

Code

{
  "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"
      }
    }
  }
}

French (fr.json)

Code

{
  "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"
      }
    }
  }
}

Italian (it.json)

Code

{
  "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"
      }
    }
  }
}

German (de.json)

Code

{
  "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"
      }
    }
  }
}

Spanish (es.json)

Code

{
  "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"
      }
    }
  }
}

Japanese (ja.json)

Code

{
  "kleep": {
    "button": {
      "text": {
        "without_hash": "自分に合うサイズを探す",
        "with_hash": "好みのサイズ"
      }
    },
    "recommended": {
      "text": {
        "btn": "類似商品を見る",
        "hint": "サイズがありません",
        "link": "類似商品を見る"
      }
    },
    "search": {
      "text": {
        "inputPlaceholder": "検索...",
        "productsBlockTitle": "商品",
        "clearButton": "クリア"
      }
    },
    "searchPage": {
      "text": {
        "header": "検索結果",
        "query": "検索結果",
        "submit": "検索",
        "input": "ストアを検索",
        "viewProduct": "商品を見る"
      }
    }
  }
}

Korean (ko.json)

Code

{
  "kleep": {
    "button": {
      "text": {
        "without_hash": "내 이상적인 사이즈 찾기",
        "with_hash": "추천 사이즈"
      }
    },
    "recommended": {
      "text": {
        "btn": "유사한 상품 보기",
        "hint": "사용 불가",
        "link": "유사한 상품 보기"
      }
    },
    "search": {
      "text": {
        "inputPlaceholder": "검색...",
        "productsBlockTitle": "상품",
        "clearButton": "지우기"
      }
    },
    "searchPage": {
      "text": {
        "header": "검색 결과",
        "query": "다음에 대한 결과",
        "submit": "검색",
        "input": "매장 검색",
        "viewProduct": "상품 보기"
      }
    }
  }
}

Portuguese (pt.json)

Code

{
  "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"
      }
    }
  }
}

14. Technical Reference

CTA Location on PDP The location is defined by DOM selectors inside KleepSDK.getConstants():

targetProductInfoBlockQueries – Array of selectors pointing to the main container of product details (title, price, sizes, etc.). The script iterates through these selectors and uses the first one it finds as the insertion point for the CTA or popups.
targetVariantQueries – Where size/variant options are. Once the product info block is found, the script searches inside it for variant elements (like size selectors). Each variant <label> (or equivalent) becomes a target for attaching the popup CTA.

Popup vs. Button (Desktop vs. Mobile) Device type is detected using checkIfMobile(): This function checks the browser’s navigator.userAgent string against a list of mobile devices (e.g., iPhone, Android, iPad).

Desktop: The CTA is displayed as hover popups next to the variant labels
Mobile: The script replaces hover popups with a single button, since hover interactions do not work on touch screens

Product Reference Configuration Kleep uses product references to match products across your catalog. Configure how to identify them: Reference Field: Where to find the brand’s product reference

Shopify SKU field
Metafield (specify which one)
Tags (with prefix, e.g., ref:ABC123)

Master Product Extraction: How to derive the master product ID from variant SKUs

Example: If variant SKUs are ABC123-S, ABC123-M, ABC123-L, the master product reference is ABC123
Rule: Take first 6 characters / Split by and take first part / Custom regex

Configure this in Kleep Dashboard → Settings → Product References. Customization Notes

Other variants of placement/layout are not provided beyond adjusting the selectors and CSS
To change appearance (colors, spacing, fonts, etc.), paste your CSS into the “Input custom CSS styles” box in the Kleep App Embed settings

15. Go-Live Checklist

Before going live, verify the following: Button Display

Button visible on at least 3 product pages
Button works on desktop AND mobile
No CSS conflicts (button not hidden or misaligned)
No Cumulative Layout Shift (CLS) issues — button doesn’t cause page jump
Vintage themes only: Commit referenced in version control

Data Quality

>98% of products have a size guide mapped
<1% of variants have missing measurements
0 orphan SKUs (products without category mapping)

Tracking

All 5 events firing correctly
Complete user journey tracked (button → recommendation → cart)
Payloads validated

Performance

JS errors < 1%
API latency P95 < 500ms
Monitoring in place

User Journey

Size guide opens correctly
Recommendations display properly
Add to cart works from size guide
Similar products display (if enabled)
Responsive on all devices

✅ Once all items are checked, notify your Kleep CSM for final QA validation before go-live.

16. Troubleshooting

The button doesn’t appear

☑️ Verify that the Kleep App Embed is enabled (toggle ON)
☑️ Make sure you saved the theme changes
☑️ Clear your browser cache and reload the page
☑️ Check that the product has size variants configured

Similar Products doesn’t appear

☑️ Check that the mode isn’t set to “Disabled” in settings
☑️ Buttons only appear when a variant is out of stock
☑️ For “custom” modes, verify you’ve added an App Block

Search isn’t working

☑️ Verify “Enable custom search” is enabled in the App Embed
☑️ Make sure you’ve added the Kleep Search block to the Search template
☑️ Check that the native search is hidden

I can’t find the Kleep App Blocks If you don’t see Kleep blocks in the “Apps” tab when clicking “Add block”, your theme is likely a vintage theme. Refer to Sections 11-12 for alternative installation instructions. Data mapping issues

☑️ Check that your product data contains the expected fields (tags, metafields, etc.)
☑️ Verify mappings in Kleep Dashboard → Settings → Data Mapping
☑️ Re-run the product scan to refresh detected values

Events not firing

☑️ Check browser console for JavaScript errors
☑️ Verify no ad-blockers or privacy extensions are blocking Kleep requests
☑️ Test in incognito mode

Contact Support If you encounter issues not listed here, contact the Kleep team:

📧 Email: support@kleep.ai

Thank you for using Kleep! 🎉

Our team is here to help you with installation and optimisation of your size guide.

Welcome

CMS

Mobile

Data

Shopify Integration Guide

1. Pre-Onboarding Checklist

2. Functionalities

3. Installation

5. Similar Products Feature

6. Kleep Search Feature

7. Returns Integration (Optional)

8. Event Tracking & Analytics

9. CSS Customization

10. Multiple Environments

10.5 CTA Button & Similar Products — Full Installation Guide

11. Vintage Themes - Size Guide Setup

12. Vintage Themes - Similar Products Setup

13. Translations (i18n)

14. Technical Reference

15. Go-Live Checklist

16. Troubleshooting

Thank you for using Kleep! 🎉

Welcome

CMS

Mobile

Data

​1. Pre-Onboarding Checklist

​2. Functionalities

​3. Installation

​5. Similar Products Feature

​6. Kleep Search Feature

​7. Returns Integration (Optional)

​8. Event Tracking & Analytics

​9. CSS Customization

​10. Multiple Environments

​10.5 CTA Button & Similar Products — Full Installation Guide

​11. Vintage Themes - Size Guide Setup

​12. Vintage Themes - Similar Products Setup

​13. Translations (i18n)

​14. Technical Reference

​15. Go-Live Checklist

​16. Troubleshooting

​Thank you for using Kleep! 🎉

1. Pre-Onboarding Checklist

2. Functionalities

3. Installation

5. Similar Products Feature

6. Kleep Search Feature

7. Returns Integration (Optional)

8. Event Tracking & Analytics

9. CSS Customization

10. Multiple Environments

10.5 CTA Button & Similar Products — Full Installation Guide

11. Vintage Themes - Size Guide Setup

12. Vintage Themes - Similar Products Setup

13. Translations (i18n)

14. Technical Reference

15. Go-Live Checklist

16. Troubleshooting

Thank you for using Kleep! 🎉