JavaScript-API

JavaScript-API:n avulla oma koodisi voi lukea ja muuttaa suostumusta. Sama API on käytettävissä kahdella tavalla:

• Globaali Cookiesh-olio, jonka script-tagi luo. Käytä sitä tavallisilla HTML-sivuilla ja selaimen konsolissa.
• @cookiesh/js-paketti, tyypitetty kääre globaalin olion ympärille paketoiduille sovelluksille. Se toimii samalla tavalla ja sisältää TypeScript-määrittelyt.

npm install @cookiesh/js

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

Paketti ei lataa Cookieshista toista kopiota. Se odottaa script-tagia ja kutsuu globaalia oliota. Kaikki alla olevat esimerkit käyttävät pakettia, mutta Cookiesh.ready() ja cookiesh.ready() toimivat täsmälleen samoin.

Suostumustila

Useimmat metodit palauttavat tai ottavat vastaan ConsentState-olion:

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** Miten nykyinen tila on syntynyt. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** Tallennetun suostumustietueen satunnainen tunniste tai null ennen ensimmäistä valintaa. */
  consentId: string | null;
  /** Valinnan ajankohta ISO 8601 -muodossa tai null ennen ensimmäistä valintaa. */
  timestamp: string | null;
  bannerVersion: string;
  /** Alue, johon sääntö osui, kuten "FR" tai "US-CA". */
  region: string;
}

Ennen kuin kävijä tekee valinnan, method on default ja kategoriat vastaavat alueen oletustilaa. Ennakkosuostumusta edellyttävillä alueilla kaikki paitsi necessary on siis false.

Suostumuksen lukeminen

ready()

ready(): Promise<ConsentState>

Ratkeaa heti, kun Cookiesh tietää suostumustilan: palaaville kävijöille välittömästi ja uusille alueen tunnistamisen jälkeen. Se ei odota, että kävijä napsauttaa banneria. Käytä sitä suostumuksesta riippuvan koodin käynnistämiseen:

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

getConsent()

getConsent(): ConsentState | null

Palauttaa nykyisen tilan synkronisesti tai null, jos Cookiesh ei ole vielä latautunut. Käytä mieluummin ready()-metodia, ellet ole varma, että skripti on latautunut.

hasConsent(category)

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

Oikotie yhden kategorian tarkistamiseen. Palauttaa false, kunnes Cookiesh on latautunut.

Suostumuksen muuttaminen

Nämä metodit tallentavat uuden suostumustietueen täsmälleen samoin kuin jos kävijä olisi käyttänyt banneria. Kutsu niitä vain kävijän selkeän toiminnon seurauksena, esimerkiksi kun hän napsauttaa jotain omalla asetussivullasi.

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

// Oma valintakytkin tilisi asetussivulla
await cookiesh.setConsent({ analytics: event.target.checked });

Kategoriat, jotka jätät pois, säilyttävät nykyisen arvonsa. necessary-kategoriaa ei voi muuttaa.

Käyttöliittymän näyttäminen

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

showBanner() näyttää ensimmäisen tason bannerin uudelleen, vaikka kävijä olisi jo tehnyt valintansa. openPreferences() avaa asetuskeskuksen, jossa on kategoriakohtaiset valintakytkimet ja evästeluettelo. close() sulkee kumman tahansa tallentamatta.

Kirjautuneet käyttäjät

Oletuksena suostumus tallennetaan selainkohtaisesti. Kirjautumista edellyttävissä tuotteissa voit liittää sen käyttäjätunnisteeseesi, jolloin valinta seuraa käyttäjää laitteelta toiselle:

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

// Kirjautumisen jälkeen
await cookiesh.identify(session.user.id);

// Uloskirjautumisen jälkeen
cookiesh.reset();

identify() hakee käyttäjän viimeisimmän valinnan. Jos sellainen on, Cookiesh ottaa sen käyttöön tällä laitteella eikä näytä banneria. Jos kävijä teki valinnan ennen kirjautumista, valinta tallennetaan käyttäjälle. Cookiesh tallentaa välittämästäsi tunnisteesta vain suolatun tiivisteen, ei koskaan itse tunnistetta. Käytä läpinäkymätöntä sisäistä tunnistetta, älä sähköpostiosoitetta.

reset() poistaa linkin käyttäjään mutta säilyttää nykyisen valinnan tällä laitteella.

Script-tagin attribuutit

Script-tagi määritetään data--attribuuteilla:

Attribuutti	Oletus	Kuvaus
data-site-id	Pakollinen	Sivustosi tunniste, kuten ck_live_8f2a91
data-language	Automaattinen	Pakottaa bannerin kielen (katso Bannerin mukauttaminen)
data-auto-block	true	Aseta arvoksi false, jos haluat estää vain itse merkitsemäsi skriptit
data-nonce	Ei mitään	CSP-nonce, joka lisätään Cookieshin vapauttamiin skripteihin
data-consent-mode	true	Aseta arvoksi false, jos et halua lähettää Google Consent Mode -signaaleja

Virheenkorjaus

Cookiesh.debug(): void

Suorita se selaimen konsolissa, niin se tulostaa tunnistetun alueen, osuneen säännön, bannerin version, jokaisen estetyn skriptin ja kaikkien kategorioiden nykyisen tilan. Metodi on käytettävissä vain globaalissa oliossa.