API Reference

run

Configures the plugin with the provided config. object.

• Type

  function(config: object): Promise<void>

• Details

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

• Example

  CookieConsent.run({
      categories: {
          // categories here
      },
      language: {
          default: 'en',
  
          translations: {
              en: {
                  // modal translations here
              }
          }
      }
  });

show

Shows the consent modal.

• Type

  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

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

hide

Hides the consent modal.

• Type

  function(): void

• Example

  CookieConsent.hide();

showPreferences

Shows the preferences modal.

• Type

  function(): void

• Example

  CookieConsent.showPreferences();

hidePreferences

Hides the preferences modal.

• Type

  function(): void

• Example

  CookieConsent.hidePreferences();

acceptCategory

Accepts or rejects categories.

• Type

  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

  CookieConsent.acceptCategory('all');                // accept all categories
  CookieConsent.acceptCategory([]);                   // reject all (accept only categories marked as readOnly/necessary)
  CookieConsent.acceptCategory();                     // accept currently selected categories inside the preferences modal
  
  CookieConsent.acceptCategory('analytics');          // accept only the "analytics" category
  CookieConsent.acceptCategory(['cat_1', 'cat_2']);   // accept only these 2 categories
  
  CookieConsent.acceptCategory('all', ['analytics']); // accept all categories except the "analytics" category
  CookieConsent.acceptCategory('all', ['cat_1', 'cat_2']); // accept all categories except these 2

acceptedCategory

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

• Type

  function(categoryName: string): boolean

• Examples

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

acceptService

Accepts or rejects services.

• Type

  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

  CookieConsent.acceptService('all', 'analytics');   // accept all services (in the 'analytics' category)
  CookieConsent.acceptService([], 'analytics');      // reject all services
  
  CookieConsent.acceptService('service1', 'analytics');     // accept only this specific service (reject all the others)
  CookieConsent.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

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

• Examples

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

validConsent

Returns true if consent is valid.

• Type

  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

  if(CookieConsent.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

  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.

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

eraseCookies

Removes one or multiple cookies.

• Type

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

• Examples
  

  Delete the plugin's own cookie

  CookieConsent.eraseCookies('cc_cookie');

  Delete the _gid and all cookies starting with _ga:

  CookieConsent.eraseCookies(['_gid', /^_ga/], '/', location.hostname);

loadScript

Loads script files (.js).

• Type

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

• Examples
  

  // basic usage
  CookieConsent.loadScript('path-to-script.js');
  
  // check if script is loaded successfully
  const loaded = await CookieConsent.loadScript('path-to-script.js');
  
  if(!loaded){
      console.log('Script failed to load!');
  }

  You may also concatenate multiple .loadScript methods:

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

  Load script with attributes:

  CookieConsent.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

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

• Example

  // Get only the 'data' field
  const data = CookieConsent.getCookie('data');
  
  // Get all fields
  const cookieContent = CookieConsent.getCookie();

getConfig

Returns the configuration object or one of its fields.

• Type

  function(field?: string): any

• Example

  // Get the entire config
  const config = CookieConsent.getConfig();
  
  // Get only the language' prop.
  const language = CookieConsent.getConfig('language');

getUserPreferences

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

• Type

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

• Details

  Possible acceptType values:

  • 'all'
  • 'custom'
  • 'necessary'

• Example
  

  const preferences = CookieConsent.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

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

• Examples
  

  // Simple usage
  CookieConsent.setLanguage('it');
  
  // Get return value
  const success = await CookieConsent.setLanguage('en');

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

  CookieConsent.setLanguage('en', true);

setCookieData

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

• Type
  

  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
  

  // First set: true
  CookieConsent.setData({
      value: {id: 21, lang: 'it'}
  }); //{id: 21, lang: 'it'}
  
  // Change only the 'id' field: true
  CookieConsent.setData({
      value: {id: 22},
      mode: 'update'
  }); //{id: 22, lang: 'it'}
  
  // Add a new field: true
  CookieConsent.setData({
      value: {newField: 'newValue'},
      mode: 'update'
  }); //{id: 22, lang: 'it', newField: 'newValue'}
  
  // Change 'id' to a string value: FALSE
  CookieConsent.setData({
      value: {id: 'hello'},
      mode: 'update'
  }); //{id: 22, lang: 'it', newField: 'newValue'}
  
  // Overwrite: true
  CookieConsent.setData({
      value: 'overwriteEverything'
  }); // 'overwriteEverything'

reset

Reset CookieConsent.

• Type:

  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:

  CookieConsent.reset(true);