API Reference

INFO

? means that the parameter/property is optional.

run

Configures the plugin with the provided config. object.

Type

javascript

function(config: object): Promise<void>

Details
The config argument is required and must contain — at least — the categories and language properties.

Example

javascript

cc.run({
    categories: {
        // categories here
    },
    language: {
        default: 'en',

        translations: {
            en: {
                // modal translations here
            }
        }
    }
});

show

Shows the consent modal.

Type
javascript
```
function(createModal?: boolean): void
```
Details
If consent was previously expressed, the consent modal will not be generated; you'll have to pass the argument true to generate it on the fly.

Example

javascript

cc.show();

// show modal (if it doesn't exist, create it)
cc.show(true);

hide

Hides the consent modal.

Type
javascript
```
function(): void
```
Example
javascript
```
cc.hide();
```

showPreferences

Shows the preferences modal.

Type
javascript
```
function(): void
```
Example
javascript
```
cc.showPreferences();
```

hidePreferences

Hides the preferences modal.

Type
javascript
```
function(): void
```
Example
javascript
```
cc.hidePreferences();
```

acceptCategory

Accepts or rejects categories.

Type

javascript

function(
    categoriesToAccept?: string | string[],
    exclusions?: string[]
): void

Details
The first argument accepts either a string or an array of strings. Special values:
- 'all': accept all
- []: empty array, accept none (reject all)
- : empty argument, accept only the categories selected in the preferences modal

Examples

javascript

cc.acceptCategory('all');                // accept all categories
cc.acceptCategory([]);                   // reject all (accept only categories marked as readOnly/necessary)
cc.acceptCategory();                     // accept currently selected categories inside the preferences modal

cc.acceptCategory('analytics');          // accept only the "analytics" category
cc.acceptCategory(['cat_1', 'cat_2']);   // accept only these 2 categories

cc.acceptCategory('all', ['analytics']); // accept all categories except the "analytics" category
cc.acceptCategory('all', ['cat_1', 'cat_2']); // accept all categories except these 2

acceptedCategory

Returns true if the specified category was accepted, otherwise false.

Type

javascript

function(categoryName: string): boolean

Examples

javascript

if(cc.acceptedCategory('analytics')){
    // great
}

if(!cc.acceptedCategory('ads')){
    // not so great
}

acceptService

Accepts or rejects services.

Type

javascript

function(
    services: string | string[],
    category: string
): void

Details
Special values for the services argument:
- 'all': accept all services
- []: empty array, accept none (reject all)

Examples

javascript

cc.acceptService('all', 'analytics');   // accept all services (in the 'analytics' category)
cc.acceptService([], 'analytics');      // reject all services

cc.acceptService('service1', 'analytics');     // accept only this specific service (reject all the others)
cc.acceptService(['service1', 'service2'], 'analytics');   // accept only these 2 services (reject all the others)

acceptedService

Returns true if the service inside the category is accepted, otherwise false.

Type

javascript

function(
    serviceName: string,
    categoryName: string
): boolean

Examples

javascript

if(cc.acceptedService('Google Analytics', 'analytics')){
    // great
}else{
    // not so great
}

validConsent

Returns true if consent is valid.

Type
javascript
```
function(): boolean
```
Details
Consent is not valid when at least one of following situations occurs:
- consent is missing (e.g. user has not yet made a choice)
- revision numbers don't match
- the plugin's cookie does not exist/has expired
- the plugin's cookie is structurally not valid (e.g. empty)

Example

javascript

if(cc.validConsent()){
    // consent is valid
}else{
    // consent is not valid
}

validCookie

Returns true if the specified cookie is valid (it exists and its content is not empty).

Type
javascript
```
function(cookieName: string): boolean
```
Details
This method cannot detect if the cookie has expired as such information cannot be retrieved with javascript.

Example

Check if the 'gid' cookie is set.

javascript

if(cc.validCookie('_gid')){
    // _gid cookie is valid!
}else{
    // _gid cookie is not set ...
}

eraseCookies

Removes one or multiple cookies.

Type

javascript

function(
    cookies: string | RegExp | (string | RegExp)[],
    path?: string,
    domain?: string
): void

Examples
Delete the plugin's own cookie
javascript
```
cc.eraseCookies('cc_cookie');
```
Delete the _gid and all cookies starting with _ga:
javascript
```
cc.eraseCookies(['_gid', /^_ga/], '/', location.hostname);
```

loadScript

Loads script files (.js).

Type

javascript

function(
    path: string,
    attributes?: {[key: string]: string}
): Promise<boolean>

Examples

javascript

// basic usage
cc.loadScript('path-to-script.js');

// check if script is loaded successfully
const loaded = await cc.loadScript('path-to-script.js');

if(!loaded){
    console.log('Script failed to load!');
}

You may also concatenate multiple .loadScript methods:

javascript

cc.loadScript('path-to-script1.js')
    .then(() => cc.loadScript('path-to-script2.js'))
    .then(() => cc.loadScript('path-to-script3.js'));

Load script with attributes:

javascript

cc.loadScript('path-to-script.js', {
    'id': 'ga-script',
    'another-attribute': 'another-value'
});

getCookie

Returns the plugin's own cookie, or just one of the fields.

Type

javascript

function(
    field?: string,
    cookieName?: string,
): any | {
    categories: string[],
    revision: number,
    data: any,
    consentId: string
    consentTimestamp: string,
    lastConsentTimestamp: string,
    services: {[key: string]: string[]}
}

Example

javascript

// Get only the 'data' field
const data = cc.getCookie('data');

// Get all fields
const cookieContent = cc.getCookie();

getConfig

Returns the configuration object or one of its fields.

Type
javascript
```
function(field?: string): any
```

Example

javascript

// Get the entire config
const config = cc.getConfig();

// Get only the language' prop.
const language = cc.getConfig('language');

getUserPreferences

Returns user's preferences, such as accepted/rejected categories and services.

Type

javascript

function(): {
    acceptType: string,
    acceptedCategories: string[],
    rejectedCategories: string[],
    acceptedServices: {[category: string]: string[]}
    rejectedServices: {[category: string]: string[]}
}

Details
Possible acceptType values:
- 'all'
- 'custom'
- 'necessary'

Example

javascript

const preferences = cc.getUserPreferences();

if(preferences.acceptType === 'all'){
    console.log("Awesome!");
}

if(preferences.acceptedCategories.includes('analytics')){
    console.log("The analytics category was accepted!");
}

setLanguage

Changes the modal's language. Returns a Promise<boolean> which evaluates to true if the language was changed successfully.

Type

javascript

function(
    language: string,
    force?: boolean
): Promise<boolean>

Examples

javascript

// Simple usage
cc.setLanguage('it');

// Get return value
const success = await cc.setLanguage('en');

Forcefully refresh modals (re-generates the html content):

javascript

cc.setLanguage('en', true);

setCookieData

Save custom data into the cookie. Returns true if the data was set successfully.

Type

javascript

function({
    value: any,
    mode?: string
}): boolean

Details
Valid mode values:
- 'update' sets the new value only if its different from the previous value, and both are of the same type.
- 'overwrite' (default): always sets the new value (overwrites any existing value).
INFO
The setCookieData method does not alter the cookies' current expiration time.

Examples

javascript

// First set: true
cc.setData({
    value: {id: 21, lang: 'it'}
}); //{id: 21, lang: 'it'}

// Change only the 'id' field: true
cc.setData({
    value: {id: 22},
    mode: 'update'
}); //{id: 22, lang: 'it'}

// Add a new field: true
cc.setData({
    value: {newField: 'newValue'},
    mode: 'update'
}); //{id: 22, lang: 'it', newField: 'newValue'}

// Change 'id' to a string value: FALSE
cc.setData({
    value: {id: 'hello'},
    mode: 'update'
}); //{id: 22, lang: 'it', newField: 'newValue'}

// Overwrite: true
cc.setData({
    value: 'overwriteEverything'
}); // 'overwriteEverything'

reset

Reset CookieConsent.

Type:
javascript
```
function(eraseCookie?: boolean): void
```
Details:
Resets all internal pointers and config. settings. You need to call again the .run() method with a valid config. object.
You can pass the argument true to delete the plugin's cookie. The user will be prompted once again to express their consent.
WARNING
Once this method is called, the plugin won't be able to detect already executed script tags with a data-category attribute.
Example:
javascript
```
cc.reset(true);
```

API Reference #

run #

show #

hide #

showPreferences #

hidePreferences #

acceptCategory #

acceptedCategory #

acceptService #

acceptedService #

validConsent #

validCookie #

eraseCookies #

loadScript #

getCookie #

getConfig #

getUserPreferences #

setLanguage #

setCookieData #

reset #

API Reference

run

show

hide

showPreferences

hidePreferences

acceptCategory

acceptedCategory

acceptService

acceptedService

validConsent

validCookie

eraseCookies

loadScript

getCookie

getConfig

getUserPreferences

setLanguage

setCookieData

reset