JavaScripti API

JavaScripti API võimaldab sinu enda koodil nõusolekut lugeda ja muuta. Sama API on saadaval kahel viisil:

• Globaalne objekt Cookiesh, mille loob skriptimärgend. Kasuta seda tavalistel HTML-lehtedel ja brauseri konsoolis.
• Pakett @cookiesh/js, tüübitud ümbris globaalse objekti ümber komplekteeritud rakenduste jaoks. See töötab samamoodi ja sisaldab TypeScripti tüübimääratlusi.

npm install @cookiesh/js

import { cookiesh } from '@cookiesh/js';

Pakett ei laadi Cookieshist teist koopiat. See ootab skriptimärgendit ja kutsub välja globaalset objekti. Kõik allolevad näited kasutavad paketti, kuid Cookiesh.ready() ja cookiesh.ready() käituvad täpselt ühtemoodi.

Nõusoleku olek

Enamik meetodeid tagastab või võtab vastu objekti ConsentState:

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** Kuidas praegune olek tekkis. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** Salvestatud nõusolekukirje juhuslik ID või null enne esimest valikut. */
  consentId: string | null;
  /** Valiku aeg ISO 8601 vormingus või null enne esimest valikut. */
  timestamp: string | null;
  bannerVersion: string;
  /** Piirkond, millele reegel vastas, näiteks "FR" või "US-CA". */
  region: string;
}

Enne kui külastaja valiku teeb, on method väärtusega default ja kategooriad kajastavad piirkonna vaikeolekut. Eelneva nõusoleku piirkondades tähendab see, et kõik peale necessary on false.

Nõusoleku lugemine

ready()

ready(): Promise<ConsentState>

Laheneb kohe, kui Cookiesh teab nõusoleku olekut: naasvate külastajate puhul kohe ja uute puhul pärast piirkonna tuvastamist. See ei oota, kuni külastaja bänneril klõpsab. Kasuta seda nõusolekust sõltuva koodi käivitamiseks:

const consent = await cookiesh.ready();
if (consent.analytics) initAnalytics();

getConsent()

getConsent(): ConsentState | null

Tagastab praeguse oleku sünkroonselt või null, kui Cookiesh pole veel laadimist lõpetanud. Eelista ready(), kui sa pole kindel, et skript on laaditud.

hasConsent(category)

hasConsent(category: 'necessary' | 'preferences' | 'analytics' | 'marketing'): boolean

Otsetee ühe kategooria kontrollimiseks. Tagastab false, kuni Cookiesh on laaditud.

Nõusoleku muutmine

Need meetodid salvestavad uue nõusolekukirje täpselt nii, nagu oleks külastaja kasutanud bännerit. Kutsu neid ainult vastusena külastaja selgele tegevusele, näiteks klõpsule sinu enda seadete lehel.

acceptAll(): Promise<ConsentState>
rejectAll(): Promise<ConsentState>
setConsent(choices: Partial<Record<'preferences' | 'analytics' | 'marketing', boolean>>): Promise<ConsentState>

// Kohandatud lüliti sinu konto seadete lehel
await cookiesh.setConsent({ analytics: event.target.checked });

Välja jäetud kategooriad säilitavad oma praeguse väärtuse. Kategooriat necessary muuta ei saa.

Kasutajaliidese kuvamine

showBanner(): void
openPreferences(): void
close(): void

showBanner() näitab esimese tasandi bännerit uuesti, isegi kui külastaja on juba valiku teinud. openPreferences() avab eelistuste keskuse kategooriapõhiste lülitite ja küpsiste loeteluga. close() sulgeb kumma tahes neist ilma salvestamata.

Sisselogitud kasutajad

Vaikimisi salvestatakse nõusolek brauseripõhiselt. Sisselogimisega toodetes seo see oma kasutaja ID-ga, et valik liiguks kasutajaga seadmete vahel kaasa:

identify(userId: string): Promise<ConsentState>
reset(): void

// Pärast sisselogimist
await cookiesh.identify(session.user.id);

// Pärast väljalogimist
cookiesh.reset();

identify() otsib üles kasutaja viimase valiku. Kui see on olemas, rakendab Cookiesh selle selles seadmes ja jätab bänneri vahele. Kui külastaja tegi valiku enne sisselogimist, salvestatakse see valik kasutaja jaoks. Cookiesh salvestab ainult edastatud ID soolatud räsi, mitte kunagi ID-d ennast. Kasuta läbipaistmatut sisemist ID-d, mitte e-posti aadressi.

reset() eemaldab seose kasutajaga, kuid jätab praeguse valiku sellesse seadmesse alles.

Skriptimärgendi atribuudid

Skriptimärgendit seadistatakse data- atribuutidega:

Atribuut	Vaikeväärtus	Kirjeldus
data-site-id	Kohustuslik	Sinu saidi ID, näiteks ck_live_8f2a91
data-language	Automaatne	Määrab bänneri keele (vaata Bänneri kohandamine)
data-auto-block	true	Määra false, et blokeerida ainult skriptid, mille oled ise märgistanud
data-nonce	Puudub	CSP nonce, mida rakendatakse skriptidele, mille Cookiesh blokeeringust vabastab
data-consent-mode	true	Määra false, et lõpetada Google Consent Mode’i signaalide saatmine

Silumine

Cookiesh.debug(): void

Käivita see brauseri konsoolis, et kuvada tuvastatud piirkond, sobinud reegel, bänneri versioon, iga blokeeritud skript ja iga kategooria praegune olek. See on saadaval ainult globaalsel objektil.