Use server-side first party cookies to identify and track users on your website. You can create and collect first party, server-side cookies through Treasure Data's Javascript SDK.

The flow of collecting user data on your website is:

  1. A user accesses your website. Treasure Data checks to see if a td_ssc_id cookie exists for the user.

    1. If yes, activities are tracked through Treasure Data SDK that is installed on your website

    2. If no, and consent has been granted, Treasure Data SDK creates a first party, server-side cookie for the user

  2. Treasure Data records users' consent response. In your configuration of the Treasure Data SDK, you specify where the user consent is stored. By storing the consent on the user's browser, the user is not asked for tracking permission each time they access your website and the consent record persists as specified in the cookie document on your website.

  3. The user grants permission to track. A Treasure Data API on your webpage requests a unique ID from Treasure Data.

  4. Treasure Data sends a unique ID back to your webpage. Server-side cookies can be set to persist for up to two years.

  5. The td_ssc_id for the user is stored in the cookie document on your website and, if configured in the Treasure Data SDK, tracking of activities performed by the user is recorded in your CDP account.

You complete the following sections to enable server-side tracking of first party cookies:


Prerequisites

Set up of this feature requires that you know how to configure in HTML and Javascript. Additionally, you need to have:

  • Basic knowledge of Treasure Data

  • Basic knowledge of Treasure Data JavaScript SDK

  • A subdomain (DNS) under your primary website


Treasure Data recommends that you implement any new features or functionality at your site using the Treasure Data JavaScript SDK version 3 Beta. It manages cookies differently. Be aware when referring to most of these articles that you need to define the suggested event collectors and Treasure Data JavaScript SDK version 3 calls in your solutions.

For example, change //cdn.treasuredata.com/sdk/2.5/td.min.js to //cdn.treasuredata.com/sdk/3.0.0-beta/td.min.js.

Setting Up the NS Record in Your DNS

The Treasure Data server-side tracking requires that the server create first party cookies under a subdomain of the primary website. You must add an NS record in your subdomain that points to the Treasure Data server-side cookie service. The NS record points the name of the subdomain to Treasure Data name servers.

For example:

primary website: www.example.com

subdomain: ssc.example.com

ssc.example.com.
NS
ns-###.awsdns-##.com. 
ns-####.awsdns-##.co.uk. 
ns-###.awsdns-##.net. 
ns-###.awsdns-##.org. 

Generally, follow the procedures for your website configuration to add an NS record. Your Treasure Data Customer Success Representative provides the details on the Treasure Data server records that you are to use. You might specify more than one record for redundancy and speed up the DNS lookup (you can pick the name server that’s physically closest to the browser).

Configuring the JS SDK to Collect and Store First Party Cookies

As the website server developer, you install TD JS SDK and configure function calls to fetch a Treasure Data-generated ID for each user who visits your website.  The function calls are basically API requests to Treasure Data's server-side cookie. The ID that server-side cookie returns to your website is saved on the end-user's browser. 

Parameters and functions include:

  • sscDomain: String | (String) => String | null. Top-level domain of your website.

  • sscServer: String | null. The subdomain you create on your website to connect to Treasure Data.

  • useServerSideCookie: Boolean

  • setSignedMode() function

  • trackPageview() function

  • set() function

Treasure Data Javascript SDK Overview and Installation

You can view a TD JS SDK overview and installation walkthrough. Also, review the video Implementation for GDPR for a description of the TD JS SDK function that helps you to comply with privacy regulations and requirements.

For more information on installing TD JS SDK see Getting Started with Website Tracking. As part of the instructions, Enable Tracking Events by Individual, is key to enabling tracking of first-party cookies.

Embed the JS Code to Call the Server Side Cookie

The JS code for the server that will contain the cookie sets a cookie on the given subdomain as a parameter. The unique id for each end user visitor persists for 2 years unless the user clears their cookies.

When users revisit the site later, they are recognized as the same user.

Ensure your Treasure Data account is set up to import data from your webpage.

The following code example illustrates the parameters and functions that you configure on your website:

<html>
	<script type="text/javascript">  
!function(t,e){if(void 0===e[t]){e[t]=function(){e[t].clients.push(this),this._init=[Array.prototype.slice.call(arguments)]},e[t].clients=[];for(var r=function(t){return function(){return this["_"+t]=this["_"+t]||[],this["_"+t].push(Array.prototype.slice.call(arguments)),this}},s=["addRecord","blockEvents","fetchServerCookie","fetchGlobalID","fetchUserSegments","resetUUID","ready","setSignedMode","setAnonymousMode","set","trackEvent","trackPageview","trackClicks","unblockEvents"],n=0;n<s.length;n++){var c=s[n];e[t].prototype[c]=r(c)}var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=("https:"===document.location.protocol?"https:":"http:")+"//cdn.treasuredata.com/sdk/2.5/td.min.js";var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)}}("Treasure",this);  
</script>
</head>
<body>
  <script type="text/javascript">
  var td = new Treasure({
    database:'YOUR_DATABASE',
    writeKey: 'YOUR_API_KEY',
    host: 'in.treasuredata.com',
    startInSignedMode: true,
    sscDomain: 'YOUR_SSC_DOMAIN', // ex) example.com
    sscServer: 'YOUR_SSC_SERVER', // ex) ssc.example.com
    useServerSideCookie: true
  });
  
  td.set('$global', 'td_global_id', 'td_global_id');
  td.fetchServerCookie(successCallback, errorCallback);
  
  function fireEvents () {
    td.trackPageview('YOUR_TABLE');
  }
  
  function successCallback (result) {
    // result === Server Side Cookie
    td.set('$global', { td_ssc_id: result });
    fireEvents();
  }
  
  function errorCallback () {
    // Track events, even if the server-side cookie does not work
    fireEvents();
  }
  </script>
</body>
</html>

Modify Your Existing JS SDK to Establish a Connection

Update the existing JS SDK coding on your website, adding the required parameters and functions, as shown in the preceding section.

Then, in Treasure Data, ensure that the database table that receives the first-party cookie data includes a column for the td_ssc_id. The column is required when events are being recorded into an existing table:


Specifying the Consent Record Location

Typically, consent is stored in the browser as a client-side cookie, for example, in document.cookie. Treasure Data provides a new location option for consent. The location is in the user's local storage.

In the JS SDK specify storeConsentByLocalStorage: true.

When end-user accepts consent, the consent is saved in the end user's local storage.


  • No labels