React Integration

Acest ghid arată cum să integrați banner-ul cookie al platformei într-o aplicație React, să useConsent pentru a obține consimțământul conștient și pentru a gestiona cerințele specifice Next.js.

Installation

npm install @probo/cookie-banner

Bannerul tematic este o componentă Web. Înregistrați-l o dată și plasați elementul personalizat în aspectul dvs.

Create a CookieBanner component

// src/components/CookieBanner.tsx
import { useEffect } from "react";
import { registerCookieBanner } from "@probo/cookie-banner";

let registered = false;

export function CookieBanner() {
  useEffect(() => {
    if (!registered) {
      registerCookieBanner();
      registered = true;
    }
  }, []);

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

Adăugați-l la layout-ul dvs. cu un link de setări

Render <CookieBanner /> o dată la rădăcina aplicației dvs., și locația <probo-settings-link> în antetul sau footer-ul dvs., astfel încât vizitatorii să poată redeschide preferințele:

// src/App.tsx
import { CookieBanner } from "./components/CookieBanner";

export default function App() {
  return (
    <>
      {/* your app */}
      <CookieBanner />
      <footer>
        <probo-settings-link>Cookie settings</probo-settings-link>
      </footer>
    </>
  );
}

Banner-ul se ocupă de tot de acolo – ia configurația, afișează dialogul de consimțământ atunci când este necesar și înregistrează consimțământul. sub CCPA dialogul începe închis; link-ul de setări afișează „Opțiunile dvs. de confidențialitate” cu pictograma oficială de renunțare și deschide panoul Opțiuni de confidențialitate.

TypeScript

Dacă TipScript se plânge de <probo-cookie-banner> JSX element, add a type declaration:

// src/probo.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    "probo-cookie-banner": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "banner-id": string;
        "base-url": string;
        position?:
          | "bottom-left"
          | "bottom-right"
          | "bottom-center"
          | "top-left"
          | "top-right"
          | "top-center";
        lang?: string;
      },
      HTMLElement
    >;
    "probo-settings-link": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement>,
      HTMLElement
    >;
    "probo-acknowledge-button": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement>,
      HTMLElement
    >;
    "probo-privacy-choices": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement>,
      HTMLElement
    >;
  }
}

The `useConsent` Hook

Use the Consent Manager API pentru a construi un hook React care oferă componentelor acces reactiv la starea de consimțământ.

// src/hooks/useConsent.ts
import { useSyncExternalStore } from "react";
import { getConsent } from "@probo/cookie-banner/consent";

const consent = getConsent();

function subscribe(onStoreChange: () => void): () => void {
  return consent.subscribe(onStoreChange);
}

function getSnapshot(): Record<string, boolean> {
  return consent.getAll();
}

function getServerSnapshot(): Record<string, boolean> {
  return {};
}

export function useConsent(): Record<string, boolean> {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

Această cârligă redă componenta ori de câte ori se schimbă starea consimțământului - la rezoluția inițială și după ce vizitatorul își actualizează preferințele.

Usage

import { useConsent } from "../hooks/useConsent";

export function AnalyticsLoader() {
  const consent = useConsent();

  if (!consent.analytics) {
    return null;
  }

  return <ThirdPartyAnalytics />;
}

Checking a single category

import { useConsent } from "../hooks/useConsent";

export function ChatWidget() {
  const consent = useConsent();

  if (!consent.functional) {
    return <p>Enable functional cookies to use live chat.</p>;
  }

  return <LiveChat />;
}

Pentru codul care rulează în afara ciclului de rendering al React – manageri de evenimente, efecte secundare sau module non-React – utilizați getConsent() direct în loc de hook:

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

export function trackEvent(name: string) {
  if (getConsent().has("analytics")) {
    analytics.track(name);
  }
}

See the Consent Manager API referință pentru întregul API.

Next.js

The cookie banner SDK accesses document, window, and localStorageÎn Next.js App Router, marcaţi componenta cu "use client":

// src/components/CookieBanner.tsx
"use client";

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

let registered = false;

export function CookieBanner() {
  useEffect(() => {
    if (!registered) {
      registerCookieBanner();
      registered = true;
    }
  }, []);

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

Then render it in your root layout:

// src/app/layout.tsx
import { CookieBanner } from "../components/CookieBanner";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <CookieBanner />
      </body>
    </html>
  );
}

The useConsent Hook funcționează în orice componentă client. Mark hooks care îl folosesc cu "use client" sau să le consume din componentele clientului:

// src/components/AnalyticsLoader.tsx
"use client";

import { useConsent } from "../hooks/useConsent";

export function AnalyticsLoader() {
  const consent = useConsent();

  if (!consent.analytics) {
    return null;
  }

  return <ThirdPartyAnalytics />;
}

Pages Router

În Router Pages, componenta banner funcţionează fără "use client". Render it in _app.tsx:

// pages/_app.tsx
import type { AppProps } from "next/app";
import { CookieBanner } from "../components/CookieBanner";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <CookieBanner />
    </>
  );
}

Headless Components

Pentru controlul complet al UI-ului de consimţământ în React, utilizaţi headless componentsÎnregistrați-le o dată și compuneți blocurile de construcție Web Component în JSX:

"use client";

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

let registered = false;

export function CustomConsentBanner() {
  useEffect(() => {
    if (!registered) {
      registerHeadlessComponents();
      registered = true;
    }
  }, []);

  return (
    <>
      <probo-cookie-banner-root
        banner-id="YOUR_BANNER_ID"
        base-url="https://your-probo-instance.com/api/cookie-banner/v1/"
      >
        <probo-banner>
          <div className="my-banner">
            <p>We use cookies to improve your experience.</p>
            <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>
            <probo-acknowledge-button>
              <button>Got it</button>
            </probo-acknowledge-button>
          </div>
        </probo-banner>

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

        <probo-privacy-choices>
          <div className="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>

      <probo-settings-link>Cookie settings</probo-settings-link>
    </>
  );
}

Use resolveLayout / resolveBannerText from @probo/cookie-banner/headless Pentru a demonstra controlul corect pentru OPT_IN, OPT_OUT, or NOTICE. See the JavaScript SDK docuri pentru referința completă a componentelor și Layout API.

Settings Link

Place <probo-settings-link> este necesar pentru toate încorporările – nu există un buton de setări plutitoare.

export function Footer() {
  return (
    <footer>
      <probo-settings-link>Cookie settings</probo-settings-link>
    </footer>
  );
}

Puneți eticheta implicită ca copii (vizualizați pentru vizitatorii non-CCPA). Sub CCPA, SDK înlocuiește întotdeauna conținutul cu eticheta legală „Opțiunile dvs. de confidențialitate” și pictograma oficială de renunțare și deschide panoul Opțiuni de confidențialitate.

probo-settings-link {
  font-size: 14px;
  color: #334155;
  text-decoration: underline;
}

See Settings link Comportamentul deplin prin reglementare.