@washingtonpost/wp-uspapi

USPAPI

Need to use this for another project? It's a NPM package!

https://www.npmjs.com/package/@washingtonpost/wp-uspapi

Getting started

npm install

Run unit tests: npm run test

Production build: npm run build

Validating it works in a browser:

__uspapi('getUSPData', 1, (uspData, success) => {
    if (success) { console.debug(uspData, success) }
    else { console.error('no') }
});

What is this?

This provides window.__uspapi which is needed by ad systems, third party trackers, and any operation that touches user data for CCPA for California residents and CDPA for Virginia residents.

The US Privacy API is our control mechanism for allowing users to opt out of tracking under the California CCPA and Virginia CDPA regulations. Users are eligible for use of the US Privacy API and the Do Not Sell mode if they are California or Virginia residents (as determined by their billing address) or have a California or Virginia geolocation.

Because the California law is strong and protects users outside of the CA Geo, we also use it to grant EU users the ability to opt-out of tracking under the promise we make them when they encounter our TCF banner in the EU and European Economic Area. We call this “EEA Ad Consent” mode, or “EAC”.

Finally, CA and VA residents are also eligible to use the Global Privacy Control. Normally users who wish to opt out do so using the Do Not Sell link in our footer (only available to VA & CA-residents or Geo). However, they can also do so using a signal at the browser level. GPC is that signal and can be activated in Chrome or Edge using a plugin or using a custom configuration for Firefox.

This package is intended to be a one stop shop for implementing the API which, to resolve race conditions, may need to be implimented more than once on the page. It is set up in order to support that approach.

Unit tests cover the functionality of this package under CA, VA and EAC settings.

Using this package

Including this package in your library will not automatically activate the USP API. You have to initiate it like so:

try {
	new Uspapi({
		log() {},
		debug: console.debug,
	});
} catch (e) {
	console.error('USP API attachment may have failed.');
}

Initiating Arguments

This class takes an object that emulates the structure of console. You can pass console directly in on browser-facing software. You can also use this structure to pass in your own logging objects or NOOP functions. The USPAPI library makes use of log for verbose console logging to understand program flow. It makes use of debug to message the console about errors and issues that might disrupt its proper functioning.

The Window Object

On class initiation the USP API library will attach itself to the window object along with any necessary other objects. You do not need to attach it to the window object yourself.

How to test

Use The Washington Post Confluence pages under Washington Post Data Privacy > Technical Guidance to find and leverage testing instructions.

Release Process

Make sure you are up to date

git pull git status npm ci npm test

Prepare the Release

npm run build

Update version numbers

Either use npm version or manually update the version in package.json & package-lock.json.

git tag 2.0.0

Publish

npm publish git push git push --tags

Changelog

6.x

With version 6 we move away from parsing a geo cookie directly and move to using an on-page Privacy API. That is now an unlisted dependency for implementation.