langs-cookie-consent v0.0.16

Langs Cookie Settings

Installation

In order to install langs-cookie-consent, please execute:

npm i lang-cookie-consent

Dependecies

langs-cookie-consent is using Angular12+, langs-navigation, AOS and ngx-translate.

Need a basic knowledge of typescript, in order to read this documentation and use the this library.

Also it's possible to use the it together with Angular Universal.

Peer dependencies list is provided below.

    "@angular/cdk": "^12.2.11",
    "@angular/common": "^12.2.11",
    "@angular/compiler": "^12.2.11",
    "@angular/core": "^12.2.11",
    "@angular/forms": "^12.2.11",
    "@angular/platform-browser": "^12.2.11",
    "@angular/platform-browser-dynamic": "^12.2.11",
    "@angular/router": "^12.2.11",
    "@nguniversal/express-engine": "^12.1.2",
    "@ngx-translate/core": "^13.0.0",
    "aos": "^2.3.4",
    "langs-navigation": "0.0.13",
    "rxjs": "^6.6.7",
    "zone.js": "~0.11.4"

Usage

To use langs-cookie-consent need to be imported LangsCookieConsentModule together with it's static method .forRoot().

It's possible to pass parameters using it, please check section down this page.

import { NgModule } from '@angular/core';
import { LangsCookieConsentModule } from 'langs-cookie-consent';

@NgModule({
  declarations: [...],
  imports: [
    ...,
    LangsCookieConsentModule.forRoot()
  ],
  providers: [...],
  bootstrap: [...]
})
export class AppModule { }

Also need to put a component somewhere in your app (preferrable in main component):

<langs-cookie-consent-banner></langs-cookie-consent-banner>

Overview

langs-cookie-consent allows to create cookie consent banner with additional settings page.

All texts can be customized, also can be used translation keys instead of text.

It's possible to use langs-navigation to open main webapp pages from the banner using links property.

By, default langs-cookie-consent is using AOS for the enter/leave animation (can be turned off).

The main logic flow of the banner visibility is next (and it's can't be changed):

• banner will be opened by default on first usage;
• banner has accept and reject buttons by default;
• after click accept button, in document.cookie will be saved flag cookieconsent_status=allow;
• after click accept button, on page refresh the banner will be hidden and will become visible revoke text container;
• after click reject button, in document.cookie will be saved flag cookieconsent_status=deny;
• after click reject button, on page refresh the banner will be visible;
• banner can be closed by close button, then will become visible revoke text container;
• placement of the banners pages and revoke text container can be changed using position input property;

As the input can be provided settings, main logic keys are next:

• settings consists of the `caption, header` and tabs.
• each tab can have header, description and providers;
• settings tabs will be displayed on the main page of the banner, as sliders, with same caption as tab have;
• providers will be displayed as sliders on the settings page under according tab;
• if tab or provider was not touched - it means it toggled on, by default.
• on any slider toggling event will be saved appropriate flag in the document.cookie.
• any slider flag value will be allow or deny, depends whether slider is toggled on or off accordingly.

Any name of cookie flag consists of three parts:

• it starts with cookieconsent_ text (cannot be changed);
• in the middle - entity identifier part - tab or provider (can be changed using cookiePrefix property);
• and ends with instance identifier - by default, for tab it's tab index, for provider - tab and provider indexes joined with underscore symbol _;
• provider or tab entity instance identifier can be changed by using id property;
• for a cookie name can be used only symbols from A-Za-z0-9 range, but it's possible to setup any identifier or cookiePrefix;

By default, tabs and providers and synchronized with next logic (it can be turned off using syncSwitchersAndProviders configuration property):

• if tab slider is toggled off, - all providers sliders are toggled off too;
• if all providers sliders are toggled off and then tab slider will be toggled on, - all providers togglers will be toggled on too;
• if tab slider is toggled off and then will be toggled on any provider slider in this tab - tab slider will be toggled on too;

Checking Cookie Status

To check cookie status langs-cookie-consent provides separate service CookieStatusNotificationService.

It can be used inside component and services using regular dependency injection:

import { AfterViewInit, Component } from '@angular/core';
import { CookieStatusNotificationService } from 'langs-cookie-consent';

@Component({
  ...
})
export class AppComponent implements AfterViewInit {
  ...

  constructor(
    ...
    private cookieStatusNotificationService: CookieStatusNotificationService
  ) {}
  
  ngAfterViewInit(): void {
    console.log(this.cookieStatusNotificationService)
  }
}

With service, there are two ways to check cookie status:

• using banner events;
• check cookie state directly;

Banner events

On button/slider/icon click event it's possible to subscribe on ReplaySubject:

CookieStatusNotificationService provides access:

• to the ReplaySubject<CookieSlider> on toggle any slider;
• to the ReplaySubject<CookieState> on accept/reject cookie settings and click close button;

Interface CookieSlider contains property isChecked to indicate a status. Interface CookieStatus contains arrays of CookieSlider interfaces for current tabs and providers.

Detailed information about all interfaces structure can be found below.

In the example below, are displayed all possible subscribes:

import { AfterViewInit, Component } from '@angular/core';
import { CookieStatusNotificationService } from 'langs-cookie-consent';

@Component({
  ...
})
export class AppComponent implements AfterViewInit {
  ...

  constructor(
    ...
    private cookieStatusNotificationService: CookieStatusNotificationService
  ) {}
  
  ngAfterViewInit(): void {
    const { accepted, closed, rejected, providerChanged, tabChanged } = this.cookieStatusNotificationService;

    accepted.subscribe(result => console.log('accepted', result));

    rejected.subscribe(result => console.log('rejected', result));

    closed.subscribe(result => console.log('close', result));

    providerChanged.subscribe(result => console.log('provider', result));

    tabChanged.subscribe(result => console.log('switcher', result));
  }
}

Get Cookie Status

To check is cookie usage allowed need to be used isCookieAllowed public getter of the CookieStatusNotificationService.

If user clicked on accept button isCookieAllowed return true, another false.

In order to receive concrete info about current cookie consent banner info status, can be used next methods:

• isTabAllowed(tabId: Identifier): boolean;
• isProviderAllowed(providerId: Identifier, tabId?: Identifier): boolean;

Type Identifier in the input arguments is a type pseudonym to represent string or number regular types.

Input Confifuration

export interface LangsCookieConsentConfigurationInput {
  // where to show the banner 
  // default 'bottom-left'
  readonly position?: CookieConsentPosition;
  
  // reverse control buttons order
  // default true 
  readonly reverseButtonsOrder?: boolean;

  // header text on the main page, can be used also translation key
  // default 'Your cookie settings for this website'
  readonly header: string;

  // description text on the main page, can be used also translation key
  // default: 
  /**
   * We use cookies to store your login information, 
   * for secure login, to collect statistical data, 
   * to optimize website functionality, 
   * and to online marketing and remarketing 
   * to provide you with a more enjoyable overall experience.
   * Click \"Accept All\" to accept cookies 
   * or click on \"Manage Cookie Settings\" below 
   * for a detailed description of the types of cookies we use 
   * and information about the the relevant providers 
   * and to decide which types of cookies are Cookies 
   * should be set when using our website.
   * */
  readonly text: string;

  // lang that can be used to check for translations
  // if current one lang has no matched translation keys
  // working according to the langs-navigation rules
  // default 'en'
  readonly fallsbackLang?: Lang;

  // if true shows all logging an info 
  // from all internal events on any action user did
  readonly isLoggingEnabled?: boolean;

  // text inside the revoke container
  // default 'Cookie Policy'
  readonly revokeText?: string;

  // the time of AOS animation in milliconds
  // default is 800
  readonly animationDuration?: number;

  // texts or tranlation keys for all buttons in the banner
  // default
  /**
   * buttons: {
    accept: "Accept",
    acceptSome: "Save & Close",
    reject: "Reject",
    saveAndClose: "Save & Close",
    back: 'Back'
  },
   * */
  readonly buttons?: LangsCookieConsentButtons,

  // a-tag links on the main page of the banner
  // caption can be text or translation key
  // navigate is the same navigate from langs-navigation property of the NavigateDirective
  // default null
  readonly links?: { caption: string; navigate: string; }[],

  // if true, tries to syncronize work of tabs (or switchers)
  // rules is described in the ReadMe, Overview section
  // default true
  readonly syncSwitchersAndProviders?: boolean;

  // all data for the settings page with tabs and providers
  // tabs will be used to generate sliders (switchers) on main page for the quick access
  // default null - means it's not using
  readonly settings?: CookieSettingInput;
}

Other interfaces and types

export type Identifier = string | number;

export interface CookieSliderInput {
  // can be used to specify unique id, will be displayed in document cookie
  id?: Identifier;
  // is checked by default or not
  isChecked?: boolean;
  // not neccessary to use
  tabId?: Identifier;
  // use it to have special prefix in document.cookie
  cookiePrefix?: string;
  // displayed text or translation key
  caption: string;
}

export interface CookieSlider extends CookieSliderInput {
  // can be used to specify unique id, will be displayed in document cookie
  id: Identifier;

  // is checked or not
  isChecked: boolean;

  // on what tab is placed
  tabId: Identifier;

  // how it will be displayed in document.cookie
  cookiePrefix: string;
}

export interface CookieState {
  // the same as tabs but as slider on the main page
  switchers: CookieSlider[];

  // all providers from all tabs
  providers: CookieSlider[];
}

// can be used text or translation key everywhere
export interface CookieSettingInput {
  // display name of the Cookie Settings page link
  caption: string;

  // is a main header on settings page
  header?: string;
  // is a description on settings page
  text?: string;

  // all tabs info
  tabs: SettingTabInput[];
}

export interface CookieSetting extends CookieSettingInput {
  header: string;
  tabs: SettingTab[];
}

export interface SettingTabInput {
  // can be used to specify tab unique id, will be displayed in document cookie
  id?: Identifier;

  // by default is checked or not
  isChecked?: boolean;

  //is a tab caption from the left side list on the settings page
  caption: string;

  // in main area of settings page
  header?: string;

  // under the header above
  text: string;

  // will be saved inside document cookie
  cookiePrefix?: string;

  // header above all providers
  providersHeader?: string;

  providers?: CookieSliderInput[];
}

export interface SettingTab extends SettingTabInput {
  // will be displayed in document cookie, can be used to get info
  id: Identifier;
  // is checked or not
  isChecked: boolean;
  // will be saved inside document cookie
  cookiePrefix: string;

  providers: CookieSlider[];
}

// on every property can be used text or translation key
export interface LangsCookieConsentButtons {
  // accept button on the main page
  accept: string;

  // accept button on the main page, if not all tabs sliders is toggled on
  acceptSome?: string;

  // reject button on the main page
  reject: string;

  // save and close button on the settings page
  saveAndClose: string;

  // return to main page button on the settings page
  back: string;
}

const bottomRight = 'bottom-right' as const;
const bottomLeft = 'bottom-left' as const;

export const cookieConsentPositions = {
  bottomRight,
  bottomLeft
};

export type CookieConsentPosition = typeof bottomRight | typeof bottomLeft;