Client state management
The Edge Network itself is stateless (it does not maintain its own session). However, there are certain use-cases which require client-side state persistency, such as:
- Consistent device identification (see visitor identification)
- Collect and enforce user consent
- Keeping personalization session ID
The Edge Network uses a state management protocol, delegating the storage aspect to its client/SDK, and includes state entries in its responses. For browsers, the entries are stored as cookies.
The client responsibility is to store and include them in all subsequent requests. The client must also take care of proper expiration for entries, as instructed by the gateway. When the entries were stored as cookies, the browser does all this work automatically.
Although the state entries always have a plain String
value (visible to the caller/SDK), you should not consume or tamper with the values in any way. The value structure/format or even the name itself might change at any point, which could lead to unexpected behavior for clients that use the state internally. The state is intended to always be consumed by the gateway itself or other edge services.
Persisting client state as metadata
The state returned by the Edge Network in the response body is a Handle
object with the type state:store
.
{
"requestId":"421036b3-a7ff-480b-a9ab-30adba6eb4f0",
"handle":[
{
"payload":[
{
"key":"kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_consent_check",
"value":"1",
"maxAge":7200,
"attrs":{
"SameSite":"None"
}
},
{
"key":"kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_identity",
"value":"CiY1NDc1ODIxNzIzODk5MDY5MzQzMTIzNjQ1NTczNzExNjE4OTA1MFINCLGOvszNLhABGAEgBKABsY6-zM0uqAGHz-z2y82cul3wAbGOvszNLg==",
"maxAge":34128000,
"attrs":{
"SameSite":"None"
}
},
{
"key":"kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_consent",
"value":"general=in",
"maxAge":15552000,
"attrs":{
"SameSite":"None"
}
}
],
"type":"state:store"
}
]
}
key
value
maxAge
attrs
Map<String, String>
SameSite
attribute is set to None
.To support multi-tagging (i.e. multiple SDK instances in the same property, which potentially reference different organizations), all state entries are automatically prefixed with kndctr_
and the URL-safe organization ID.
When the client SDK receives a state:store
handle in the response, it must do the following:
- Store entries client-side, respecting the expiration time supplied by the gateway.
- Load them from the client store and include all un-expired entries in the subsequent requests.
Here’s an example of a request which passes in the client-side stored state:
{
"meta":{
"state":{
"entries":[
{
"key":"kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_consent_check",
"value":"1"
},
{
"key":"kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_personalization_sessionId",
"value":"0a88f43e-044b-41a6-a4f3-6c2848bbc672"
}
]
}
}
}
Persisting client state in browser cookies
When working with browser clients, the Edge Network can automatically persist the entries as browser cookies. This allows transparent state storage support, since browsers respect the state management protocol by default.
Almost all entries are materialized as first party cookies when enabled and supported (see the note below), but the gateway could also store some third party cookies when the third party adobedc.demdex.net
domain is used.
Since entries are always bound to a specific scope (device/application) by their definition, only the subset that is compatible with the current request context will be written by the Edge Network. Unwritten entries are
returned within a state:store
handle.
As a general rule, application scoped entries are always written as first party cookies, while device scoped entries are written as third-party cookies. The decision is completely transparent to the caller, the gateway decides which entries can be written, depending on the call context.
The caller must explicitly enable support for storing client state as cookies, via the meta.state.cookiesEnabled
flag:
{
"meta":{
"state":{
"cookiesEnabled":true,
"domain":"foo.com"
}
}
}
cookiesEnabled
false
.domain
cookiesEnabled: true
. The top-level domain on which the cookies should be written. The Edge Network will use this value to decide if state can be persisted as cookies.Even if cookies support is enabled via the cookiesEnabled
flag, the Adobe Experience Platform Edge Network will only write the state entries if the request top-level domain matches the domain
specified by the caller. When there’s a mismatch, entries are returned in a state:store
handle.
The first-party cookies cannot be written (even if support is enabled) in the following cases:
- The request is coming on the third-party
adobedc.demdex.net
domain. - The request is coming on a first-party
CNAME
domain, different from the one specified by the caller inmeta.state.domain
.
Cookie security
All cookies have the Secure flag enabled whenever possible.
All secure cookies have the SameSite attribute set to None
, meaning that cookies are sent in all contexts, both 1st party and cross-origin.
- For the first-party cookies (
kndcrt_*
), theSecure
flag is only set when the request context is secure (HTTPS) and when referrer (Referer HTTP Header) is also HTTPS. If the referrer is not secure (HTTP), theSecure
flag is omitted to permit the Web SDK to read them. A secure cookie cannot be read from an unsecure context. - For the third-party cookie (demdex), the
Secure
flag is always set, since all requests are HTTPS, so the request context is secure, and this cookie is never read from JavaScript.
The Secure
flag is not present in the metadata representation of cookies. Only the SameSite
attribute is included. In this case, it is the client’s responsibility to correctly set the Secure
flag whenever the SameSite
attribute is present. Cookies with SameSite=None
must also specify the Secure
attribute, since they require a secure context (HTTPS).