React Integration

Acest ghid arată cum să integrați banner-ul cookie-ului platformei într-o aplicație React, să construiți o legătură useConsent pentru rendering-ul conștient de consimțământ și să gestionați cerințele specifice Next.js.

Installation

npm install @probo/cookie-banner

Rendering the Themed Banner

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

1. 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"
       />
     );
   }

2. 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 plasați <probo-settings-link> în antet sau footer, 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ă TypeScript se plânge de elementul <probo-cookie-banner> JSX, adăugați o declarație de tip:

src/the platform.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
    >;
  }
}

, HTMLElement >; "the platform-acknowledge-button": React.DetailedHTMLProps< React.HTMLAttributes, HTMLElement >; "the platform-privacy-choices": React.DetailedHTMLProps< React.HTMLAttributes, 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 />;
}

Imperative Consent Checks

Pentru codul care rulează în afara ciclului de rendering al React – manageri de evenimente, efecte secundare sau module non-React – utilizați ___ZBT_I18N_RUNTIME_BLOCK_187__ direct în loc de cârlig:

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 întregulAPI.

Next.js

Banner-ul cookie SDK accesează document, window, și localStorage, deci trebuie să funcționeze pe client. Î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>
  );
}

Hook-ul useConsent funcționează în orice componentă client. Marcați hook-urile care îl folosesc cu "use client" sau le consumă din componentele client:

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". Redă-l în _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>
    </>
  );
}

Utilizați resolveLayout / resolveBannerText de la @probo/cookie-banner/headless pentru a afișa controalele corecte pentru OPT_IN, OPT_OUT sau NOTICE. JavaScript SDK docuri pentru referința completă a componentelor și Layout API.

Settings Link

Plasați <probo-settings-link> în antet sau footer. Este necesar pentru toate încorporările - nu există niciun 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.