API Reference

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 returns additional information such as when the uspString was created, if the end-user is a new user, etc...


Command

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

__uspapi('getUSPData', 1 , usapi_callback);

Response

{
  dateCreated: "2023-05-23T13:27:06.187Z",
  gpcEnabled: false,
  newUser: true,
  uspString: "1YNN",
  version: 1
}
schema:
  description: Response for getUSPData
  type: object
  properties:
    dateCreated:
      type: string
      description: Date when uspData object was created.
      example: 2023-05-23T13:27:06.187Z
    gpcEnabled:
      type: boolean
      description: Is GPC signal enabled on the end-user browser? [Click here](https://docs.sourcepoint.com/hc/en-us/articles/8357018608019-Global-Privacy-Control-GPC-) for more information on Global Privacy Control (GPC).
      example: false
    newUser:
      type: boolean
      description: Is the end-user a first time visitor to the property?
      example: true
    uspString:
      type: string
      description: An encoded 4-character string describes the end-user consent.
      example: 1YNN
    version:
      type: integer
      description: A number indicating the US Privacy spec version
      example: 1

Read uspString

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

Character positionDescriptionExpected values
First characterSpecification version. Currently set to 11
Second characterHas explicit notice been provided and the opportunity to opt out of the sale of their data been presented?Y/N/-
Third characterHas the end-user opted-out of the sale of his or her personal information?Y/N/-
Fourth characterPublisher is a signatory to the IAB Limited Service Provider Agreement (LSPA).Y/N/-

The returned values for the second, third, and fourth characters in the uspString mean the following:

  • Y = true
  • N = false
  • - = not applicable to the end-user's current browsing session

📘

Examples

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.