The customer privacy API is a browser-based, JavaScript API that enables developers to read and write cookies related to a buyer's consent to be tracked. The API is implemented as a property on the global window.Shoplazza
object and is accessible to all Shoplazza online stores.
You can use the API to build consent collection mechanisms such as banners for General Data Protection Regulation (GDPR) compliance. For marketing and analytics use cases, you can use the API when tracking or exporting data about storefront visitors to cover both GDPR compliance and accordance with the California Consumer Privacy Act (CCPA).
What you'll learn
- Build consent collection into your app
- Build visitor tracking into your app
Consent collection
You can use the following methods for consent collection:
- shouldShowGDPRBanner(): boolean - Determines whether to show a GDPR banner on the storefront.
- setTrackingConsent(consent: boolean, callback: function) - Sets the visitor’s consent as accepted or declined after they interact with the banner.
Note
If you’re developing a banner application, then you need to tell merchants to block the regulation that your banner targets in their Store Admin -> Settings -> Store information -> Customer Privacy.
shouldShowGDPRBanner(): boolean
You can use this method to determine if you should show a GDPR banner.
Request data
window.Shoplazza.customerPrivacy.shouldShowGDPRBanner();
Response
This method returns a boolean value that indicates if you should show a GDPR banner to the visitor.
The response aggregates the visitor’s location, the merchant’s preference, and whether the visitor has already provided a consent value in the past year.
Visitor consent provided in past year | Visitor in EU | Merchant limits tracking for customers in Europe | Boolean value |
---|---|---|---|
Not applicable | Not applicable | ✘ | false |
✘ | ✔ | ✔ | true |
✘ | ✘ | ✔ | false |
✔ | ✔ | ✔ | false |
✔ | ✘ | ✔ | false |
setTrackingConsent(consent: boolean, callback: function)
You can use this method to set a buyer's response to a tracking consent request.
Request data
window.Shoplazza.customerPrivacy.setTrackingConsent(consent: boolean, callback: function);
Request parameters:
Name | Type | Description |
---|---|---|
consent | boolean | Indicates the buyer's response to the tracking consent request. You can obtain the response using a banner UI element or other similar mechanism. If set to true , then the API returns a custom event called trackingConsentAccepted . If set to false , then no custom event is returned but the callback function is still executed. |
callback | function | A function that executes after the API has set tracking consent. You can use this function to hide the UI banner element or execute a similar task. |
Example request:
The following example request shows a JavaScript function that sets consent
to true
and executes another function to hide the banner.
function handleAccept(e) {
window.Shoplazza.customerPrivacy.setTrackingConsent(true, hideBanner);
document.addEventListener("trackingConsentAccepted", function () {
console.log("trackingConsentAccepted event fired");
});
}
Response
The API executes the callback function and optionally emits a custom event called trackingConsentAccepted
.
Example response:
A successful request returns an empty object:
{ }
If there is an error with the request, then an error object is returned:
{error:[string]}
Visitor tracking
You can use the Customer Privacy API to check if customers have consented to be tracked and if merchants have decided to disallow the sale of visitor data. For visitor tracking consent, you should implement a mechanism for listening to consent collection events that can fire asynchronously on the page, to ensure that you don't miss any tracking opportunities.
You can use the following methods for consent collection:
- userCanBeTracked(): boolean - Covers the scenario of tracking a visitor (GDPR).
- userDataCanBeSold(): boolean - Covers the scenario of selling visitor data (CCPA).
If userCanBeTracked
is set to false
, then the following behaviour must be observed:
- No persistent, non-essential cookies should be set
- No data should be emitted to third-party platforms
If userDataCanBeSold
is set to false
, then the following behaviour must be observed:
- Data can be emitted (if tracking isn't blocked)
- Data can't be sold to third-parties
If the Customer Privacy API isn't available, then tracking and data emission can proceed. All methods should be preceded with a check that the API is available before checking that tracking or sale of data is blocked.
Example API check:
if (!window.Shoplazza.customerPrivacy || window.Shoplazza.customerPrivacy.userCanBeTracked()) { startTracking() }
userCanBeTracked(): boolean
You can use this method to return whether the storefront visitor has consented to be tracked.
Request data
window.Shoplazza.customerPrivacy.userCanBeTracked();
Response
The API returns a boolean value that indicates whether a user can be tracked.
The response aggregates the visitor’s consent and location, as well as the merchant’s preference.
Visitor consent | Visitor in EU | Merchant limits tracking for customers in Europe | Boolean value |
---|---|---|---|
Not applicable | Not applicable | ✘ | false |
✔ | ✔ | ✔ | true |
✔ | ✘ | ✔ | true |
✘ | ✔ | ✔ | false |
✘ | ✘ | ✔ | false |
Undeclared | ✔ | ✔ | false |
Undeclared | ✘ | ✔ | true |
Listening for consent collection
A trackingConsentAccepted
event fires when positive tracking consent is collected on the page.
By listening for this event and calling your custom start tracking method when it fires, you avoid any possible data loss due to missing asynchronous consent collection.
document.addEventListener('trackingConsentAccepted', () => {
// fire custom method to start tracking
});
userDataCanBeSold(): boolean
You can use this method to determine if the merchant has decided to explicitly disallow the sale of data to third parties for visitors located in California. This enables compliance with CCPA.
Request Data
window.Shoplazza.customerPrivacy.userDataCanBeSold();
Response
The API returns a boolean value indicating whether data can be sole to third parties for visitors located in California.
The API response aggregates the merchant’s preferences and the visitor’s location. However, you can't use the API to enable visitors to opt-out of the sale of their data.
User consent | Visitor in California | Merchant limits the third-party sale of California customers’ data | Boolean value |
---|---|---|---|
Not applicable | ✔ | ✔ | false |
Not applicable | ✘ | ✔ | true |
Not applicable | ✔ | ✘ | true |
Not applicable | ✘ | ✘ | true |