__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
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
1
function usapi_callback(uspData, success) {
2
// your custom callback code can be included here
3
console.log(uspData, ' + ', success);
4
}
5
6
__uspapi('getUSPData', 1 , usapi_callback);
Copied!
1
// call the __uspapi() function from the browser console
2
__uspapi('getUSPData', 1 , function(uspData, success) {console.log(uspData, success);});
Copied!
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
1
{version: 1, uspString: "1YNN", newUser: null, dateCreated: null}
2
3
dateCreated: null
4
newUser: null
5
uspString: "1YNN"
6
version: 1
Copied!

Read uspString

The uspString value in the JSON response is an encoded 4 character string that contains the following information:
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”.
Last modified 4mo ago