Version: Latest (3.0)1.1

Data Persistence in JavaScript SDK

The JavaScript SDK stores persistent user data in the cookies by default. If the cookies are not supported, the SDK uses local storage instead.

By default, the SDK stores all cookies in the top-level domain. It helps you to identify the users visiting websites hosted under a particular sub-domain. For example, if you include the JavaScript SDK in both admin.samplewebsite.com and app.samplewebsite.com, the SDK will store the cookie in samplewebsite.com. However, you can specify the cookie storage location by using the storage parameter in the load API options, as shown:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  storage: {
    cookie: {
      domain: "samplewebsite.com"
    }
  }
});

Replace the write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. and data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. in the snippet with their actual values.

Cookies

The cookie values are encrypted and their length is directly proportional to the values provided to the SDK. Also, all cookie names are prefixed with rl_ and the values are prefixed with RS_ENC_v3_. For example, rl_user_id —> RS_ENC_v3_U2FsdGVkX1+UKmiooYoGmKdNws7sgmWgGfHe.

The following table lists the cookies used by the JavaScript SDK to store persistent user data:

{
  email: “alex@example.com”,
  accountType: “pro”,
  country: “US”,
  someObj: {
    key1: val1,
    key2: val2,
  }
}

{
  location: “New Orleans”,
  nationality: “US”,
  someObj: {
    key1: val1,
    key2: val2,
  }
}

Local storage

RudderStack stores the local storage cookie names with rudder_<write-key>.<uuid>. prefix where uuid is in the standard UUID v4 format. For example:

rudder_28xsd8CjukXbMPt1ZaTzdedjXRE.2dc2aee6-2836-4273-be69-79c90c04ddec.reclaimEnd

The JavaScript SDK uses local storage to keep track of the events sent to the RudderStack backend, as listed in the below table:

{
  “d89d7fb5-945e-4378-bda5-492e4b596fb4”: {
   “item”: {
    “url”: “https://rudderstack-dataplane.rudderstack.com/v1/track",
    “headers”: {
     “Content-Type”: “application/json”,
      …
    },
    “message”: { 
     …
    }
    “attemptNumber”: 1,
    “time”: 1639734792773,
    “id”: “a4d89d7f-b594-4eb3-b8bd-a5492e4b596f”
   }
  }
}

[
  {
   “item”: {
    “url”: “https://rudderstack-dataplane.rudderstack.com/v1/track”,
    “headers”: {
     “Content-Type”: “application/json”,
      …
    },
    “message”: { 
     …
    }
    “attemptNumber”: 0,
    “time”: 1639734792773,
    “id”: “a4d89d7f-b594-4eb3-b8bd-a5492e4b596f”
   }
  }
]

Decryption APIs

Depending on your environment, use the below APIs to decrypt the RudderStack JavaScript cookie value encrypted using the storage load option.

Browser environments

The following decryption APIs are available for the frontend (browser) environments based on your use case:

Decrypt cookie value

You can use the getDecryptedValueBrowser API to decrypt the RudderStack cookie value that is encrypted with version set to v3.

import { getDecryptedValueBrowser } from '@rudderstack/analytics-js-cookies';

const encryptedCookieValue = 'RS_ENC_v3_InRlc3QtZGF0YSI=';
const decryptedCookieValue = getDecryptedValueBrowser(encryptedCookieValue);
console.log('Decrypted Cookie Value: ', decryptedCookieValue);
// Output:
// Decrypted Cookie Value: test-data

Note that the API returns null in the following cases:

• The provided input is not encrypted or properly encrypted.
• There are errors during decryption.

Decrypt cookie name

The getDecryptedCookieBrowser API takes the name of the JavaScript SDK cookie and returns the decrypted value. The return type is either a string or an object as some cookies like user ID, anonymous ID have string values while the user traits are objects.

You can use the following exported cookies with this API:

The following snippet highlights how to use the getDecryptedCookieBrowser API:

import {
  getDecryptedCookieBrowser,
  anonymousUserIdKey,
  userTraitsKey,
} from '@rudderstack/analytics-js-cookies';

const anonymousId = getDecryptedCookieBrowser(anonymousUserIdKey);
console.log('Anonymous User ID: ', anonymousId);
// Output:
// Anonymous User ID: 2c5b6d48-ea90-43a2-a2f6-457d27f90328

const userTraits = getDecryptedCookieBrowser(userTraitsKey);
console.log('User Traits: ', userTraits);
// Output:
// User Traits: {"email":"abc@xyz.com","name":"John Doe"}

const invalidCookie = getDecryptedCookieBrowser('invalid-cookie-name');
console.log('Invalid Cookie: ', invalidCookie);
// Output:
// Invalid Cookie: null

Note that the API returns null in the following cases:

• If the cookie is absent.
• If the cookie is not properly encrypted. It only decrypts the cookies that are encrypted with version set to v3.
• If the decrypted cookie value is not a valid JSON string.
• If the provided cookie name is not a valid RudderStack JavaScript SDK cookie.

Node.js environments

The following decryption API is available for the backend (Node.js) environments:

getDecryptedValue

You can use the getDecryptedValue API to decrypt the RudderStack cookie value that is encrypted with version set to v3.

import { getDecryptedValue } from '@rudderstack/analytics-js-cookies';

const encryptedCookieValue = 'RS_ENC_v3_InRlc3QtZGF0YSI=';
const decryptedCookieValue = getDecryptedValue(encryptedCookieValue);
console.log('Decrypted Cookie Value: ', decryptedCookieValue);

// Output:
// Decrypted Cookie Value: test-data

Note that the API returns null in the following cases:

• The provided input is not encrypted or properly encrypted.
• There are errors during decryption.

See this RudderStack blog for a detailed use case on leveraging the getDecryptedValue API to fetch the anonymousId from the request cookie and use it to implement a real-time personalization engine.

Debugging

All the above-mentioned APIs swallow any errors during the decryption process and return null. To log errors during the decryption process, you can set the debug parameter to true while using the APIs.

The following example highlights how to log errors using the getDecryptedValue API:

import { getDecryptedValue } from '@rudderstack/analytics-js-cookies';

const encryptedCookieValue = 'RS_ENC_v3_InRlc3QtZGF0YSI-some-random-data';

// Set the debug flag to true
const decryptedCookieValue = getDecryptedValue(encryptedCookieValue, true);
console.log('Decrypted Cookie Value: ', decryptedCookieValue);

// Output:
// Error occurred during decryption: Unexpected non-whitespace character after JSON at position 11
// Decrypted Cookie Value: null

Questions? Contact us by email or on Slack