Dokumentācija

CookiePilot izstrādātāju dokumentācija

API, notikumi, integrācijas ar GTM

Ievads

CookiePilot ir sīkdatņu piekrišanas pārvaldības platforma (CMP), kas atbilst Vispārīgajai datu aizsardzības regulai (VDAR), Elektronisko sakaru likumam un Google Consent Mode v2 prasībām. Šo regulējumu Latvijā uzrauga Datu valsts inspekcija (DVI).

Kam paredzēts

  • Vietņu īpašniekiem: ieviešana bez programmēšanas.
  • Izstrādātājiem: API, notikumi, integrācijas ar GTM.
  • Aģentūrām: white-label risinājums, vairāku domēnu pārvaldība.

Ātrā darba sākšana

1. solis: Reģistrācija

  1. Izveidojiet kontu vietnē app.cookiepilot.io/register.
  2. Pievienojiet domēnu vadības panelī un nokopējiet API atslēgu (formāts cp_live_...).

2. solis: Koda instalēšana

Tieša instalēšana ir divi skripti <head> sadaļā, šādā secībā.

2.a solis: Noklusētā piekrišana (inline stub). Ievietojiet to kā pirmo, pirms jebkura cita skripta (cookiepilot.js, GA, GTM, reklāmu un izsekošanas tagi):

<script>"use strict";(function(){window.dataLayer=window.dataLayer||[];var d={ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"granted",wait_for_update:500},h=false;try{for(var i=0;i<window.dataLayer.length;i++){var x=window.dataLayer[i];if(x&&x[0]==="consent"&&x[1]==="default"){h=true;break}}}catch(err){}if(!h&&window.dataLayer.length)window.dataLayer.unshift(["consent","default",d]);window.gtag=function(){window.dataLayer.push(arguments)};if(!h)window.gtag("consent","default",d);var a=document.cookie.match(/(^|)cookiepilot_consent=([^;]+)/);if(a){try{var e=JSON.parse(decodeURIComponent(a[2]));window.gtag("consent","update",{analytics_storage:e.analytics?"granted":"denied",ad_storage:e.marketing?"granted":"denied",ad_user_data:e.marketing?"granted":"denied",ad_personalization:e.marketing?"granted":"denied",functionality_storage:e.preferences?"granted":"denied",personalization_storage:e.preferences?"granted":"denied",security_storage:"granted"})}catch(err){}}})();</script>

Šis inline fragments uzreiz iestata visas kategorijas uz denied (ar wait_for_update: 500), tāpēc Google Consent Mode v2 noklusētais stāvoklis ir gatavs vēl pirms tam, kad ielādējas jebkas cits. Atgriežoties lietotājam tas uzreiz nolasa saglabāto piekrišanu no sīkdatnes un nosūta consent update.

2.b solis: Bannera skripts. Pievienojiet uzreiz pēc inline stub:

<!-- CookiePilot -->
<script async src="https://cdn.cookiepilot.io/cookiepilot.js" data-cpkey="TWOJ_KLUCZ"></script>

3. solis: Bannera konfigurācija

Vadības panelī: Domēns → Konfigurācija → Izskats:

  • bannera novietojums (augšā, apakšā, modālajā logā),
  • krāsas un teksti,
  • peldošā poga "Sīkdatņu iestatījumi" atgriežošajiem lietotājiem.

Integrācija ar Google Tag Manager

Izmantojot GTM, CookiePilot instalējat ar vienu Custom HTML tagu, kas uzreiz iestata noklusēto piekrišanu un ielādē banneri pašā agrākajā GTM fāzē. Atsevišķs stub fails vai otrs tags nav nepieciešams.

Tags: CookiePilot - Consent Init + Banner

GTM izveidojiet Custom HTML tagu (Tags → New → Custom HTML) un ielīmējiet:

<script>"use strict";
(function() {
window.dataLayer=window.dataLayer||[];var d={ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"granted",wait_for_update:500},h=false;try{for(var i=0;i<window.dataLayer.length;i++){var x=window.dataLayer[i];if(x&&x[0]==="consent"&&x[1]==="default"){h=true;break}}}catch(err){}if(!h&&window.dataLayer.length)window.dataLayer.unshift(["consent","default",d]);window.gtag=function(){window.dataLayer.push(arguments)};if(!h)window.gtag("consent","default",d);var a=document.cookie.match(/(^|)cookiepilot_consent=([^;]+)/);if(a){try{var e=JSON.parse(decodeURIComponent(a[2]));window.gtag("consent","update",{analytics_storage:e.analytics?"granted":"denied",ad_storage:e.marketing?"granted":"denied",ad_user_data:e.marketing?"granted":"denied",ad_personalization:e.marketing?"granted":"denied",functionality_storage:e.preferences?"granted":"denied",personalization_storage:e.preferences?"granted":"denied",security_storage:"granted"})}catch(err){}}
var s = document.createElement('script');
s.src = 'https://cdn.cookiepilot.io/cookiepilot.js?cpkey=' + encodeURIComponent('TWOJ_KLUCZ');
document.head.appendChild(s);
})();
</script>

Trigeris: Consent Initialization - All Pages. Tagam ir jānostrādā vienu reizi katrā lapā. Google tagi (GA4, Google Ads), Facebook Pixel un citi mārketinga tagi NEIZMANTO Consent Initialization trigeri, bet tiek aktivizēti vēlāk (Consent Checks vai no piekrišanas atkarīgs trigeris). Saglabājiet tagu un publicējiet GTM konteineru.

Secība un trigeri

SecībaTagsTrigeris
1CookiePilot - Consent Init + BannerConsent Initialization - All Pages
2GA4, Google Ads, UETAll Pages (Consent Mode pats apstrādās piekrišanas)
3Facebook Pixel, TikTok, LinkedIn u.c.Custom Event cookiepilot_consent_update + piekrišanas nosacījums (skat. zemāk)

Tagi ārpus Google (Facebook Pixel, TikTok, LinkedIn)

Google Consent Mode apstrādā tikai Google tagus. Pārējiem skriptiem logrīks pie katras piekrišanas izmaiņas nosūta uz dataLayer notikumu:

dataLayer.push({
  event: 'cookiepilot_consent_update',
  cookiepilot_consent: {
    necessary: true,
    analytics: true,
    marketing: true,
    preferences: false
  }
});

Notikums tiek nosūtīts arī pie katra atgriežošā lietotāja apmeklējuma (kad logrīks nolasa sīkdatni ar piekrišanu), tāpēc GTM trigeris nostrādās pie katra apmeklējuma, ne tikai pie pirmā lēmuma.

Kopīgais paraugs (izpildiet vienu reizi)

Šos trīs elementus konfigurējat vienu reizi un pēc tam izmantojat visiem tagiem ārpus Google.

  1. Trigeris (Triggers → New → Custom Event): notikuma nosaukums cookiepilot_consent_update. Bez nosacījumiem, bez "Once per page" (tagam ir jāspēj nostrādāt atkārtoti pēc lēmuma maiņas).
  2. Data Layer Variable katrai izmantotajai kategorijai:
    • Name cookiepilot_consent.marketing → mainīgais, piemēram, dlv.cp_marketing
    • Name cookiepilot_consent.analytics → mainīgais, piemēram, dlv.cp_analytics
    • Name cookiepilot_consent.preferences → mainīgais, piemēram, dlv.cp_preferences
  3. Trigger Group vai nosacījums trigerī: dlv.cp_marketing equals true (mārketinga tagiem) vai attiecīgais lauks.

Katrā no zemāk dotajiem piemēriem Trigger ir tas pats Custom Event ar pievienotu nosacījumu uz pareizo mainīgo.

Facebook Pixel

Tags GTM: Tags → New → Custom HTML.

<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'YOUR_PIXEL_ID');
fbq('track', 'PageView');
</script>
  • Trigeris: cookiepilot_consent_update + nosacījums dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Pēc izvēles, lai nodrošinātu pilnu atbilstību Facebook Limited Data Use, pievienojiet otru tagu, kas izsauc fbq('consent','revoke') ar trigeri dlv.cp_marketing equals false.

TikTok Pixel

Tags GTM: Tags → New → Custom HTML.

<script>
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js",o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=r+"?sdkid="+e+"&lib="+t;e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(n,e)};
  ttq.load('YOUR_TIKTOK_PIXEL_ID');
  ttq.grantConsent();
  ttq.page();
}(window, document, 'ttq');
</script>
  • Trigeris: cookiepilot_consent_update + nosacījums dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

ttq.grantConsent() ir jaunais TikTok API (no 2024. gada). Bez tā TikTok saņem jauktos (hashed) datus bez piekrišanas, kas pārkāpj noteikumus.

LinkedIn Insight Tag

<script type="text/javascript">
_linkedin_partner_id = "YOUR_LINKEDIN_PARTNER_ID";
window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || [];
window._linkedin_data_partner_ids.push(_linkedin_partner_id);
</script>
<script type="text/javascript">
(function(l) {
if (!l){window.lintrk = function(a,b){window.lintrk.q.push([a,b])};
window.lintrk.q=[]}
var s = document.getElementsByTagName("script")[0];
var b = document.createElement("script");
b.type = "text/javascript";b.async = true;
b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js";
s.parentNode.insertBefore(b, s);})(window.lintrk);
</script>
  • Trigeris: cookiepilot_consent_update + nosacījums dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Hotjar

<script>
(function(h,o,t,j,a,r){
  h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
  h._hjSettings={hjid:YOUR_HOTJAR_ID,hjsv:6};
  a=o.getElementsByTagName('head')[0];
  r=o.createElement('script');r.async=1;
  r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
  a.appendChild(r);
})(window,document,'https://static.hotjar.com/c/hotjar-',".js?sv=");
</script>
  • Trigeris: cookiepilot_consent_update + nosacījums dlv.cp_analytics equals true.
  • Tag firing options: Once per page.

Hotjar pieder pie analytics, nevis marketing (tas mēra uzvedību, nevis reklāmas). Pārbaudiet savu sīkdatņu politiku — dažas firmas Hotjar klasificē citādi.

Microsoft Clarity

<script type="text/javascript">
(function(c,l,a,r,i,t,y){
  c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
  t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
  y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "YOUR_CLARITY_PROJECT_ID");
</script>
  • Trigeris: cookiepilot_consent_update + nosacījums dlv.cp_analytics equals true.
  • Tag firing options: Once per page.

Pinterest Tag

<script>
!function(e){if(!window.pintrk){window.pintrk = function () {
window.pintrk.queue.push(Array.prototype.slice.call(arguments))};var
n=window.pintrk;n.queue=[],n.version="3.0";var
t=document.createElement("script");t.async=!0,t.src=e;var
r=document.getElementsByTagName("script")[0];
r.parentNode.insertBefore(t,r)}}("https://s.pinimg.com/ct/core.js");
pintrk('load', 'YOUR_PINTEREST_TAG_ID');
pintrk('page');
</script>
  • Trigeris: cookiepilot_consent_update + nosacījums dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Microsoft Ads (UET)

UET atbalsta Google Consent Mode kopš 2023. gada beigām, tāpēc Custom Event trigeris jums nav nepieciešams. Ievietojiet tagu standarta veidā (All Pages, Once per page), un UET pats nolasa ad_storage no GCM, ko iestata logrīks.

Kategoriju kartēšana (kopsavilkums)

TagsKategorijaLauks cookiepilot_consent
Facebook Pixelmarketingmarketing
TikTok Pixelmarketingmarketing
LinkedIn Insightmarketingmarketing
Pinterestmarketingmarketing
Hotjaranalyticsanalytics
Microsoft Clarityanalyticsanalytics
Mixpanel, Amplitudeanalyticsanalytics
Intercom, Drift, Crisppreferencespreferences
GA4, Google Ads, UET(GCM, bez trigera)apstrādā gtag('consent','update')

API atsauce

CookiePilot nodrošina objektu window.CookiePilot:

MetodeApraksts
CookiePilot.getConsent()Pašreizējais piekrišanas stāvoklis vai null, ja lēmuma nav.
CookiePilot.acceptAll()Piekrišana visām kategorijām.
CookiePilot.rejectAll()Noraida visu, izņemot necessary.
CookiePilot.updateConsent(partial)Atjaunina izvēlētās kategorijas, piemēram, { analytics: true }.
CookiePilot.showSettings()Atver preferenču modālo logu.
CookiePilot.hideSettings()Aizver preferenču modālo logu.
CookiePilot.showMyConsent() / hideMyConsent()Parāda/paslēpj peldošo pogu.

Piemērs

const consent = CookiePilot.getConsent();
// { necessary: true, analytics: true, marketing: false, preferences: false }

CookiePilot.updateConsent({ analytics: true });

document.getElementById('cookie-settings').addEventListener('click', () => {
  CookiePilot.showSettings();
});

Saite "Pārvaldīt sīkdatnes" kājenē

<a href="#" onclick="CookiePilot.showSettings(); return false;">Pārvaldīt sīkdatnes</a>

JavaScript notikumi

Logrīks nosūta (dispatch) natīvu notikumu cookiepilot:consent uz window. Klausītājam ir jābūt reģistrētam pirms logrīka ielādes, ja vēlaties noķert notikumu atgriežošajam lietotājam (nosūtīšana notiek uzreiz pēc logrīka palaišanas):

<script>
  window.addEventListener('cookiepilot:consent', (e) => {
    if (e.detail.marketing) {
      fbq('init', 'YOUR_PIXEL_ID');
    }
  });
</script>
<script src="https://cdn.cookiepilot.io/cookiepilot.js" data-cpkey="TWOJ_KLUCZ"></script>

e.detail satur to pašu saturu (payload) kā getConsent(). Integrācijai caur GTM šī vietā izmantojiet iepriekš aprakstīto dataLayer notikumu, jo dataLayer ir persistents masīvs un GTM apstrādā arī vēsturiskos notikumus.

Piekrišanas kategorijas

KategorijaAprakstsPēc noklusējuma
necessaryNepieciešamas vietnes darbībaiVienmēr aktīvas
analyticsStatistika un analītikaNepieciešama piekrišana
marketingReklāmas un remārketingsNepieciešama piekrišana
preferencesPersonalizācija, valodaNepieciešama piekrišana
CookiePilot kategorijaConsent Mode lauki
analyticsanalytics_storage
marketingad_storage, ad_user_data, ad_personalization
preferencesfunctionality_storage, personalization_storage
(vienmēr)security_storage: granted

Versija 2 pievienoja ad_user_data un ad_personalization (obligāti kopš 2024. gada marta ES/EEZ teritorijā, izmantojot Google reklāmas).

ParametrsApraksts
ad_storageReklāmas sīkdatnes
analytics_storageAnalītikas sīkdatnes
ad_user_dataLietotāja datu nosūtīšana Google
ad_personalizationReklāmu personalizācija
functionality_storageFunkcionālās sīkdatnes
personalization_storagePersonalizācijas sīkdatnes
security_storageVienmēr granted

Mehānisms:

  1. Stub sinhroni iestata visus laukus uz denied, ar wait_for_update: 500.
  2. Pēc lietotāja lēmuma logrīks nosūta gtag('consent', 'update', {...}) ar augstāk doto kartējumu.
  3. Atgriežošajam lietotājam 2. punkts izpildās uzreiz pēc logrīka palaišanas, balstoties uz sīkdatni.

Izskata konfigurācija

Vadības panelī: Domēns → Konfigurācija:

  • Izskats: novietojums, krāsas, izkārtojums (BAR / BOX / MODAL).
  • Teksti: virsraksts, apraksts, pogu apzīmējumi, kategoriju apraksti. 13 valodas (EN, PL, DE, FR, ES, IT, NL, PT, SV, CS, RO, EL, HU).
  • Piekrišanas poga: peldošā poga "Sīkdatņu iestatījumi", redzama pēc pirmā lēmuma (apakšā pa kreisi/pa labi).
  • Custom CSS: lauks pašu stiliem. Logrīks tiek renderēts Shadow DOM, tāpēc galvenā dokumenta CSS selektori nedarbosies. Tikai caur šo lauku.

Pieejamība (WCAG 2.1 AA)

  • ✅ Navigācija ar tastatūru (Tab, Shift+Tab, Enter, Escape).
  • ✅ ARIA labels, role="dialog", aria-modal.
  • ✅ Fokusa slazds (focus trap) modālajā logā.
  • ✅ Ekrāna lasītājs (live regions stāvokļa izmaiņām).
  • ✅ Atsaucīgums (responsivitāte).

Integrācijas

WordPress

Mums ir oficiāls spraudnis: CookiePilot vietnē WordPress.org.

  1. WordPress administrēšana → Spraudņi → Pievienot jaunu → meklējiet "CookiePilot".
  2. Instalējiet un aktivizējiet.
  3. Iestatījumi → CookiePilot → ielīmējiet API atslēgu no vadības paneļa.

Spraudnis pats ievieto stub un tagu <head> sadaļā (ar pareizu secību pirms citiem skriptiem) un nodrošina shortcode [cookiepilot_settings] saitei "Pārvaldīt sīkdatnes" kājenē.

Ja vēlaties bez spraudņa: izmantojiet "Insert Headers and Footers" un ielīmējiet fragmentu no ātrās darba sākšanas 2. soļa Header sadaļā.

Shopify

  1. Veikals → Motīvi (Themes) → Rediģēt kodu.
  2. Failā theme.liquid ielīmējiet fragmentu pirms </head>.

Next.js

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://cdn.cookiepilot.io/cookiepilot.js"
          data-cpkey="TWOJ_KLUCZ"
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

strategy="beforeInteractive" nodrošina, ka bannera skripts izpildās agri. Atcerieties, ka inline stub no 2.a soļa (noklusētā piekrišana) pievienojat atsevišķi, <head> sadaļā pirms šī skripta, piemēram, izmantojot next/script ar dangerouslySetInnerHTML vai tieši failā app/layout.tsx.

BUJ

Vai skripts palēnina vietni?

Pakotne (bundle) ir aptuveni 12 KB gzip, ielādēta asinhroni. Bez ietekmes uz Core Web Vitals.

Cik ilgi tiek glabāta piekrišana?

Sīkdatne ar lietotāja lēmumu: pēc noklusējuma 365 dienas (konfigurējams vadības panelī). Notikumi analītikā: 2 gadi (ClickHouse TTL).

Jā. Logrīks palaišanas brīdī nolasa sīkdatni un nosūta notikumu uz dataLayer. Custom Event trigeris GTM nostrādās pie katra apmeklējuma, ne tikai pie pirmā lēmuma.

Kur ziņot par problēmu?

kontakt@cookiepilot.io vai čats vadības panelī.

Pārbaudes saraksts pēc ieviešanas

Pēc CookiePilot instalēšanas pārbaudiet konfigurāciju pirms reklāmas kampaņu publicēšanas.

1. Tests pirms lietotāja piekrišanas

  1. Atveriet vietni inkognito režīmā un notīriet domēna sīkdatnes.
  2. Atveriet DevTools → Network un atsvaidziniet lapu.
  3. Pirms piekrišanas nospiešanas pārbaudiet, ka:
    • netiek izveidotas analītikas/mārketinga sīkdatnes, piemēram, _ga, _gcl_*, _fbp, _ttp,
    • mārketinga tagi nesūta pieprasījumus uz Meta/TikTok/LinkedIn pirms mārketinga piekrišanas,
    • dataLayer ir iestatīts noklusētais stāvoklis denied laukiem ad_storage, ad_user_data, ad_personalization un analytics_storage.

2. Tests pēc piekrišanas akceptēšanas

  1. Nospiediet „Pieņemt visas”.
  2. DevTools pārbaudiet, vai parādījās notikums cookiepilot_consent_update.
  3. Google tagiem GTM Preview / Tag Assistant pārbaudiet, vai Consent Mode mainīja stāvokli uz granted attiecīgajām kategorijām.
  4. GA4 pārbaudiet DebugView, vai notikumi sāka pienākt pēc piekrišanas.
  5. Meta Pixel / TikTok / LinkedIn pārbaudiet, vai tagi tiek aktivizēti tikai pēc notikuma cookiepilot_consent_update un mārketinga piekrišanas nosacījuma.

3. Tests piekrišanas noraidīšanai

  1. Notīriet sīkdatnes un atsvaidziniet lapu.
  2. Nospiediet „Noraidīt visas”.
  3. Pārbaudiet, ka mārketinga sīkdatnes un pieprasījumi joprojām netiek palaisti.
  4. Pārbaudiet, ka vietnes nepieciešamās funkcijas joprojām darbojas.

4. Biežākās kļūdas

  • GA4/Google Ads tags tiek aktivizēts uz Consent Initialization, nevis vēlāka trigera.
  • Meta Pixel vai TikTok Pixel nav nosacījuma uz cookiepilot_consent.marketing.
  • Vietnē palicis vecs, kodā ierakstīts (hardcoded) izsekotājs <head> sadaļā pirms CookiePilot.
  • Dokumentācijā vai veidnē palicis neaktuāls skripta URL vai vecs identifikatora atribūts aktuālā cookiepilot.js ar data-cpkey vietā.