# ISML iscookie Element
## Overview
The `<iscookie>` element sets a cookie in the browser, allowing you to store user-related information on the shopper's system. Cookies enable persistent storage of preferences, session data, and user identifiers that the browser returns with subsequent requests to the same domain.
**Security Note:** Cookie handling includes automatic `SameSite` attribute management based on security settings and the `Secure` flag.
## Syntax
```isml
<iscookie
name = cookie_name // required
value = cookie_value // required
comment = cookie_use // optional
domain = domain_name // optional
path = pathname // optional
maxAge = cookie_lifetime // optional
version = cookie_spec // optional
secure = "on" | "off" // optional
/>
```
## Required Attributes
### name
**Type:** String or Expression
**Required:** Yes
Specifies the name for the cookie. This is the identifier used to retrieve the cookie value in subsequent requests.
**Restrictions:** Names starting with `$` are **not allowed**.
**Examples:**
```isml
<!-- String literal -->
<iscookie name="UserID" value="${customer.ID}"/>
<!-- Expression -->
<iscookie name="${pdict.cookieName}" value="${pdict.cookieValue}"/>
<!-- Invalid: starts with $ -->
<iscookie name="$sessionID" value="123"/> <!-- NOT ALLOWED -->
```
### value
**Type:** String or Expression
**Required:** Yes
Specifies the value stored by the cookie. This can be any string data such as a user ID, preference setting, or session identifier.
**Examples:**
```isml
<!-- Customer UUID -->
<iscookie name="UserID" value="${pdict.buyer.UUID}"/>
<!-- Preference value -->
<iscookie name="preferredStore" value="${customer.profile.custom.storeLocation}"/>
<!-- String literal -->
<iscookie name="consent" value="accepted"/>
<!-- Expression -->
<iscookie name="sessionData" value="${JSON.stringify(pdict.sessionInfo)}"/>
```
## Optional Attributes
### comment
**Type:** String or Expression
**Optional:** Yes
Documents the intended use of the cookie. This information can help users decide whether to accept or reject the cookie, especially when cookies contain private information.
**Privacy Best Practice:** Always provide meaningful comments for cookies that store personal or sensitive data to support transparency and user consent.
```isml
<iscookie
name="UserID"
value="${customer.UUID}"
comment="Your international customer ID for personalized shopping experience"/>
<iscookie
name="preferences"
value="${prefs}"
comment="Stores your site preferences like language and currency"/>
```
### domain
**Type:** String or Expression
**Optional:** Yes
Specifies the domain for which the cookie is valid. Controls which domains can access the cookie.
**Important Rules:**
- An explicitly specified domain **must always start with a dot** (`.`)
- If not specified, the browser sets the domain to the domain that issued the cookie
- Cookies are sent to the specified domain and all its subdomains
**Examples:**
```isml
<!-- Valid for foo.com and all subdomains (www.foo.com, shop.foo.com) -->
<iscookie name="UserID" value="${customer.ID}" domain=".foo.com"/>
<!-- Valid for example.com and all subdomains -->
<iscookie name="sessionID" value="${session.ID}" domain=".example.com"/>
<!-- Browser sets domain automatically (recommended for most cases) -->
<iscookie name="UserID" value="${customer.ID}"/>
```
### path
**Type:** String or Expression
**Optional:** Yes
Specifies the URL path subset to which this cookie applies. Pages outside of that path cannot access the cookie.
**Path Matching:**
- Cookie is sent to the specified path and all sub-paths
- More specific paths provide better security and control
- Default is typically `/` (root path)
**Examples:**
```isml
<!-- Cookie available to /checkout and all sub-paths -->
<iscookie name="checkoutData" value="${data}" path="/checkout"/>
<!-- Cookie available site-wide -->
<iscookie name="UserID" value="${customer.ID}" path="/"/>
<!-- Cookie only for specific section -->
<iscookie name="adminSession" value="${sessionID}" path="/admin"/>
<!-- Dynamic path -->
<iscookie name="categoryPref" value="${pref}" path="${'/category/' + categoryID}"/>
```
### maxAge
**Type:** Integer or Expression
**Optional:** Yes
**Unit:** Seconds
Defines the lifetime of the cookie in seconds. Controls how long the browser should retain the cookie.
**Value Meanings:**
- **Positive integer:** Cookie persists for the specified number of seconds
- **`0`:** Cookie is deleted immediately
- **Negative integer:** Cookie is not persistent and is deleted when the browser closes (session cookie)
**B2C Commerce Regulations:**
- Maximum cookie lifetime is **6 months** for compliance with international data storage regulations
- Anonymous customer cookies adhere to 6-month maximum
- All B2C Commerce cookies have a lifetime of 6 months or less
**Examples:**
```isml
<!-- Session cookie (deleted when browser closes) -->
<iscookie name="tempData" value="${data}" maxAge="-1"/>
<!-- 1 hour (3600 seconds) -->
<iscookie name="sessionID" value="${session.ID}" maxAge="3600"/>
<!-- 1 day (86400 seconds) -->
<iscookie name="dailyPref" value="${pref}" maxAge="86400"/>
<!-- 30 days (2592000 seconds) -->
<iscookie name="preferences" value="${prefs}" maxAge="2592000"/>
<!-- 6 months maximum (15552000 seconds = 180 days) -->
<iscookie name="UserID" value="${customer.UUID}" maxAge="15552000"/>
<!-- Delete cookie immediately -->
<iscookie name="oldCookie" value="" maxAge="0"/>
<!-- Dynamic lifetime -->
<iscookie name="tempToken" value="${token}" maxAge="${pdict.tokenLifetime}"/>
```
**Lifetime Calculations:**
```isml
<isscript>
var ONE_HOUR = 60 * 60; // 3600
var ONE_DAY = 24 * 60 * 60; // 86400
var ONE_WEEK = 7 * 24 * 60 * 60; // 604800
var ONE_MONTH = 30 * 24 * 60 * 60; // 2592000
var SIX_MONTHS = 180 * 24 * 60 * 60; // 15552000 (B2C Commerce max)
</isscript>
<iscookie name="sessionToken" value="${token}" maxAge="${ONE_HOUR}"/>
<iscookie name="userPrefs" value="${prefs}" maxAge="${ONE_MONTH}"/>
```
### version
**Type:** Decimal Integer or Expression
**Optional:** Yes
Identifies the version of the cookie specification to which the cookie conforms.
**Valid Values:** Any decimal integer (digits 0-9)
**Common Versions:**
- `0` - Original Netscape cookie specification (most common)
- `1` - RFC 2109 cookie specification
```isml
<!-- Version 0 (Netscape specification) -->
<iscookie name="UserID" value="${customer.ID}" version="0"/>
<!-- Version 1 (RFC 2109) -->
<iscookie name="sessionData" value="${data}" version="1"/>
<!-- Dynamic version -->
<iscookie name="data" value="${value}" version="${pdict.cookieVersion}"/>
```
### secure
**Type:** String
**Allowed Values:** `"on"`, `"off"`
**Optional:** Yes
**Default:** `"off"`
**Expressions:** Not allowed
Indicates whether the cookie must only be transmitted over secure connections (HTTPS/SSL).
**Security Behavior:**
- `"on"` - Cookie only sent over HTTPS connections
- `"off"` - Cookie sent over both HTTP and HTTPS
**Important:** Setting `secure="on"` affects the automatic `SameSite` attribute (see SameSite Attribute section).
```isml
<!-- Secure cookie (HTTPS only) -->
<iscookie name="UserID" value="${customer.UUID}" secure="on"/>
<!-- Non-secure cookie (HTTP and HTTPS) -->
<iscookie name="preferences" value="${prefs}" secure="off"/>
<!-- Best practice: Always use secure for sensitive data -->
<iscookie
name="sessionToken"
value="${token}"
secure="on"
maxAge="3600"/>
```
## SameSite Attribute Management
The `SameSite` attribute controls whether cookies are sent with cross-site requests, providing CSRF protection.
**Automatic Behavior:** You **cannot** manually set the `SameSite` attribute using the `<iscookie>` tag. The server automatically manages it based on the following rules:
### SameSite=None
The server sets `SameSite=None` when **either** condition is true:
1. Developer sets `secure="on"` on the cookie
2. Global security preference **"Enforce HTTPS"** is enabled
**Note:** When `SameSite=None` is set, the `Secure` flag is also automatically set.
```isml
<!-- Results in SameSite=None; Secure -->
<iscookie name="crossSiteID" value="${id}" secure="on"/>
```
### No SameSite Attribute
If neither condition above is met, the server **doesn't set** the `SameSite` attribute, and the browser uses its own default setting (typically `SameSite=Lax`).
```isml
<!-- Browser uses its default SameSite setting -->
<iscookie name="localPref" value="${pref}" secure="off"/>
```
### Client Compatibility
The `SameSite` attribute is **not sent** with a cookie if the server detects that the client doesn't correctly interpret the attribute (older browsers).
## Purpose
Cookies serve multiple purposes in B2C Commerce storefronts:
1. **User Identification:** Store unique user IDs to identify returning customers
2. **Session Management:** Maintain session state across requests
3. **Personalization:** Store user preferences (language, currency, store location)
4. **Simplified Login:** Enable "Remember Me" functionality without storing passwords
5. **Shopping Cart Persistence:** Maintain cart state for anonymous users
6. **Analytics Tracking:** Track user behavior and shopping patterns
7. **Consent Management:** Store cookie consent preferences
**How Cookies Work:**
1. B2C Commerce sends cookie to browser via `<iscookie>` tag
2. Browser stores the cookie on the shopper's system
3. Browser returns the cookie with every subsequent request to the same domain
4. Server reads cookie value to identify user, preferences, or session
## Supporting Objects
For programmatic cookie operations in scripts, use these classes:
| Class | Purpose |
|-------|---------|
| **`dw.system.Request`** | Read cookies from incoming requests |
| **`dw.web.Cookies`** | Collection of cookies |
| **`dw.web.Cookie`** | Individual cookie object with properties and methods |
**See:** Scripting API documentation for detailed programmatic cookie manipulation.
## Common Use Cases
### Customer Identification Cookie
```isml
<iscookie
name="UserID"
value="${pdict.buyer.UUID}"
comment="Your international customer ID"
domain=".foo.com"
path="/acme"
maxAge="10000"
version="0"
secure="on"
/>
```
### Store Preferences
```isml
<isscript>
var preferences = {
language: request.locale,
currency: session.currency.currencyCode,
storeID: customer.profile.custom.preferredStore
};
</isscript>
<iscookie
name="storePreferences"
value="${JSON.stringify(preferences)}"
comment="Stores your language, currency, and preferred store location"
maxAge="${30 * 24 * 60 * 60}"
secure="on"
/>
```
### Session Cookie
```isml
<!-- Deleted when browser closes (maxAge = -1) -->
<iscookie
name="tempSessionData"
value="${session.custom.temporaryData}"
comment="Temporary session information"
maxAge="-1"
path="/"
secure="on"
/>
```
### Remember Me Functionality
```isml
<isif condition="${pdict.rememberMe}">
<iscookie
name="rememberToken"
value="${customer.profile.custom.rememberMeToken}"
comment="Remember me authentication token"
maxAge="${30 * 24 * 60 * 60}"
path="/"
secure="on"
/>
</isif>
```
### Cookie Consent Tracking
```isml
<iscookie
name="cookieConsent"
value="${pdict.consentLevel}"
comment="Stores your cookie preferences and consent"
maxAge="${365 * 24 * 60 * 60}"
path="/"
secure="on"
/>
```
### Delete a Cookie
```isml
<!-- Set maxAge to 0 to delete the cookie -->
<iscookie
name="oldCookie"
value=""
maxAge="0"
/>
```
### Shopping Cart Cookie for Anonymous Users
```isml
<iscookie
name="anonymousBasket"
value="${session.custom.basketID}"
comment="Stores your shopping cart for your next visit"
maxAge="${7 * 24 * 60 * 60}"
path="/"
secure="on"
/>
```
### Locale Preference
```isml
<iscookie
name="locale"
value="${request.locale}"
comment="Your preferred language and region settings"
maxAge="${90 * 24 * 60 * 60}"
path="/"
secure="on"
/>
```
## Reading Cookies
### In ISML Templates
Access cookies from the current request using the `request.httpCookies` object:
```isml
<!-- Check if cookie exists -->
<isif condition="${request.httpCookies['UserID'] != null}">
<isredirect location="${URLUtils.url('LoginPanel')}"/>
</isif>
<!-- Read cookie value -->
<isset name="userID" value="${request.httpCookies['UserID'].value}" scope="page"/>
<div>Welcome back, User ${userID}</div>
<!-- Conditional logic based on cookie -->
<isif condition="${request.httpCookies['cookieConsent'] != null}">
<!-- Show analytics scripts -->
<isinclude template="analytics/tracking"/>
</isif>
```
### In Scripts
```javascript
// Check if cookie exists
if (request.httpCookies.UserID != null) {
var userID = request.httpCookies.UserID.value;
// Use userID...
}
// Iterate over all cookies
var cookies = request.httpCookies;
for (var cookieName in cookies) {
var cookie = cookies[cookieName];
Logger.debug('Cookie: {0} = {1}', cookieName, cookie.value);
}
// Get specific cookie
var Cookie = require('dw/web/Cookie');
var userCookie = request.httpCookies['UserID'];
if (userCookie) {
var value = userCookie.value;
var domain = userCookie.domain;
var path = userCookie.path;
var maxAge = userCookie.maxAge;
}
```
## Security Best Practices
### Always Use Secure Flag for Sensitive Data
```isml
<!-- Good: Secure flag for authentication tokens -->
<iscookie
name="authToken"
value="${token}"
secure="on"
maxAge="3600"
/>
<!-- Bad: Sensitive data without secure flag -->
<iscookie
name="authToken"
value="${token}"
secure="off" <!-- INSECURE -->
/>
```
### Use HTTPS in Production
**Critical:** Always enable **"Enforce HTTPS"** in production environments to ensure:
- `SameSite=None` is set automatically
- `Secure` flag is set automatically
- Protection against man-in-the-middle attacks
### Limit Cookie Lifetime
```isml
<!-- Good: Short lifetime for sensitive data -->
<iscookie
name="sessionToken"
value="${token}"
maxAge="3600"
secure="on"
/>
<!-- Avoid: Overly long lifetime for sensitive data -->
<iscookie
name="sessionToken"
value="${token}"
maxAge="${365 * 24 * 60 * 60}" <!-- Too long for session data -->
secure="on"
/>
```
### Provide Meaningful Comments
```isml
<!-- Good: Clear privacy documentation -->
<iscookie
name="UserID"
value="${customer.UUID}"
comment="Stores your unique customer identifier to personalize your shopping experience and remember your preferences"
secure="on"
/>
<!-- Less helpful: Vague comment -->
<iscookie
name="UserID"
value="${customer.UUID}"
comment="User data"
/>
```
### Use Specific Paths When Possible
```isml
<!-- Good: Restrict cookie to specific path -->
<iscookie
name="checkoutToken"
value="${token}"
path="/checkout"
maxAge="1800"
secure="on"
/>
<!-- Less secure: Site-wide access when not needed -->
<iscookie
name="checkoutToken"
value="${token}"
path="/"
maxAge="1800"
secure="on"
/>
```
### Never Store Passwords
```isml
<!-- NEVER DO THIS -->
<iscookie
name="password"
value="${customer.password}" <!-- NEVER STORE PASSWORDS -->
secure="on"
/>
<!-- Instead: Use tokens -->
<iscookie
name="authToken"
value="${generateSecureToken(customer)}"
secure="on"
maxAge="3600"
/>
```
## Privacy and Compliance
### GDPR and Cookie Consent
For GDPR compliance, implement cookie consent management:
```isml
<!-- Only set non-essential cookies after consent -->
<isif condition="${pdict.hasAnalyticsConsent}">
<iscookie
name="analyticsID"
value="${pdict.analyticsIdentifier}"
comment="Used to analyze site usage and improve your shopping experience"
maxAge="${90 * 24 * 60 * 60}"
secure="on"
/>
</isif>
<!-- Essential cookies can be set without consent -->
<iscookie
name="sessionID"
value="${session.sessionID}"
comment="Essential for site functionality and security"
maxAge="-1"
secure="on"
/>
```
### Cookie Categories
Implement different cookie types with appropriate consent:
```isml
<!-- Essential Cookies (no consent required) -->
<iscookie name="sessionID" value="${session.ID}" maxAge="-1" secure="on"/>
<!-- Functional Cookies (consent recommended) -->
<isif condition="${pdict.functionalConsent}">
<iscookie name="preferences" value="${prefs}" maxAge="${90 * 24 * 60 * 60}" secure="on"/>
</isif>
<!-- Analytics Cookies (consent required) -->
<isif condition="${pdict.analyticsConsent}">
<iscookie name="analytics" value="${id}" maxAge="${90 * 24 * 60 * 60}" secure="on"/>
</isif>
<!-- Marketing Cookies (consent required) -->
<isif condition="${pdict.marketingConsent}">
<iscookie name="marketing" value="${id}" maxAge="${90 * 24 * 60 * 60}" secure="on"/>
</isif>
```
### Transparency Requirements
```isml
<iscookie
name="UserTracking"
value="${trackingID}"
comment="This cookie tracks your browsing behavior to provide personalized product recommendations. You can opt out in your privacy settings."
maxAge="${30 * 24 * 60 * 60}"
secure="on"
/>
```
## Performance Considerations
### Cookie Size Limits
**Browser Limits:**
- Maximum cookie size: ~4KB per cookie
- Maximum cookies per domain: ~50-180 (varies by browser)
- Maximum total size: ~4KB * number of cookies
**Best Practices:**
- Keep cookie values small
- Don't store large objects in cookies
- Use server-side session storage for large data
```isml
<!-- Bad: Storing large data in cookie -->
<iscookie
name="cartData"
value="${JSON.stringify(basket)}" <!-- Could exceed 4KB -->
/>
<!-- Good: Store reference, keep data server-side -->
<iscookie
name="cartID"
value="${basket.UUID}" <!-- Small reference -->
secure="on"
/>
```
### Minimize Cookie Count
```isml
<!-- Less efficient: Multiple cookies -->
<iscookie name="language" value="${locale.language}"/>
<iscookie name="country" value="${locale.country}"/>
<iscookie name="currency" value="${currency}"/>
<!-- More efficient: Single cookie with JSON -->
<isscript>
var prefs = {
language: locale.language,
country: locale.country,
currency: currency
};
</isscript>
<iscookie name="preferences" value="${JSON.stringify(prefs)}"/>
```
## Troubleshooting
### Cookie Not Being Set
**Problem:** Cookie doesn't appear in browser.
**Solution:**
1. Check that both `name` and `value` are provided
2. Verify cookie name doesn't start with `$`
3. Ensure `<iscookie>` is executed (not inside false conditional)
4. Check browser cookie settings aren't blocking cookies
```isml
<!-- Verify execution -->
<iscomment>Cookie should be set here</iscomment>
<iscookie name="testCookie" value="testValue" maxAge="3600"/>
```
### Cookie Not Being Sent
**Problem:** Cookie exists but isn't sent with requests.
**Solution:**
1. Check `domain` attribute matches request domain
2. Verify `path` attribute includes request path
3. Ensure cookie hasn't expired (`maxAge`)
4. Check `secure` flag if using HTTP
```isml
<!-- Check domain matches -->
<iscookie
name="UserID"
value="${id}"
domain=".yoursite.com" <!-- Must match request domain -->
path="/" <!-- Must include request path -->
/>
```
### Secure Cookie on HTTP
**Problem:** Cookie with `secure="on"` not working on HTTP.
**Solution:** Secure cookies only work on HTTPS. Either:
- Use HTTPS
- Remove `secure="on"` for development (not recommended for production)
```isml
<!-- Development: conditional secure flag -->
<isscript>
var isProduction = System.getInstanceType() === System.PRODUCTION_SYSTEM;
</isscript>
<iscookie
name="devCookie"
value="${value}"
secure="${isProduction ? 'on' : 'off'}"
/>
```
### Cookie Deleted Unexpectedly
**Problem:** Cookie disappears before expected.
**Solution:**
1. Check `maxAge` value is correct (remember it's in seconds)
2. Verify another part of code isn't deleting it (`maxAge="0"`)
3. Check browser settings for cookie retention
```isml
<!-- Verify maxAge calculation -->
<isscript>
var thirtyDays = 30 * 24 * 60 * 60; // 2,592,000 seconds
</isscript>
<iscookie name="longLived" value="${value}" maxAge="${thirtyDays}"/>
```
## Related Elements and APIs
- **`request.httpCookies`**: Read cookies in ISML templates
- **`dw.web.Cookie`**: Programmatic cookie class
- **`dw.web.Cookies`**: Cookie collection class
- **`dw.system.Request`**: Request object with cookie access
## Summary
The `<iscookie>` element is essential for:
- ✅ Storing user preferences and personalization data
- ✅ Managing session state for anonymous users
- ✅ Enabling "Remember Me" functionality
- ✅ Tracking consent and privacy preferences
- ✅ Supporting shopping cart persistence
- ✅ Automatic `SameSite` attribute management
- ✅ Security with `Secure` flag for HTTPS-only transmission
- ✅ Compliance with 6-month maximum lifetime regulation
Always prioritize security, privacy, and transparency when implementing cookies in your B2C Commerce storefront.
