Customer Privacy Api

The Customer privacy API is a browser-based JavaScript API that allows developers to read and write cookies associated with buyers' consent to be tracked.

The API is implemented as a property on the global window.Shopline object, and is accessible to all SHOPLINE stores.

You can use the API to build consent collection mechanisms, such as General Data Protection Regulation (GDPR) compliance banners.

For marketing and analytics use cases, you can use the API when tracking or exporting data about storefront visitors to cover GDPR compliance.

Consent collection mechanisms​

You can handle consent using the following methods:

• window.Shopline.loadFeatures - The load method must be used to ensure the API is available when the banner is initialized.
• shouldShowGDPRBanner(): boolean - Determines visibility of the GDPR banner on the storefront.
• setTrackingConsent(consent: boolean, callback: function) - Sets the visitor's consent to accept or decline after the visitor interacts with the banner.

If the API fails to load, the banner will not initialize.

Initializing​

To initialize the Client Privacy API, you need to use the loadFeatures method and initialize your banner in the callback function:

window.Shopline.loadFeatures(
  [
    {
      name: 'consent-tracking-api',
      version: '0.1'
    }
  ],
  error => {
    if (error) {
      throw error; // If the following operations are not performed, an error can be thrown in advance here
    }
    new Banner(); // or initialize your banner here
  }
)

shouldShowGDPRBanner(): boolean​

You can use this method to determine if the GDPR banner should be shown:

window.Shopline.customerPrivacy.shouldShowGDPRBanner()

Return value​

This method returns a boolean indicating whether you should display the GDPR banner to visitors.

The response summarizes the visitor's location, the merchant's preferences, and whether the visitor has provided consent value in the past year.

setTrackingConsent (consent: boolean, callback: function)​

You can use this method to set the buyer's response to tracking consent requests:

window.Shopline.customerPrivacy.setTrackingConsent(consent: boolean, callback: function)

Call parameters​

Example​

The following sample request shows a JavaScript function that sets consent to true and executes a callback function to hide the banner.

function handleAccept(e) {
  window.Shopline.customerPrivacy.setTrackingConsent(true, hideBanner);
  document.addEventListener('trackingConsentAccepted', function () {
    console.log('trackingConsentAccepted event fired');
  })
}

Callback function result​

The API executes the callback function and optionally emits a custom event called trackingConsentAccepted。

Example​

Successful requests return an object containing the status:

{
  code: "SUCCESS",
  data: true,
  message: "OK",
  success: true
}

If the request has errors, an error object is returned:

{error: [string]}

Visitor tracking​

You can use the Customer privacy API to check if a customer has consented to being tracked, and if the merchant has decided against selling visitor data. You must ensure that the API is initialized.

For visitor tracking consent, you should implement a mechanism to listen for consent collection events that can be fired asynchronously on the page to ensure you don't miss any tracking opportunities.

You can collect consent using the following methods:

• window.Shopline.loadFeatures - Executes the load method to ensure that the API is available on the storefront.
• userCanBeTracked(): boolean - covers tracking visitor (GDPR) scenarios

Tracking and data sending can continue if the Customer privacy API is not available. All methods should check that the API is available before checking whether the tracking or sale of data is blocked.

Example of API check:

if (!window.Shopline.customerPrivacy || window.Shopline.customerPrivacy.userCanBeTracked()) {
  startTracking()
}

Initializing​

To initialize the Customer Privacy API, you need to make the API available on the page using the loadFeatures method:

window.Shopline.loadFeatures(
  [
    {
      name: 'consent-tracking-api',
      version: '0.1'
    }
  ],
  error => {
    if (error) {
      throw error; // If the following operations are not performed, an error can be thrown in advance here
    }
  }
)

userCanBeTracked(): boolean​

You can use this method to return whether a storefront visitor has consented to being tracked:

window.Shopline.customerPrivacy.userCanBeTracked();

Return value​

The API returns a boolean indicating whether the user can be tracked. The response aggregates the visitor's consent and location, as well as the merchant's preferences.

Listening consent collection​

A trackingConsentAccepted event is fired when active tracking consent has been collected on the page.

By listening to this event and calling your custom start tracking method when it fires, you can avoid any possible data loss due to lack of asynchronous consent collection.

document.addEventListener('trackingConsentAccepted', function () {
  // Trigger a custom method to start tracking
});