Klaro Documentation

To use Klaro on your website via CDN, you must embed both a configuration file and the Klaro script. Important: The configuration script must be loaded before the Klaro script.

Replace [klaro-version] with a specific version number (e.g., v0.5.30). Avoid using the latest tag to prevent breaking changes during updates.

If you prefer to provide your own styles, you can use klaro-no-css.js and include klaro.min.css separately.

<!-- make sure the config gets loaded before Klaro -->
<script defer type="text/javascript" src="config.js"></script>
<script defer type="text/javascript" src="https://cdn.kiprotect.com/klaro/[klaro-version]/klaro.js"></script>

Klaro manages translation synchronization by marking missing strings. If a translation is missing in a specific language file:

1. The key will exist but contain an empty string ''.
2. A helper key named [original_key]_en will be automatically added, containing the English translation for that key.

To fix a missing translation: Add the correct translation to the key and then delete the [original_key]_en helper key.

Klaro provides a set of React components that can be reused in your React projects.

Key characteristics:

• Relative Imports: All imports within the components are relative.
• Unstyled: The components do not load any default styles. This allows you to either import your own CSS or overwrite existing styles to match your project's design system.

For modern JavaScript projects (React, Vue, Angular, etc.), install Klaro as a Node module. The package provides several entry points depending on whether you want the UI, the CSS, or just the core logic.

• klaro: Full version including CSS.
• klaro/dist/klaro-no-css: Version without built-in CSS.
• klaro/dist/cm: The consent manager framework only (no UI components).

npm install klaro

// import Klaro with CSS
import * as klaro from 'klaro'

// import Klaro without CSS
import * as klaro from 'klaro/dist/klaro-no-css'

// import the accompanying CSS (requires style-loader)
import 'klaro/dist/klaro.css'

// import only the consent manager (no UI components)
import 'klaro/dist/cm'

To add a new translation string to Klaro, follow these steps to ensure it propagates correctly through the translation system:

1. Add the new string to en.ref.yml (the reference language).
2. Manually create a corresponding entry in en.yml.

Tip: You can append the |capitalize filter to a key to ensure the string is automatically capitalized across all supported Klaro languages.

To prevent third-party scripts from running before user consent, you must modify their HTML tags.

1. Change src to data-src.
2. Change type to text/plain.
3. Add data-type with the original type (e.g., text/javascript).
4. Add data-name which must match the name defined for that app in your Klaro configuration file.

This method also works for images, stylesheets, and other elements using src or type attributes.

<script type="text/plain"
    data-type="text/javascript"
    data-name="optimizely"
    data-src="https://cdn.optimizely.com/js/10196010078.js">
</script>

You can integrate Klaro into your project by importing it as a Node module via Webpack. By default, this setup uses the NPM version of Klaro.

To set up the development environment for this example:

1. Install dependencies using npm install.
2. Build the distribution files using npm run build.
3. Start the development server using npm run dev.

Once running, the Klaro consent manager will be available at http://localhost:9000 with a basic configuration.

If you are developing Klaro itself and want to use your local changes instead of the NPM version in a Webpack project, follow these steps:

1. Run npm install to install project dependencies.
2. Remove the existing NPM version of Klaro: rm -rf node_modules/klaro.
3. Create a symbolic link to your local Klaro directory: ln -s ../../.. node_modules/klaro (adjust the path to point to your local Klaro repository).
4. Crucial: Run make build inside the main Klaro directory to ensure the required distribution files are generated in the dist directory, which the Webpack configuration expects to import.

npm install
rm -rf node_modules/klaro
ln -s ../../.. node_modules/klaro
# Run this in the main Klaro directory:
make build

When loaded as a standard script, the API is available via the global klaro object. You can use the getManager() method to access the ConsentManager, which allows you to check consent status for specific services within your application logic.

// Check consent for a specific service before initializing it
let manager = klaro.getManager();
if (manager.getConsent('hotjar')) hotjar.initialize(HOTJAR_ID);

By default, Klaro opens automatically when the page loads. To trigger the consent modal manually (e.g., via a 'Change Settings' button), use klaro.show().

To force the modal to open even if the user has not yet made a choice (bypassing the initial consent notice), call klaro.show(undefined, true).