Skip to main content

API Functions (Global for Web)

LR CMP API

__lrcmp(command, [version], [callback], [parameter])

Argument Name

Type

Value

command

String

Name of the command to execute

version

number

Optional parameter, version of the API, currently v1.0

callback

function

Function to be executed with the result of the command

parameter

number

Parameter to be passed to the command function

Commands

getVendorList

The getVendorList command retrieves the currently used vendor list from local storage or fetches from URL if vendor list is not yet stored.

__lrcmp('getVendorList', 2, (resfunctionult) => {console.log(result)});

Argument Name

Type

Value

command

string

'getVendorList'

version

number

(ignored) or 2

callback(result)

function

function(result: object)

To return the vendor list.

parameter

(ignored)

Function call

__lrcmp('getVendorList', null, (data, success) => {console.log(data)})

Returns

lastUpdated: "2021-07-08T17:13:16.041Z"
policyVersion: 1
purposes: {1: {…}, 2: {…}, 3: {…}, 4: {…}, 5: {…}, 6: {…}, 7: {…}}
specificationVersion: 1
vendorListVersion: 4
vendors: {1: {…}, 2: {…}, 3: {…}...}

ping

Gets CMP metadata.

__lrcmp('ping', null, (pingReturn) => {console.log(pingReturn)})

Argument Name

Type

Value

command

string

'ping'

version

number

(ignored)

callback

function

Function to be executed with the result of the command

parameter

(ignored)

What the function returns

CMP Metadata

Argument Name

Value

apiVersion

current api version as string

cmpApplies

true if publisher has configured CMP to apply to visitor's country

cmpLoaded

true if GlobalCmp main script is loaded, false if still running stub

cmpStatus

stub | loaded | error

displayStatus

visible | hidden | disabled

apiVersion

'1.0', // version of the GlobalCmp API that is supported, e.g. "1.0"

cmpVersion

GlobalCmp's own/internal version that is currently running

vendorListVersion

Version of the list currently loaded by the CMP

policyVersion

Policy version of vendor list

Function call

__lrcmp('ping', null, (data, success) => {console.log(data)})

Returns

apiVersion: "1.0"
cmpApplies: true
cmpLoaded: true
cmpStatus: "loaded"
cmpVersion: 1
displayStatus: "visible"
policyVersion: 1
vendorListVersion: 4

Get consent data

Retrieves consent status for all vendors and publisher or consent status for specific vendors.

Argument Name

Type

Value

command

string

''getConsentData'

version

number

(ignored)

callback

function

Function to be executed with the result of the command

parameter

null | Array<number>. If no argument is passed, return consent status for publisher and all vendors. If array of numbers is passed return consent status for vendors whose id is inside that array. Null can be passed inside the array to get the data for publisher.

What the function returns

  • Consent status metadata with consent status for all vendors and publisher, if no argument is passed

  • Consent status metadata with consent status for specific vendor, if array of vendor IDs is passed

Function call

__lrcmp('getConsentData', null, (data, success) => {console.log(data)})

Returns

cmpApplies: true
cmpStatus: "loaded"
cmpVersion: 1
eventStatus: "cmpuishown"
policyVersion: 1
publisher: {
  consent: true
  legitimateInterest: true
  purposes {
    consents: {1: true, 2: false, 3: false, 4: false, 5: false, 6: false}
    legitimateInterests: {1: false, 2: true, 3: true, 4: false, 5: false, 6: true}
  }
},
vendors: {
  1: {
    consent: true
    legitimateInterest: true
    purposes:
    consents: {1: true, 2: false, 3: false, 4: false, 5: true}
    legitimateInterests: {1: false, 2: true, 3: false, 4: false, 5: false}
  },
  2: {consent: false, legitimateInterest: true, purposes: {…}}
  4: {consent: true, legitimateInterest: false, purposes: {…}}
}

Function call

__lrcmp('getConsentData', null, (data, success) => {console.log(data)}, [1])

Returns

cmpApplies: true
cmpStatus: "loaded"
cmpVersion: 1
eventStatus: "cmpuishown"
policyVersion: 1
publisher: {
  consent: true
  legitimateInterest: true
  purposes {
    consents: {1: true, 2: false, 3: false, 4: false, 5: false, 6: false}
    legitimateInterests: {1: false, 2: true, 3: true, 4: false, 5: false, 6: true}
  }
},
vendors: {
  1: {
    consent: true
    legitimateInterest: true
    purposes:
    consents: {1: true, 2: false, 3: false, 4: false, 5: true}
    legitimateInterests: {1: false, 2: true, 3: false, 4: false, 5: false}
  }
}

Function call

Get consent data for vendor with id 1 and publisher. Null is for publisher

__lrcmp('getConsentData', null, (data, success) => {console.log(data)}, [1, null])

Returns

cmpApplies: true
cmpStatus: "loaded"
cmpVersion: 1
eventStatus: "cmpuishown"
policyVersion: 1
vendors: {
  1: {
    consent: true
    legitimateInterest: true
    purposes:
    consents: {1: true, 2: false, 3: false, 4: false, 5: true}
    legitimateInterests: {1: false, 2: true, 3: false, 4: false, 5: false}
  }
}

Accept (give consent)

Gives consent to the publisher, all vendors and their purposes, or gives consent to a specific vendor.

Argument Name

Type

Value

command

string

'accept'

version

number

(ignored)

callback

function

Function to be executed with the result of the command

parameter

Array

null | Vendor | Publisher

If no parameter or null is passed, function acts as accept all.

Parameter examples:

Vendor: { vendors:
    {
      1:
        {
          consent: true,
          legitimateInterest: true,
          purposes: [1, 3, 5],
          legIntPurposes: [2]
        }
      },
      2:
        {
          ...
        }
    }
  Publisher: {
    publisher:
      {
        consent: true,
        legitimateInterest: true,
        purposes: [1, 3, 5],
        legIntPurposes: [2]
      }
  }

Any vendor or publisher property can be omitted.

What the function returns

No return value.

Function call

Accept all example

__lrcmp('accept', null, (data, success) => {console.log(success)})

Returns

true | false

Function call

Give consent only to vendor with id 1 but not to his purposes

__lrcmp('accept', null, (data, success) => {console.log(success)}, { vendors: {  1: {  consent: true, legitimateInterest: true } }})

Returns

true | false

Function call

Give consent only to purposes for vendor with id 1

__lrcmp('accept', null, (data, success) => {console.log(success)}, { vendors: {  1: {  purposes: [1, 3, 5], legIntPurposes: [2] } }})

Returns

true | false

Function call

Give consent to vendor with id 1 and to his purposes

__lrcmp('accept', null, (data, success) => {console.log(success)}, { vendors: {  1: {  consent: true, legitimateInterest: true, purposes: [1, 3, 5], legIntPurposes: [2] } }})

Returns

true | false

Function call

Give consent to publisher and to his purposes

__lrcmp('accept', null, (data, success) => {console.log(success)}, {publisher: { consent: true, legitimateInterest: true, purposes: [1, 5], legIntPurposes: [2]}})

Returns

true | false

Reject (revoke consent)

Revokes consent from the publisher, all vendors and their purposes, or revokes consent from a specific vendor.

Argument Name

Type

Value

command

string

'reject'

version

number

(ignored)

callback

function

Function to be executed with the result of the command

parameter

Array

null | Vendor | Publisher.

If no parameter or null is passed, function acts as reject all.

Parameter examples:

  Vendor: { vendors:

    {

      1:

        {

          consent: false,

          legitimateInterest: false,

          purposes: [1, 3, 5],

          legIntPurposes: [2]

        }

      },

      2:

        {

          ...

        }

    }
Publisher: {

    publisher:

      {

        consent: false,

        legitimateInterest: false,

        purposes: [1, 3, 5],

        legIntPurposes: [2]

      }
  } 

Any vendor or publisher property can be omitted.

What the function returns

No return value.

Function call

Reject all example

__lrcmp('reject', null, (data, success) => {console.log(success)})

Returns

true | false

Function call

Revoke consent only from vendor with id 1 but not from his purposes

__lrcmp('reject', null, (data, success) => {console.log(success)}, { vendors: {  1: {  consent: false, legitimateInterest: false } }})

Returns

true | false

Function call

Revoke consent only from purposes for vendor with id 1

__lrcmp('reject', null, (data, success) => {console.log(success)}, { vendors: {  1: {  purposes: [1, 3, 5], legIntPurposes: [2] } }})

Returns

true | false

Function call

Revoke consent from vendor with id 1 and from his purposes

__lrcmp('reject', null, (data, success) => {console.log(success)}, { vendors: {  1: {  consent: false, legitimateInterest: false, purposes: [1, 3, 5], legIntPurposes: [2] } }})

Returns

true | false

Function call

revoke consent from publisher and from his purposes

__lrcmp('reject', null, (data, success) => {console.log(success)}, {publisher: { consent: false, legitimateInterest: false, purposes: [1, 5], legIntPurposes: [2]}})

Returns

true | false

{tcfPolicyVersion: 2, cmpId: 3, cmpVersion: 1, gdprApplies: true, tcString: "CO69m8oO9K-yuADABCENBBCsAPPAAAAAAAAAADNQAAAAAA.YAAAAAAAAAA", …}
cmpId: 3
cmpStatus: "loaded"
cmpVersion: 1
eventStatus: "cmpuishown"
gdprApplies: true
isServiceSpecific: true
listenerId: null
publisher: {consents: {…}, legitimateInterests: {…}}
publisherCC: "aa"
purpose: {consents: {…}, legitimateInterests: {…}}
purposeOneTreatment: false
specialFeatureOptins: {1: true, 2: true}
tcString: "CO69m8oO9K-yuADABCENBBCsAPPAAAAAAAAAADNQAAAAAA.YAAAAAAAAAA"
tcStringCustom: "CO69m8oO9K-yuADABCENBBCgAAAAAAAAAAAAAAAAAAAA.YAAAAAAAAAA"
tcfPolicyVersion: 2
useNonStandardStacks: false
vendor: {consents: {…}, legitimateInterests: {…}}

CMP Applies

Gets the information on whether the CMP applies or not. If a user is located in a country that is configured as supported, CMP will apply. Otherwise, CMP will not apply.

Argument Name

Type

Value

command

string

'cmpApplies'

version

number

(ignored)

callback

function

Function to be executed with the result of the command

parameter

(ignored)

Function call

__lrcmp('cmpApplies', null, (data, success) => {console.log(data)})

What the function returns

true | false. True if cmp applies, false otherwise

getAuditID

Retrieves the audit id of a user.

Argument Name

Type

Value

command

string

'getAuditId'

version

number

(ignored)

callback

function

Function to be executed with the result of the command

parameter

(ignored)

What the function returns

AuditId of a user.

Function call

__lrcmp('getAuditId', null, (data, success) => {console.log(data)})

What the function returns

dc01394316bd4c8f9bfc7b79b4c58571

resetAuditId

Generates and returns a new Audit ID.

Argument Name

Type

Value

command

string

'resetAuditId'

version

number

(ignored)

callback

function

Function to be executed with the result of the command

parameter

(ignored)

What the function returns

Newly generated Audit Id.

Function call

__lrcmp('resetAuditId', null, (data, success) => {console.log(data)})

What the function returns

56bfdb5d835648cf99940d930ebc68b9

toggleConsentTool

The toggleConsentTool command will surface the notice screen at any given time regardless of consent state.

__lrcmp('toggleConsentTool', 2, (result) => {console.log(result)}, [parameter]);

Argument Name

Type

Value

command

string

'toggleConsentTool'

version

number

(ignored) or 2

callback(result)

function

function(result: Void)

Consent notice or manager will be toggled (i.e. it would be shown or hidden based on current state). If in configuration noticeConfig.display is set to false consent manager will be displayed else consent notice will be displayed.

parameter

Optional(boolean)

If passed it will be used to force consent tool state to show or hide regardless of the current state.

You can embed this API to be triggered to hide or show consent tool regardless of the current state. At the same time this API can also be used to toggle around consent notice or manager based on the boolean value of noticeConfig.display in the configuration.

checkConsent

The checkConsent command will return an object whether or not there is consent for the given vendor.

__lrcmp("checkConsent", 2 ,(data, success)=>{console.log(data)}, [parameter]);

Argument Name

Type

Value

command

string

'checkConsent'

version

number

2

callback(result)

function

function(result: boolean)

True if there's consent for provided vendors.

parameter

Array|Object

Array of objects or only object with vendorId, purposeIds and featureIds properties to check consent for if no data or invalid one is provided result will be false.

recheckConsentOnChange=true

Will trigger every time the consent status has changed by listening to the event consent changed. It will be invoked depending on the event.

Per vendor

  • Passing the perVendor parameter as false will return a boolean regarding all the data which was passed.

  • Passing the perVendor parameter as true will return an array of objects, and each object will represent consent per vendor from the passed data.

Example 1

Checking vendorId: 33 and purposeIds: [1,3,5,6] :

__lrcmp("checkConsent", 2, (data, success) => {
    console.log(data)
}, {
    data: [{
        vendorId: 33,
        purposeIds: [1, 3, 5, 6]
    }]
});

Note

If you provide features or/and purposes together with vendorId it will check if that vendor has only those purposes enabled.

So incase purposeIds: [1, 3, 5] is true and purposeIds: [ 6 ] is revoked (false) through the UI. Passing the following command:

__lrcmp("checkConsent", 2, (data, success) => {
    console.log(data)
}, {
    data: [{
        vendorId: 33,
        purposeIds: [1, 3, 5]
    }]
});

Will return true because purpose 6 is not included in the purposeIds Array.

Example 2

If you want to check consent for vendor and all purposes and special features that are associated with it in the global vendor list, you can just pass vendorId:

__lrcmp("checkConsent", 2, (data, success) => {
    console.log(data)
}, {
    data: {
        vendorId: 33
    }
});

In this case the command will check vendorId: 33 and purposeIds: [1, 3, 5, 6] and the return boolean value will reflect the consent state of these purposes as well as the vendor.

Example 3

In this example we tackle the following parameters:

  • recheckConsentOnChange: true

  • Custom vendorId: [10007, 10009] (Facebook, LinkedIn)

  • perVendor: true we are passing/checking more than one vendor ID which will create array of objects, and each object will represent consent pre vendor from the passed data.

        window.__lrcmp('checkConsent', null, function (data, success) {
            console.log(data);        
        }, {
            data: [{
                "vendorId": 10007
            }, {
                "vendorId": 10009
            }],
            recheckConsentOnChange: true,
            perVendor: true
        });

Response, if vendorId: [10007, 10009 ] are in the config and consented:

(2)[{
    0: hasConsent: true
    vendorId: 10007
    vendorName: "Facebook"
    __proto__: Object
}, {
    1: hasConsent: true
    vendorId: 10009
    vendorName: "LinkedIn"
}]

From here for custom solutions (conditional firing) it is recommended to check for the hasConsent property and populate an array or an object with the values, so it can be used later for triggering a certain tag or a function:

window.__lrcmp('checkConsent', null, function (data, success) {
    // a different approach can be integrated here to store 
    //   the vendor boolean values as a refrence. 

    const vendorsWithConsentHc = [];

    if (data && data.length) {
        data.forEach((item) => {
            if (item.hasConsent && item.vendorName) {
                vendorsWithConsentHc.push(item.vendorId);
            }
        });
    }

    window.consentlayer = window.consentlayer || [];
    window.consentlayer.push({
        vendorsWithConsentHc
    });

}, {
    data: [{
        "vendorId": 10007
    }, {
        "vendorId": 10021
    }],
    recheckConsentOnChange: true,
    perVendor: true
});

getConsentCriteria

The getConsentCriteria retrieves the information about the configured vendors with publisher and/or purposes for a configuration.

Argument Name

Type

Value

command

string

getConsentCriteria

version

number

(ignored)

callback(result)

function

Function to be executed with the result of the command.

parameter

string

null | {vendors: boolean, purposes: boolean}. If no argument is passed, return object with vendors and purposes. If vendors or purposes are set to true, only items that are set to true will be returned. Both vendors and purposes properties are optional.

Returns

Object with configured vendors and/or purposes.

Example 1

__lrcmp('getConsentCriteria', null, (data, success) => {console.log(data)})

Returns

{
  vendors: {
    1: "Exponential Interactive, Inc d/b/a VDX.tv",
    2: "Captify Technologies Limited",
    3: "affilinet",
    0: "Publisher / Brand"
  },
  purposes: {
    1: "Store and/or access information on a device",
    2: "Strictly Necessary",
    3: "Functional",
    4: "Analytics",
    5: "Marketing",
    6: "Personalization",
    7: "Social Media"
  }
}

Example 2

__lrcmp('getConsentCriteria', null, (data, success) => {console.log(data)}, { vendors: true })

Returns

{
  vendors: {
    1: "Exponential Interactive, Inc d/b/a VDX.tv",
    2: "Captify Technologies Limited",
    3: "affilinet",
    0: "Publisher / Brand"
  }
}

Example 3

__lrcmp('getConsentCriteria', null, (data, success) => {console.log(data)}, { purposes: true })

Returns

{
  purposes: {
    1: "Store and/or access information on a device",
    2: "Strictly Necessary",
    3: "Functional",
    4: "Analytics",
    5: "Marketing",
    6: "Personalization",
    7: "Social Media"
  }
}

Example 4

__lrcmp('getConsentCriteria', null, (data, success) => {console.log(data)}, { purposes: true, vendors: true })

Returns

{
  vendors: {
    1: "Exponential Interactive, Inc d/b/a VDX.tv",
    2: "Captify Technologies Limited",
    3: "affilinet",
    0: "Publisher / Brand"
  },
  purposes: {
    1: "Store and/or access information on a device",
    2: "Strictly Necessary",
    3: "Functional",
    4: "Analytics",
    5: "Marketing",
    6: "Personalization",
    7: "Social Media"
  }
}

addEventListener

The addEventListener command registers a callback function with the CMP. The listener's callback is triggered when for example the consent string status has changed. The listener is registered with an ID for later removal.

__lrcmp('addEventListener', 2, (tcData, success) => {console.log(tcData)}, [parameter]);

Argument Name

Type

Value

command

string

'addEventListener'

version

number

(ignored) or 2

callback(result)

function

`result (Object, Boolean)`: Object containing the event name or listenerId and any data the event may return, Boolean if success

parameter

String

Name of the event to listen to.

You can choose the event name from the list in "Events."

Note

If addEventListener command is called without parameter, on every change you should get tcData object based on the specs containing the event listenerId.

If LiveRamps custom events were passed as a parameter. e.g. consentChanged then no listenerId will be returned. You can remove it removeEventListener by passing event name instead of an ID.

removeEventListener

The removeEventListener command removes the event listener.

__lrcmp('removeEventListener', 2, (result) => {console.log(tcData)}, [parameter]);

Argument Name

Type

Value

command

string

'removeEventListener'

version

number

(ignored) or 2

callback(result)

function

function(result:boolean)

Callback function to remove as a listener, boolean if success.

parameter

number|string

Unique ID assigned by the CMP to the registered callback (via addEventListener) or event name.

You can choose the event name from the list in "Events."