Reference Guide: JS Privacy object and methods

Overview

The JS Privacy API consists of a public JavaScript object, Privacy, that can be accessed using code implemented on an Uberflip Hub via the custom code functionality.

The interface for this object consists of a set of "getter" and "setter" methods:

• The getter methods can be used to obtain information about Privacy Groups, such as which Privacy Groups exist in the Hub, and what Hub functionalities (cookies and other privacy-related functions) they are tied to.
• The setter methods can be used to manipulate the status of Privacy Groups, either enabling or disabling them. Additionally, there is also a static method that can be used to manually trigger a page reload in order to apply settings changes.

There are two versions of the Uberflip Hub Front End currently in use, known as Front End V1 and V2, and the Privacy object is injected on a different object in each version. Therefore, while the interface for this object is the same in both versions, specific usage varies depending on the Front End version of the Hub you are working with.

Requirements

In order for the JS Privacy API to be usable with a target Hub, the Privacy Groups feature must be set up and configured on that Hub. This means that at least one Privacy Group must be created, and that all privacy-related Hub functionalities (as shown under Privacy Groups > Functionality) must be linked to Privacy Group(s).

Usage

To use the JS Privacy API in the context of an Uberflip Hub, first determine the version of the Hub Front End that is in use.

Depending on the version, the Privacy object will be injected on:

• Front End V1: window.Hubs
• Front End V2: window.uberflip

Beyond this, the methods available for the Privacy object, and their structure and usage, are the same regardless of the Hub Front End version.

Implement code that uses the Privacy object by placing it in a custom code block within that Hub. The block you use must be loaded after the window.Hubs/window.uberflip object has been injected. To achieve this, either choose the Body Bottom placement for the code block, or use window.addEventListener to listen for the uberflip.load Hub event.

Privacy.getAll()

Used to get information about all Privacy Groups in the target Hub.

Method

Front End V1:
var privacyGroups = Hubs.Privacy.getAll();

Front End V2:
var privacyGroups = uberflip.Privacy.getAll();

Behavior

Returns a JSON object of all Privacy Groups in the target Hub. Contains individual objects for each Privacy Group, keyed by unique Privacy Group ID. Each Privacy Group object contains the following properties:

• id integer: The system-defined Privacy Group ID that uniquely identifies the Privacy Group.
• name string: The user-defined name of the Privacy Group.
• description string: The user-defined description of the Privacy Group.
• version integer: The UNIX timestamp when the most recent version of the Privacy Group was published.
• isAccepted integer: Indicates whether the current visitor has accepted (1) or declined (0) the Privacy Group.
• functionalities array: A list of privacy-related Hub functionalities that has been assigned to the Privacy Group. Each is an object with the following properties:
  • id integer: The ID of the Hub functionality (specific to the Hub).
  • name string: The "friendly" name of the Hub functionality.
  • code string: The system-defined functionality code used to reference this Hub functionality in certain methods. See below for a list of possible values.

📘

No matches

If the target Hub does not contain any Privacy Groups, an empty JSON object ({}) will be returned.

Example

{
  "405608":{
    "id":405608,
    "name":"Marketing",
    "description":"Allow storing of a Marketing Analytics cookie.",
    "version":1598039701,
    "isAccepted":0,
    "functionalities":[
      {
        "id":4,
        "code":"ELOQUA",
        "name":"Eloqua"
      },
      {
        "id":5,
        "code":"MARKETO",
        "name":"Marketo"
      }
    ]
  },
  "405614":{
    "id":405614,
    "name":"Analytics",
    "description":"Allow your page views, length of stay and other interesting metrics for big data to consume to be tracked.",
    "version":1597432246,
    "isAccepted":1,
    "functionalities":[
      {
        "id":1,
        "code":"UBERFLIP",
        "name":"Uberflip"
      }
    ]
  },
  "405621":{
    "id":405621,
    "name":"Functionality",
    "description":"Allow setting of functionality cookies that are required for our website to work.",
    "version":1597432246,
    "isAccepted":1,
    "functionalities":[
      {
        "id":2,
        "code":"UBERFLIPUI",
        "name":"Uberflip UI"
      }
    ]
  }
}

Privacy.getById()

Used to get information about a specific Privacy Group. Specify the desired Privacy Group using its Privacy Group ID (e.g. 123456).

Method

Front End V1:
var privacyGroup = Hubs.Privacy.getById(123456);

Front End V2:
var privacyGroup = uberflip.Privacy.getById(123456);

Behavior

Returns a JSON object with the details of the specified Privacy Group. The object contains the following properties:

• id integer: The system-defined Privacy Group ID that uniquely identifies the Privacy Group.
• name string: The user-defined name of the Privacy Group.
• description string: The user-defined description of the Privacy Group.
• version integer: The UNIX timestamp when the most recent version of the Privacy Group was published.
• isAccepted integer: Indicates whether the current visitor has accepted (1) or declined (0) the Privacy Group.
• functionalities array: A list of privacy-related Hub functionalities that has been assigned to the Privacy Group. Each is an object with the following properties:
  • id integer: The ID of the Hub functionality (specific to the Hub).
  • name string: The "friendly" name of the Hub functionality.
  • code string: The system-defined functionality code used to reference this Hub functionality in certain methods. See below for a list of possible values.

📘

No matches

If a Privacy Group with the specified ID does not exist in the Hub, null will be returned.

Example

{
  "id":405621,
  "name":"Functionality",
  "description":"Allow setting of functionality cookies that are required for our website to work.",
  "version":1597432246,
  "isAccepted":1,
  "functionalities":[
    {
      "id":2,
      "code":"UBERFLIPUI",
      "name":"Uberflip UI"
    }
  ]
}

Privacy.getByFunctionalityCode()

Used to search for a specific Hub functionality to get information about the Privacy Group it belongs to. Specify the desired Hub functionality using its functionality code (e.g. UBERFLIP).

Method

Front End V1:
var privacyGroup = Hubs.Privacy.getByFunctionalityCode('UBERFLIP');

Front End V2:
var privacyGroup = uberflip.Privacy.getByFunctionalityCode('UBERFLIP');

Behavior

Returns a JSON object with the details of the Privacy Group associated with the specified Hub functionality. The object contains the following properties:

• id integer: The system-defined Privacy Group ID that uniquely identifies the Privacy Group.
• name string: The user-defined name of the Privacy Group.
• description string: The user-defined description of the Privacy Group.
• version integer: The UNIX timestamp when the most recent version of the Privacy Group was published.
• isAccepted integer: Indicates whether the current visitor has accepted (1) or declined (0) the Privacy Group.
• functionalities array: A list of privacy-related Hub functionalities that has been assigned to the Privacy Group. Each is an object with the following properties:
  • id integer: The ID of the Hub functionality (specific to the Hub).
  • name string: The "friendly" name of the Hub functionality.
  • code string: The system-defined code used to reference this Hub functionality in certain methods. See below for a list of possible values.

📘

No matches

If there is no Privacy Group associated with the specified Hub functionality code on the target Hub, or if the Hub functionality code provided is not valid, null will be returned.

Example

{
  "id":405614,
  "name":"Analytics",
  "description":"Allow your page views, length of stay and other interesting metrics for big data to consume to be tracked.",
  "version":1597432246,
  "isAccepted":1,
  "functionalities":[
    {
      "id":1,
      "code":"UBERFLIP",
      "name":"Uberflip"
    }
  ]
}

Privacy.isFunctionalityEnabled()

Used to determine if a specific Hub functionality has been allowed by the current visitor. Specify the desired Hub functionality using its functionality code (e.g. UBERFLIP).

Method

Front End V1:
var isEnabled = Hubs.Privacy.isFunctionalityEnabled('UBERFLIP');

Front End V2:
var privacyGroup = uberflip.Privacy.isFunctionalityEnabled('UBERFLIP');

Behavior

Finds the Privacy Group associated with the specified Hub functionality, and returns the value of the isAccepted property of that Privacy Group.

Note that this method translates the integer value of the isAccepted property to a Boolean value, i.e. 1 is returned as true and 0 is returned as false.

📘

No matches

If there is no Privacy Group associated with the specified Hub functionality code on the target Hub, true will be returned, indicating that the functionality is allowed by the current visitor.

Note that all Hub functionalities must be linked to Privacy Groups in order to enforce visitor privacy settings — unassigned Hub functionalities will be allowed by default.

Privacy.acceptAll()

Used to accept all Privacy Groups and their associated cookies.

Method

Front End V1:
Hubs.Privacy.acceptAll();

Front End V2:
uberflip.Privacy.acceptAll();

Behavior

Sets the value of the isAccepted property to 1 for all Privacy Groups in the target Hub.

🚧

Important

Must be followed by running Privacy.applyChanges().

Privacy.rejectAll()

Used to reject all Privacy Groups and their associated cookies.

Method

Front End V1:
Hubs.Privacy.rejectAll();

Front End V2:
uberflip.Privacy.rejectAll();

Behavior

Sets the value of the isAccepted property to 0 for all Privacy Groups in the target Hub.

🚧

Important

Must be followed by running Privacy.applyChanges().

Privacy.acceptById()

Used to accept a specific Privacy Group and its associated cookies. Specify the desired Privacy Group using its Privacy Group ID (e.g. 123456).

Method

Front End V1:
Hubs.Privacy.acceptById(123456);

Front End V2:
uberflip.Privacy.acceptById(123456);

Behavior

Sets the value of the isAccepted property to 1 for the specified Privacy Group.

📘

No matches

If no Privacy Group with the specified ID exists in the target Hub, no changes are made.

🚧

Important

Must be followed by running Privacy.applyChanges().

Privacy.rejectById()

Used to reject a specific Privacy Group and its associated cookies. Specify the desired Privacy Group using its Privacy Group ID (e.g. 123456).

Method

Front End V1:
Hubs.Privacy.rejectById(123456);

Front End V2:
uberflip.Privacy.rejectById(123456);

Behavior

Sets the value of the isAccepted property to 0 for the specified Privacy Group.

📘

No matches

If no Privacy Group with the specified ID exists in the target Hub, no changes are made.

🚧

Important

Must be followed by running Privacy.applyChanges().

Privacy.applyChanges()

Used after a privacy preference has changed to reload the Hub and apply the changes.

🚧

Important

Must be run after any of the following methods have been used:

• acceptAll
• rejectAll
• acceptById
• rejectById

Method

Front End V1:
Hubs.Privacy.applyChanges();

Front End V2:
uberflip.Privacy.applyChanges();

Behavior

Reloads the Hub for the current visitor, causing all page elements to be re-rendered with their new privacy preferences applied.

Functionality codes

Each Hub functionality that can be assigned to a Privacy Group has a preset functionality code that can be used to reference it. The following functionality codes are supported: