---
url: customer-privacy-api
sidebar_position: 5
---

# 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](#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](#visitor-tracking) to cover GDPR compliance.

:::note
To use the Customer privacy API, merchants must restrict data collection for the App's target region in their store admin settings.
:::

## Consent collection mechanisms
You can handle consent using the following methods:

- [window.Shopline.loadFeatures](#Initializing) - The load method must be used to ensure the API is available when the banner is initialized.
- [shouldShowGDPRBanner(): boolean](#shouldshowgdprbanner-boolean) - Determines visibility of the GDPR banner on the storefront.
- [setTrackingConsent(consent: boolean, callback: function)](#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{#Initializing}
To initialize the Client Privacy API, you need to use the loadFeatures method and initialize your banner in the callback function:

```java
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:
```java
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.

| Visitor consent form provided in the past year | EU visitors | Merchants limit tracking for European customers | Boolean value |
| --- | --- | --- | --- |
| Not applicable | Not applicable | ✘ | `false` |
| ✘ | ✔ | ✔ | `true` |
| ✘ | ✘ | ✔ | `false` |
| ✔ | ✔ | ✔ | `false` |
| ✔ | ✘ | ✔ | `false` |

### setTrackingConsent (consent: boolean, callback: function)
You can use this method to set the buyer's response to tracking consent requests:
```java
window.Shopline.customerPrivacy.setTrackingConsent(consent: boolean, callback: function)
```

#### Call parameters
| Parameter | Type | Description |
| --- | --- | --- |
| consent | boolean | <li>Represents the buyer's response to a tracking consent request. You can use banner UI elements or other similar mechanisms to get responses. </li> <li>If set to true, the API returns a custom event called trackingConsentAccepted. </li>If set to false, no custom event will be returned, but the callback function will still be executed. |
| callback | function | Function to execute after the API has set tracking consent. You can use this feature to hide UI banner elements or perform similar tasks. |

#### Example
The following sample request shows a JavaScript function that sets consent to true and executes a callback function to hide the banner.
```java
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:
```json
{
  code: "SUCCESS",
  data: true,
  message: "OK",
  success: true
}
```
If the request has errors, an error object is returned:
```json
{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](#Initializing). 

<br/>For visitor tracking consent, you should implement a mechanism to [listen for consent collection events that can be fired asynchronously on the page](#listening-consent-collection) to ensure you don't miss any tracking opportunities.

You can collect consent using the following methods:

- [window.Shopline.loadFeatures](#Initializing_01) - Executes the load method to ensure that the API is available on the storefront.
- [userCanBeTracked(): boolean](#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:
```java
if (!window.Shopline.customerPrivacy || window.Shopline.customerPrivacy.userCanBeTracked()) {
  startTracking()
}
```

### Initializing{#Initializing_01}
To initialize the Customer Privacy API, you need to make the API available on the page using the loadFeatures method:
```java
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:
```java
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.

| Visitor's Consent | EU visitors | Merchants limit tracking for European customers | Boolean value |
| :--- | :--- | :---: | :--- |
| Not applicable | Not applicable | ✘ | `false` |
| ✔ | ✔ | ✔ | `true` |
| ✔ | ✘ | ✔ | `true` |
| ✘ | ✔ | ✔ | `false` |
| ✘ | ✘ | ✔ | `false` |
| undeclared | ✔ | ✔ | `false` |
| undeclared | ✘ | ✔ | `true` |

#### 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.

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