__uspapi() function

The IAB __uspapifunction applies to CCPA campaigns being run in your organization's CMP. Your organization can use these Javascript commands to perform actions specific to your needs.

At present, the IAB CCPA implementation supports one command, getUSPData. Click here to find more information about the CCPA API from the IAB.

__uspapi argument

The __uspapi function takes three arguments: the command, US privacy version and callback function:

Argument description
Argument description

Argument

Description

Command

The specific action your organization wishes to perform.

US Privacy Specification version

The API version, this is usually set to '1'.

Callback function

A callback function can be custom code defined by your organization to complete a task depending on the value of success and using the data in tcData. See below for more information.

Your organization could write a custom callback function that returns the contents in the uspData.

The callback function has two arguments:

  • uspData - a JSON object that contains the unencoded values of the string

  • success - a boolean value (true/false) that informs if the command request was successful

The callback function should be called immediately and without any asynchronous logic. The callback shall be invoked only once per API call with this command.

A value of false will be passed as the value to the success argument to the callback when no uspData object could be returned.

__uspapi command & response

The __uspapi function currently provides one command, getUSPData.

The getUSPData command allows your organization to retrieve values of the uspString, an encoded 4 character string that describes the end-user's consent. The command also provides additional information such as if the CCPA applies to the end-user and more.

The API response is a JSON string with values for dateCreated, newUser, uspString and version.

Code example
Browser console command
API response
Code example
function usapi_callback(uspData, success) {
// your custom callback code can be included here
console.log(uspData, ' + ', success);
}
__uspapi('getUSPData', 1 , usapi_callback);
Browser console command
// call the __uspapi() function from the browser console
__uspapi('getUSPData', 1 , function(uspData, success) {console.log(uspData, success);});
API response

The getUSPData response is a JSON string with these values:

Parameter

Description

dateCreated

date when JSON string was created

newUser

Is the end-user a first time visitor?

uspString

An encoded 4-character string describes the end-user consent. Click here for information on reading the uspString.

version

A number indicating the US Privacy spec

version

{version: 1, uspString: "1YNN", newUser: null, dateCreated: null}
dateCreated: null
newUser: null
uspString: "1YNN"
version: 1

Read uspString

The uspString value in the JSON response is an encoded 4 character string that contains the following information:

uspString Description
uspString Description

Character position

Description

Expected values

First character

Specification version. Currently set to '1'

'1'

Second character

Has explicit notice been provided and the opportunity to opt out of the sale of their data?

Y/N

Third character

Has the end-user opted-out of the sale of his or her personal information?

Y/N

Fourth character

Publisher is a signatory to the IAB Limited Service Provider Agreement (LSPA).

Y/N

Examples

Each character can be 'Y' for true, 'N' for false or '-' for not applicable to the end-user's current browsing situation.

If US Privacy does not apply to an end-user then the uspString value will be “1---”.

If 'Do Not Sell' applies and the end-user does not give consent then the uspString value will be “1YYY”.

If 'Do Not Sell' does not apply and the end-user gives consent then the uspString value will be “1YNY”.