langs-cookie-consent
v0.0.16
Published
In order to install **`langs-cookie-consent`**, please execute: ``` npm i lang-cookie-consent ```
Downloads
6
Readme
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 flagcookieconsent_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 flagcookieconsent_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 thecaption**, **header
andtabs
.- each
tab
can haveheader
,description
andproviders
; settings
tabs
will be displayed on the main page of the banner, as sliders, with samecaption
astab
have;providers
will be displayed as sliders on thesettings
page under accordingtab
;- if
tab
orprovider
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
ordeny
, 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
orprovider
(can be changed usingcookiePrefix
property); - and ends with instance identifier - by default, for
tab
it's tab index, forprovider
-tab
andprovider
indexes joined with underscore symbol_
; provider
ortab
entity instance identifier can be changed by usingid
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, - allproviders
sliders are toggled off too; - if all
providers
sliders are toggled off and thentab
slider will be toggled on, - allproviders
togglers will be toggled on too; - if
tab
slider is toggled off and then will be toggled on anyprovider
slider in thistab
-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;