The IAB __uspapi function 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.
Note: 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 | 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. |
Note: 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.
function usapi_callback(uspData, success) {
// your custom callback code can be included here
console.log(uspData, ' + ', success);
}
__uspapi('getUSPData', 1 , usapi_callback);// call the __uspapi() function from the browser console
__uspapi('getUSPData', 1 , function(uspData, success) {console.log(uspData, success);});
getUSPData response is a JSON string with these values:
| Parameter | Description |
dateCreated |
Date when JSON string was created |
gpcEnabled |
Click here for more information on Global Privacy Control (GPC).
|
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
gpcEnabled: false
newUser: false
uspString: "1YNN"
version: 1Read 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”.