JavaScript SDK

The @probo/cookie-banner SDK este o bibliotecă JavaScript ușoară, fără dependență, construită pe Componente Web. Renderizează interfața de utilizator a consimțământului, gestionează starea consimțământului vizitatorului, comunică cu platforma API și activează resurse terțe pe baza consimțământului.

Există trei modalități de a utiliza SDK-ul, în funcție de nevoile dvs.:

Script Tag (No Bundler)

The simplest option. Add a single <script> Etichetați-vă HTML - nu sunt necesare instrumente de construcție:

<script
  src="https://unpkg.com/@probo/cookie-banner/dist/cookie-banner.iife.js"
  data-banner-id="YOUR_BANNER_ID"
  data-base-url="https://your-probo-instance.com/api/cookie-banner/v1/"
  data-position="bottom-left"
></script>

<!-- Required: reopen control in the header or footer -->
<probo-settings-link>Cookie settings</probo-settings-link>

Acest lucru generează automat un dialog de consimțământ complet stilat. <probo-settings-link> în header-ul sau footer-ul dvs., astfel încât vizitatorii să poată redeschide preferințele Settings link.

Attribute	Required	Description
`data-banner-id`	Yes	ID-ul bannerului dvs. de pe consola platformă
`data-base-url`	Yes	Bannerul cookie al platformei API bază URL
`data-position`	No	Banner card position: `bottom-left` (default), `bottom-right`, `bottom-center`, `top-left`, `top-right`, or `top-center`
`data-lang`	No	Force a specific language (e.g. `"fr"`Atunci când este omis, SDK-ul detectează automat pagina sau browser-ul. Language Detection.

Pentru aplicațiile grupate (React, Vue, Svelte, Next.js etc.), importați banner-ul tematic ca modul ES:

npm install @probo/cookie-banner

Înregistrați componenta și plasați-o în HTML sau șablon:

import { registerCookieBanner } from "@probo/cookie-banner";

registerCookieBanner();

<probo-cookie-banner
  banner-id="YOUR_BANNER_ID"
  base-url="https://your-probo-instance.com/api/cookie-banner/v1/"
  position="bottom-left"
></probo-cookie-banner>

<!-- Required: reopen control in the header or footer -->
<probo-settings-link>Cookie settings</probo-settings-link>

Attribute	Required	Description
`banner-id`	Yes	ID-ul bannerului dvs. de pe consola platformă
`base-url`	Yes	Bannerul cookie al platformei API bază URL
`position`	No	Banner card position: `bottom-left` (default), `bottom-right`, `bottom-center`, `top-left`, `top-right`, or `top-center`
`lang`	No	Force a specific language (e.g. `"fr"`Atunci când este omis, SDK-ul detectează automat pagina sau browser-ul. Language Detection.

Deoarece aceasta este o componentă Web, funcționează în orice cadru. În React, JSX o tratează ca pe un element personalizat. În Vue sau Svelte, utilizați-o direct în șablon. React Integration Ghid pentru o plimbare completă cu o useConsent Hook, setarea Next.js și declarațiile TypeScript.

See Theming pentru cum să personalizați culorile, fonturile și stilul.

Pentru acces programatic la starea de consimțământ din orice modul (nu doar DOM), consultați Consent Manager API.

Headless Components (Full Control)

Pentru un control complet asupra UI-ului de consimțământ, utilizați componentele fără cap. Acestea sunt blocuri de construcție a componentelor Web ne-stilizate pe care le compuneți și le stilizați singuri:

import { registerHeadlessComponents } from "@probo/cookie-banner/headless";

registerHeadlessComponents();

Then build your own layout:

<probo-cookie-banner-root banner-id="YOUR_BANNER_ID" base-url="BASE_URL">
  <probo-banner>
    <div class="my-banner">
      <p data-text="banner_description">We use cookies to improve your experience.</p>
      <!-- Opt-in / opt-out primary actions -->
      <probo-accept-button>
        <button>Accept all</button>
      </probo-accept-button>
      <probo-reject-button>
        <button>Reject all</button>
      </probo-reject-button>
      <probo-customize-button>
        <button>Customize</button>
      </probo-customize-button>
      <!-- Notice presentation (APPI, Mexico, unregulated): single dismiss -->
      <probo-acknowledge-button>
        <button>Got it</button>
      </probo-acknowledge-button>
    </div>
  </probo-banner>

  <probo-preference-panel>
    <div class="my-preferences">
      <probo-category-list>
        <template>
          <div class="category">
            <span data-slot="name"></span>
            <span data-slot="description"></span>
            <probo-category-toggle>
              <input type="checkbox" />
            </probo-category-toggle>
          </div>
          <probo-cookie-list>
            <template>
              <div class="cookie">
                <span data-slot="name"></span>
                <span data-slot="type"></span>
                <span data-slot="duration"></span>
              </div>
            </template>
          </probo-cookie-list>
        </template>
      </probo-category-list>
      <probo-save-button>
        <button>Save preferences</button>
      </probo-save-button>
    </div>
  </probo-preference-panel>

  <!-- CCPA only: shown when state is privacy_choices -->
  <probo-privacy-choices>
    <div class="my-privacy-choices">
      <probo-reject-button>
        <button>Do Not Sell or Share My Personal Information</button>
      </probo-reject-button>
    </div>
  </probo-privacy-choices>
</probo-cookie-banner-root>

<!-- Required outside the root (header or footer) -->
<probo-settings-link>Cookie settings</probo-settings-link>

Use resolveLayout / resolveBannerText pentru a afișa butoanele potrivite și a copia pentru prezentarea activă (OPT_IN, OPT_OUT, or NOTICE).

Component Reference

Component	Description
`<probo-cookie-banner-root>`	Root element. Requires `banner-id` and `base-url`. Optional `lang` atribut pentru a forța o limbă. Gestionează ciclul de viață și starea clientului.
`<probo-banner>`	Container pentru cardul de banner din primul strat. vizibilitatea urmează `layout.initial_state` (e.g. closed under CCPA — see Settings link).
`<probo-accept-button>`	Wraps a button that records `ACCEPT_ALL` consent.
`<probo-reject-button>`	Wraps a button that records `REJECT_ALL` consent (opt-out / Do Not Sell).
`<probo-customize-button>`	Înfășoară un buton care deschide panoul de preferințe.
`<probo-acknowledge-button>`	Wraps a button that records `ACKNOWLEDGE` for NOTICE Prezentări (dezafectare informativă). Nu reutilizați accept-toate pentru acest lucru.
`<probo-preference-panel>`	Container for per-category consent toggles.
`<probo-privacy-choices>`	Suprafața opțiunilor de confidențialitate CCPA (opt-out de vânzare/partajare + declarație de drepturi de proprietate intelectuală sensibilă). `privacy_choices`.
`<probo-category-list>`	Renders a `<template>` once per cookie category. Fills `data-slot="name"` and `data-slot="description"`.
`<probo-category-toggle>`	Conectează caseta de verificare din interiorul acesteia la starea de consimțământ a categoriei.
`<probo-cookie-list>`	Renders a `<template>` once per cookie in the category. Fills `data-slot="name"`, `data-slot="type"`, and `data-slot="duration"`.
`<probo-save-button>`	Înfășoară un buton care salvează proiectul de preferințe curent.
`<probo-settings-link>`	Required header/footer reopen control. Click target vine de la `layout.reopen_state`. See Settings link.

Layout API

De la 0,12 înainte, API returnează o layout Integratorii fără cap ar trebui să o citească în loc să se ramifice pe regulation or consent_mode:

import {
  resolveLayout,
  resolveBannerText,
} from "@probo/cookie-banner"; // or "@probo/cookie-banner/headless"

document.addEventListener("probo-ready", (e) => {
  const { config } = e.detail;
  const layout = resolveLayout(config);
  // layout.presentation: "OPT_IN" | "OPT_OUT" | "NOTICE"
  // layout.initial_state / layout.reopen_state: "banner" | "panel" | "privacy_choices" | "hidden"
  // layout.buttons: which actions to show
  // layout.settings_link: "default" | "ccpa_privacy_choices"

  const copy = resolveBannerText(config);
  // copy.title, copy.description, copy.primaryButton, copy.secondaryButton?
});

If layout lipsește, SDK-ul înregistrează o eroare și cade înapoi la strict opt-in - ceea ce înseamnă că un backend de platformă găzduit independent este mai vechi decât probod v0.246.0Actualizarea probod atunci când vedeți acest avertisment.

Settings link

<probo-settings-link> este singurul control de redeschidere. Plasați-l în antetul sau footer-ul site-ului pentru fiecare încorporat (script tag, tematic sau fără cap). Dacă lipsește, SDK-ul emite un soft probo-validation warning — without it visitors cannot reopen preferences.

<style>
  /* Style the host — typography still applies after CCPA replaces the children */
  probo-settings-link {
    font-size: 14px;
    color: #334155;
    text-decoration: underline;
  }
</style>

<footer>
  <probo-settings-link>Cookie settings</probo-settings-link>
</footer>

Comportamentul prin prezentare/reglementare (dreptat de layout):

Presentation	Typical regulations	Label shown	Banner on first visit	Click opens
OPT_OUT (CCPA)	CCPA / CPRA	Întotdeauna înlocuită cu legea „Opțiunile dvs. de confidențialitate” text and official opt-out icon (English; not translated)	Closed by default	Privacy Choices panel (`privacy_choices`)
OPT_OUT (other)	PIPEDA, LGPD	Copiii dumneavoastră (de exemplu „Setări cookie”), sau un feedback localizat dacă este gol	Closed by default	Compact opt-out banner
OPT_IN	GDPR, UK GDPR, FADP, …	Copiii tăi, sau o cădere localizată dacă este goală	Open until the visitor chooses	Preference panel
NOTICE	APPI, LFPDPPP, unregulated countries	Copiii tăi, sau o cădere localizată dacă este goală	Open (informational dismiss)	Notice banner again

Atunci când a fost aplicat un semnal de opțiune de renunțare la Global Privacy Control (GPC), link-ul de setări poate afișa o mică GPC honored Blocare lângă etichetă.

The themed embed mounts <probo-privacy-choices> pentru opt-out layout-uri, dar Reapariția la această suprafață este CCPA-numai (layout.reopen_state = privacy_choicesAlte regimuri de excludere redeschid banner-ul compact. integratorii fără cap ar trebui să includă <probo-privacy-choices> legătura de setări găsește automat rădăcina bannerului pentru toate cele trei metode de integrare.

Style probo-settings-link însuşi pentru dimensiunea şi culoarea fonturilor – nu pentru copii interni. Sub CCPA, SDK-ul înlocuieşte copiii, dar stilurile gazdă se aplică în continuare. 1em.

Language Detection

SDK rezolvă automat limba vizitatorului folosind următoarea prioritate:

Explicit attribute — The lang atribut pe componenta (sau data-lang pe scenariu Tag)
Page language — The lang Atributele de pe <html> element, utilizând subtag-ul limbajului de bază (de ex. fr from fr-FR)
Browser language — The browser’s navigator.language, using the base subtag
Default language — Limba implicită a banner-ului configurată în consolă (default en)

Limba rezolvată este trimisă la API atunci când se colectează configurația bannerului.API returnează toate textul UI, numele categoriilor și descrierile în limba rezolvată. Dacă nu există traducere pentru acea limbă, API revine la limba implicită a bannerului.

Built-in Languages

Noile bannere includ traduceri pentru aceste limbi:

Code	Language	Code	Language
`en`	English	`nl`	Dutch
`de`	German	`pl`	Polish
`es`	Spanish	`pt`	Portuguese
`fr`	French	`tr`	Turkish
`id`	Indonesian	`uk`	Ukrainian
`it`	Italian	`zh`	Chinese
`ja`	Japanese
`ko`	Korean

Puteți personaliza aceste traduceri și puteți adăuga noi limbi din consola de platformă.

Titlul și descrierea bannerului (inclusiv variantele de excludere și notificare)
Etichete de buton (acceptați toate, respingeți toate, personalizați, salvați, respingeți / recunoașteți)
Preference panel title and description
Cookie detail labels (type, description, duration)
ARIA accessibility labels
Privacy policy / cookie policy link text
Textul de localizare a conținutului (se afișează atunci când resursele sunt blocate)
Duration labels (years, months, days, persistent, etc.)

Forcing a Language

Pentru a renunța la auto-detectare, setați limba în mod explicit:

Script tag:

<script
  src="https://unpkg.com/@probo/cookie-banner/dist/cookie-banner.iife.js"
  data-banner-id="YOUR_BANNER_ID"
  data-base-url="https://your-probo-instance.com/api/cookie-banner/v1/"
  data-lang="de"
></script>

Themed banner:

<probo-cookie-banner
  banner-id="YOUR_BANNER_ID"
  base-url="https://your-probo-instance.com/api/cookie-banner/v1/"
  lang="de"
></probo-cookie-banner>

Headless components:

<probo-cookie-banner-root
  banner-id="YOUR_BANNER_ID"
  base-url="https://your-probo-instance.com/api/cookie-banner/v1/"
  lang="de"
>
  <!-- ... -->
</probo-cookie-banner-root>

Matching the Page Language

În cele mai multe cazuri, nu este necesar să setați în mod explicit o limbă. lang Atributele de pe <html> element, the SDK picks it up automatically:

<html lang="fr"></html>

Aceasta este abordarea recomandată pentru site-urile multilingve care lang atribut ca parte a setării lor i18n.

Events

SDK emite evenimente personalizate care bulează prin DOM. Ascultați elementul rădăcină sau orice strămoș:

Event	Detail	Description
`probo-ready`	`{ config, gpcApplied, regulation }`	Se aprinde atunci când este încărcată configurația bannerului. `config` includes `language`, `default_language`, `texts`, `layout`, `consent_mode`, `regulation`, `cookie_policy_url`, and categories. `gpcApplied` is `true` if a GPC opt-out was applied.
`probo-state`	`{ state, prev }`	Deschisă atunci când starea bannerului UI se schimbă. `loading`, `banner`, `panel`, `privacy_choices`, `hidden`.
`probo-consent`	`{ action, consent_data }`	Concediat după înregistrarea consimţământului. acţiuni: `ACCEPT_ALL`, `REJECT_ALL`, `CUSTOMIZE`, `GPC`, `ACKNOWLEDGE`.
`probo-validation`	`{ missing }`	Soft composition warning (e.g. missing `<probo-settings-link>`). Does not block load.

document.addEventListener("probo-consent", (e) => {
  console.log("Consent action:", e.detail.action);
});

Client-side: A probo_consent Cookie-ul stochează starea de consimțământ a vizitatorului. max-age este setat la expirarea consimţământului configurat pe banner (în zile). SameSite=Lax.
Server-side: Fiecare acțiune de consimțământ este înregistrată prin intermediul platformei API cu versiunea banner, ID-ul vizitatorului, tipul de acțiune, adresa IP anonimizată și agentul de utilizator. adresele IP sunt anonimizate înainte de stocare (IPv4 ultimul octet zero, IPv6 mascat la /48) – IP-ul complet nu persistă niciodată. Audit Trail pentru lista completă a câmpurilor stocate.
Visitor identity: SDK generează un ID aleator de vizitator și îl stochează în localStorageAcest ID este folosit pentru a căuta consimțământul existent atunci când vizitatorul se întoarce.
Offline resilience: În cazul în care API este inaccesibil în momentul înregistrării consimțământului, cererea este în coadă în localStorage și retrasă automat la următoarea încărcare a paginii.

Integrations

SDK-urile sunt dotate cu integrări încorporate care sincronizează automat statutul de consimțământ cu serviciile terțelor părți. Integrările sunt activate în mod implicit – acestea sunt activate numai atunci când sunt configurate steagurile corespunzătoare pe categoriile de cookie-uri din consola platformei.

The SDK pushes Google Consent Mode v2 signals to gtag() or dataLayerpăstrarea etichetelor Google în sincronizare cu consimțământul vizitatorului.

How it works:

La încărcare, SDK trimite o consent("default", ...) care stabilește toate tipurile de consimțământ configurate pentru "denied".
Când vizitatorul face o alegere, SDK-ul trimite o consent("update", ...) call with "granted" or "denied" pentru fiecare tip de consimțământ bazat pe alegerile per categorie ale vizitatorului.

Configurarea este condusă de GCM consent types câmp pe fiecare categorie de cookie-uri din consola de platformă. Mapă categorii la tipuri de consimțământ Google cum ar fi analytics_storage, ad_storage, ad_user_data, or ad_personalizationCategoriile fără tipurile de consimțământ GCM configurate sunt ignorate.

The integration detects window.gtag or window.dataLayer Dacă nici unul dintre ele nu este prezent, nu face nimic.

PostHog

PostHog nu este sincronizat automat de către SDK – dar Consent Manager API vă oferă tot ce aveți nevoie pentru a vă conecta în câteva rânduri și pentru a respecta GDPR, CCPA și celelalte reglementări pe care le gestionează banner-ul.

See the dedicated guides:

Cum să configurați PostHog: GDPR, CCPA și legile globale privind confidențialitatea — setarea fără cookie-uri vs. consimțământ conștient, cu un exemplu minim de lucru pentru fiecare.
PostHog feature flags behind a cookie banner – să evalueze steagurile numai după consimțământul analitic și identify(), și de ce Track 2 ar trebui să folosească întotdeauna cookieless_mode: "on_reject".

O integrare completă a funcționării (inclusiv o demonstrație a drapelului caracteristicii cu consimțământ) trăiește în cookie-banner-react example.