Salesforce B2C Commerce 24.7 > B2C Commerce API > B2C Commerce Script > dw.system
dw.system
Class Session
Object
dw.system.Session
Represents a session in B2C Commerce. The session has some well-defined attributes like the current authenticated customer or the click stream, but also supports storing custom values in the session. The Digital session handling works in the following way:
  • A session is created in Digital on the first user click. This is guaranteed even if B2C Commerce caches the HTML pages. It is not guaranteed when the pages are cached by a CDN.
  • A session is identified with a unique ID, called the session ID.
  • When a session is created, the application server calls the pipeline OnSession-Start. It can be used to pre-initialize the session, before the actual request hits the server.
  • Digital uses session stickiness and always routes requests within a single session to the same application server.
  • Session data is also stored in a persistent location.
  • In case of a fail-over situation, requests are re-routed to another application server, which then loads the session data from the persistent storage.
  • There are two session timeouts. A soft timeout occurs 30 minutes after the last request has been made. The soft timeout logs out and clears all privacy data, but it is still possible to use the session ID to reopen the session. A hard timeout renders a session ID invalid after six hours, even if the session is still in use. The hard timeout prevents a session from being reopened. For example, if the session ID is pasted into a URL after the hard timeout, the session doesn't reopen.
Certain rules apply for what and how much data can be stored in a session:
  • All primitive types (boolean, number, string, Number, String, Boolean, Date) are supported.
  • All B2C Commerce value types (Money, Quantity, Decimal, Calendar) are supported.
  • Strings are limited to 2000 characters.
  • No other types can be stored in a session. In particular, persistent objects, collections, and scripted objects cannot be stored in a session. B2C Commerce will report unsupported values with a deprecation message in the log files. An unsupported value will be stored in the session, but the results are undefined. Since version compatibility mode 19.10 unsupported types will no longer be accepted, and an exception will be thrown.
  • There is a 10 KB size limit for the overall serialized session.
Properties
clickStream  :  ClickStream  (Read Only)
The current click stream if this is an HTTP session, null otherwise.
currency  :  Currency
Get the currency associated with the current session. The session currency is established at session construction time and is typically equal to the site default currency. In the case of a multi-currency site, the session currency may be different than the site default currency.
custom  :  CustomAttributes  (Read Only)
The session's custom attributes. The attributes are stored for the lifetime of the session and are not cleared when the customer logs out.
customer  :  Customer  (Read Only)
The customer associated with this storefront session. The method always returns null if called for a non-storefront session (e.g., within a job or within Business Manager). For a storefront session, the method always returns a customer. The returned customer may be anonymous if the customer could not be identified via the customer cookie.
customerAuthenticated  :  boolean  (Read Only)
Identifies whether the customer associated with this session is authenticated. This call is equivalent to customer.isAuthenticated().
customerExternallyAuthenticated  :  boolean  (Read Only)
Identifies whether the customer associated with this session is externally authenticated.
forms  :  Forms  (Read Only)
The forms object that provides access to all current forms of a customer in the session.
lastReceivedSourceCodeInfo  :  SourceCodeInfo  (Read Only)
Returns information on the last source code handled by the session. This may or may not be the session's active source code, e.g., the last received source code was inactive and therefore was not set as the session's active source code.
privacy  :  CustomAttributes  (Read Only)
The session's custom privacy attributes. The attributes are stored for the lifetime of the session and are automatically cleared when the customer logs out.
sessionID  :  String  (Read Only)
The unique session id. This can safely be used as an identifier against external systems.
sourceCodeInfo  :  SourceCodeInfo  (Read Only)
Returns information on the session's active source-code.
trackingAllowed  :  boolean
Returns whether the tracking allowed flag is set in the session. The value for newly created sessions defaults to the Site Preference "TrackingAllowed" unless a cookie named "dw_dnt" is found in which case the cookie value takes precedence.
userAuthenticated  :  boolean  (Read Only)
Identifies whether the agent user associated with this session is authenticated.
userName  :  String  (Read Only)
The current agent user name associated with this session.

Note: this class allows access to sensitive security-related data. Pay special attention to PCI DSS v3 requirements 2, 4, and 12.

Constructor Summary
This class does not have a constructor, so you cannot create it directly.
Method Summary
generateGuestSessionSignature() : String
Generates a new guest session signature.
getClickStream() : ClickStream
Returns the current click stream if this is an HTTP session, null otherwise.
getCurrency() : Currency
Get the currency associated with the current session.
getCustom() : CustomAttributes
Returns the session's custom attributes.
getCustomer() : Customer
Returns the customer associated with this storefront session.
getForms() : Forms
Returns the forms object that provides access to all current forms of a customer in the session.
getLastReceivedSourceCodeInfo() : SourceCodeInfo
Returns information on the last source code handled by the session.
getPrivacy() : CustomAttributes
Returns the session's custom privacy attributes.
getSessionID() : String
Returns the unique session id.
getSourceCodeInfo() : SourceCodeInfo
Returns information on the session's active source-code.
getUserName() : String
Returns the current agent user name associated with this session.
isCustomerAuthenticated() : boolean
Identifies whether the customer associated with this session is authenticated.
isCustomerExternallyAuthenticated() : boolean
Identifies whether the customer associated with this session is externally authenticated.
isTrackingAllowed() : boolean
Returns whether the tracking allowed flag is set in the session.
isUserAuthenticated() : boolean
Identifies whether the agent user associated with this session is authenticated.
setCurrency(newCurrency : Currency) : void
Sets the session currency.
setSourceCode(sourceCode : String) : Status
Applies the specified source code to the current session and basket.
setTrackingAllowed(trackingAllowed : boolean) : void
Sets the tracking allowed flag for the session.
Methods inherited from class Object
assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values
Method Detail
generateGuestSessionSignature
generateGuestSessionSignature() : String
Generates a new guest session signature.

This is intended for guest authentication with the Shopper Login and API Access Service (SLAS).

Returns:
A new signed session token.
getClickStream
getClickStream() : ClickStream
Returns the current click stream if this is an HTTP session, null otherwise.
Returns:
the current click stream if this is an HTTP session, null otherwise.
getCurrency
getCurrency() : Currency
Get the currency associated with the current session. The session currency is established at session construction time and is typically equal to the site default currency. In the case of a multi-currency site, the session currency may be different than the site default currency.
Returns:
the currency associated with this storefront session, never null.
getCustom
getCustom() : CustomAttributes
Returns the session's custom attributes. The attributes are stored for the lifetime of the session and are not cleared when the customer logs out.
Returns:
the session's custom attributes.
getCustomer
getCustomer() : Customer
Returns the customer associated with this storefront session. The method always returns null if called for a non-storefront session (e.g., within a job or within Business Manager). For a storefront session, the method always returns a customer. The returned customer may be anonymous if the customer could not be identified via the customer cookie.
Returns:
the customer associated with this storefront session.
getForms
getForms() : Forms
Returns the forms object that provides access to all current forms of a customer in the session.
Returns:
the forms.
getLastReceivedSourceCodeInfo
getLastReceivedSourceCodeInfo() : SourceCodeInfo
Returns information on the last source code handled by the session. This may or may not be the session's active source code, e.g., the last received source code was inactive and therefore was not set as the session's active source code.
Returns:
source code information for the last received source code.
getPrivacy
getPrivacy() : CustomAttributes
Returns the session's custom privacy attributes. The attributes are stored for the lifetime of the session and are automatically cleared when the customer logs out.
Returns:
the session's custom privacy attributes.
getSessionID
getSessionID() : String
Returns the unique session id. This can safely be used as an identifier against external systems.
Returns:
the unique identifier for the session.
getSourceCodeInfo
getSourceCodeInfo() : SourceCodeInfo
Returns information on the session's active source-code.
Returns:
the session's source-code information.
getUserName
getUserName() : String
Returns the current agent user name associated with this session.

Note: this class allows access to sensitive security-related data. Pay special attention to PCI DSS v3 requirements 2, 4, and 12.

Returns:
the current agent user name associated with this session.
isCustomerAuthenticated
isCustomerAuthenticated() : boolean
Identifies whether the customer associated with this session is authenticated. This call is equivalent to customer.isAuthenticated().
Returns:
true if the customer is authenticated, false otherwise.
isCustomerExternallyAuthenticated
isCustomerExternallyAuthenticated() : boolean
Identifies whether the customer associated with this session is externally authenticated.
Returns:
true if the customer is authenticated, false otherwise.
isTrackingAllowed
isTrackingAllowed() : boolean
Returns whether the tracking allowed flag is set in the session. The value for newly created sessions defaults to the Site Preference "TrackingAllowed" unless a cookie named "dw_dnt" is found in which case the cookie value takes precedence.
Returns:
true if the tracking allowed flag is set in the session, false otherwise.
isUserAuthenticated
isUserAuthenticated() : boolean
Identifies whether the agent user associated with this session is authenticated.
Returns:
true if the agent user is authenticated, false otherwise.
setCurrency
setCurrency(newCurrency : Currency) : void
Sets the session currency.
Parameters:
newCurrency - the new currency to use. Must not be null. Method will throw an exception if a currency not allowed by the current site is passed.
setSourceCode
setSourceCode(sourceCode : String) : Status
Applies the specified source code to the current session and basket. This API processes the source code exactly as if it were supplied on the URL query string, with the additional benefit of returning error information. If no input parameter is passed, then the active source code in the session and basket is removed. If a basket exists, and the modification fails, then the session is not written to either. This method may open and commit a transaction, if none is currently active.
Parameters:
sourceCode - the source code to set as active in the session and basket. If a null parameter is passed, then the active source code in the session is removed.
Returns:
an OK status if the source code was applied, otherwise an ERROR status. In the latter case, the possible error codes are: CODE_INVALID and CODE_INACTIVE. See documentation for SourceCodeStatusCodes for further descriptions.
setTrackingAllowed
setTrackingAllowed(trackingAllowed : boolean) : void
Sets the tracking allowed flag for the session. If tracking is not allowed, multiple services depending on tracking will be restricted or disabled: Predictive Intelligence recommendations, Active Data, Analytics of the customer behavior in the storefront. Additionally, collected clicks in the session click stream will be cleared. Setting this property to either value also results in setting a session-scoped cookie named "dw_dnt" (1=DoNotTrack; 0=Track)
Parameters:
trackingAllowed - true if tracking is allowed, false otherwise.

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.