sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/isml/iscookie.md

@@ -1,798 +0,0 @@
-# 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.