JavaScript API

The following section documents commands that can be used with the global PrivacyID() function created by the embed snippet.

PrivacyID(<command>, <command parameters>);

You can invoke PrivacyID commands anywhere on your page, as long as your commands appear below the global embed snippet.

Commands

• endpoint

• consentCategories

• requireConsent

• userId

• getIdentity

endpoint

Specifies the URL to the API Endpoint you implemented on your web server for identifying the user.

PrivacyID('endpoint', '<endpoint>');

Argument	Type	Example	Description
<endpoint>	string	“/api/privacyId”	The path or URL to the API endpoint on your web server for identifying the user.

The getIdentity command will delay execution until a value for this property is provided.

Example

PrivacyID('endpoint', '/api/privacyId');

consentCategories

Specifies the script categories which the user has allowed to access their user ID.

Each script you define in the PrivacyID portal can have one or more consent categories associated with it. The getIdentity command will only provide user IDs to scripts where all script categories have been allowed by the user.

PrivacyID('consentCategories', [<categories>]);

Argument	Type	Example	Description
[<categories>]	Array<string>	[“functional”, “analytics”]	An array of string category names which have been allowed by the user. This value could come from your system or a third-party cookie consent service which you have integrated into your website.

By default, PrivacyID will delay the execution of the getIdentity command until consent categories are provided. If your website does not use consent categories, you can set the requireConsent property to false to avoid this delay.

Example

// Example integration with 3rd party Cookie Script service.
CookieScript.instance.onAccept = function() {
  var state = CookieScript.instance.currentState();
  PrivacyID('consentCategories', state.categories);  
};

requireConsent

Specifies whether PrivacyID should wait for consent categories to be defined before providing user IDs to scripts. Defaults to true.

PrivacyID('requireConsent', <value>);

Argument	Type	Example	Description
<value>	boolean	false	Specify false to disable consent categories and

Example

PrivacyID('requireConsent', false);

userId

Associates a persistent ID with the user to help PrivacyID identify them in future visits in the event that the user cookie is lost.

This property should only be specified when you can guarantee that the value you pass in will be uniquely consistent to the user. For example, good value to use could be an email address or a unique customer ID of a logged in user. The value provided will be hashed before it is used to ensure that no PII (personally identifiable information) is transmitted or stored outside of your servers.

PrivacyID('userId', <userId>);

Argument	Type	Example	Description
<userId>	string	1234-5678-9101	A unique persistent value to associate with the user. E.g. a unique customer ID of a logged in user.

You should only specify a value for the userId property if you can ensure that is unique to the user. If the same value is provided to different users accidentally then PrivacyID will start to provide the same user identities to multiple users which will lead to misidentification, affecting any scripts that rely on PrivacyID.

Example

PrivacyID('userId', '1234-5678-9101');

getIdentity

Returns unique, consistent user IDs for each script integrated on your website.

This command should be used for each script integrated into your website which needs to uniquely identify the user. The callback function you provide will be invoked once the user is identified and a user ID will be available if the script is currently enabled within the PrivacyID portal and the user has consented to all categories required by the script.

PrivacyID('getIdentity', '<scriptKey>', <callback>);

Argument	Type	Example	Description
<scriptKey>	string	6ee2aa22-8ea8-4ad0-9353-5a714151ebf6	The unique identifier that represents your script. This is available in the PrivacyID portal.
<callback>	Function	(userId) => console.log(userId)	A callback function to be invoked with the user identity. The user ID provided will either be a string or undefined if the script is not authorized to access the user ID.

Responses to this command will be queued until the endpoint and consentCategories properties have been provided.

Example

PrivacyID('getIdentity', '0318b158-5bcc-497a-a526-718b18d1600b', function(userId) {
  console.log(userId);
});

Example with Google Analytics

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-1234567890"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'G-1234567890');
  
  PrivacyID('getIdentity', '0318b158-5bcc-497a-a526-718b18d1600b', function(userId) {
    gtag('config', 'G-XXXXXXXXXX', {
      'user_id': userId
    });
  });
</script>