JavaScript API

JavaScript API позволяет вашему собственному коду читать и изменять согласие. Один и тот же API доступен двумя способами:

• Глобальный объект Cookiesh, который создает тег script. Используйте его на обычных HTML-страницах и в консоли браузера.
• Пакет @cookiesh/js — типизированная обертка над глобальным объектом для приложений со сборщиком. Работает так же и включает определения TypeScript.

npm install @cookiesh/js

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

Пакет не загружает вторую копию Cookiesh. Он дожидается тега script и обращается к глобальному объекту. Во всех примерах ниже используется пакет, но Cookiesh.ready() и cookiesh.ready() ведут себя одинаково.

Состояние согласия

Большинство методов возвращают или принимают объект ConsentState:

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** Как возникло текущее состояние. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** Случайный ID сохраненной записи о согласии или null до первого выбора. */
  consentId: string | null;
  /** Время выбора в формате ISO 8601 или null до первого выбора. */
  timestamp: string | null;
  bannerVersion: string;
  /** Регион, по которому сработало правило, например "FR" или "US-CA". */
  region: string;
}

Пока посетитель не сделал выбор, method равен default, а категории отражают состояние по умолчанию для его региона. В регионах с предварительным согласием это значит, что всё, кроме necessary, равно false.

Чтение согласия

ready()

ready(): Promise<ConsentState>

Выполняется, как только Cookiesh узнает состояние согласия: сразу для вернувшихся посетителей и после определения региона для новых. Метод не ждет, пока посетитель нажмет кнопку в баннере. Используйте его, чтобы запускать код, зависящий от согласия:

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

getConsent()

getConsent(): ConsentState | null

Синхронно возвращает текущее состояние или null, если Cookiesh еще не загрузился. Лучше используйте ready(), если вы не уверены, что скрипт уже загружен.

hasConsent(category)

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

Короткий способ проверить одну категорию. Возвращает false, пока Cookiesh не загрузился.

Изменение согласия

Эти методы сохраняют новую запись о согласии — точно так же, как если бы посетитель воспользовался баннером. Вызывайте их только в ответ на явное действие посетителя, например щелчок на вашей собственной странице настроек.

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

// Собственный переключатель на странице настроек аккаунта
await cookiesh.setConsent({ analytics: event.target.checked });

Категории, которые вы не указали, сохраняют текущее значение. necessary изменить нельзя.

Показ интерфейса

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

showBanner() снова показывает баннер первого уровня, даже если посетитель уже сделал выбор. openPreferences() открывает центр настроек с переключателями по категориям и декларацией файлов cookie. close() закрывает любой из них без сохранения.

Вошедшие пользователи

По умолчанию согласие хранится отдельно для каждого браузера. В продуктах с авторизацией свяжите его с ID пользователя, чтобы выбор следовал за пользователем на всех устройствах:

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

// После входа
await cookiesh.identify(session.user.id);

// После выхода
cookiesh.reset();

identify() находит последний выбор пользователя. Если он есть, Cookiesh применяет его на этом устройстве и не показывает баннер. Если посетитель сделал выбор до входа, этот выбор сохраняется для пользователя. Cookiesh хранит только хеш переданного ID с солью и никогда — сам ID. Используйте непрозрачный внутренний ID, а не адрес электронной почты.

reset() удаляет связь с пользователем, но сохраняет текущий выбор на этом устройстве.

Атрибуты тега script

Тег script настраивается атрибутами data-:

Атрибут	По умолчанию	Описание
data-site-id	Обязателен	ID вашего сайта, например ck_live_8f2a91
data-language	Автоматически	Принудительно задает язык баннера (см. Оформление баннера)
data-auto-block	true	Укажите false, чтобы блокировать только скрипты, которые вы отметили сами
data-nonce	Нет	Nonce для CSP, который применяется к скриптам, разблокированным Cookiesh
data-consent-mode	true	Укажите false, чтобы не отправлять сигналы Google Consent Mode

Отладка

Cookiesh.debug(): void

Выполните в консоли браузера, чтобы вывести определенный регион, сработавшее правило, версию баннера, каждый заблокированный скрипт и текущее состояние всех категорий. Метод доступен только у глобального объекта.