Skip to content

Personalization deep dive

Jump to bottom
jonsnyder edited this page Oct 19, 2023 · 3 revisions

Personalization within the Web SDK can be complicated at times. This deep dive tries to explain many of its parts.

Requesting personalization from Experience Edge

On the first sendEvent call on a page, the page-wide scope ("view") and the default surface (derived from the page url) are added automatically to the request. This signals experience edge to query its personalization providers for propositions. In addition to this triggering mechanism, you can also include explicit scopes or surfaces and trigger a request for propositions.

The request for personalization will include schemas that are supported by the Web SDK. Personalization providers should use the schema list to determine which kinds of propositions can be returned to the client.

Proposition structure

Propositions are the units of personalization returned from Experience edge. Propositions returned from the server have this basic structure:

{
  "id": "1234",
  "scope": "home",
  "scopeDetails": {...},
  "items": [
    {
      "schema": "https://ns.adobe.com/personalization/dom-action",
      "data": {...}
    },
    ...
  ]
}

Propositions can be classified into these basic scope types:

  • Page - propositions with scope equal to "view" or to the default surface.
  • View - propositions with "scopeDetails.characteristics.scopeType" equal to "view". These correspond to SPA view propositions.
  • Proposition - all other propositions. These are the ones that were explicitly requested through scopes or surfaces in the sendEvent call.

Rendering propositions after sendEvent

When sendEvent is called with "renderDecisions: true", the following logic is used to determine which propositions to render based on scope type.

  • Page - These are all rendered
  • View - Only the view propositions with scopes equal to the xdm.web.webPageDetails.viewName specified in the XDM option of sendEvent will be rendered. All the view propositions are saved to the view cache so that they can be rendered in subsequent sendEvent calls.
  • Proposition - These are not rendered.
flowchart TD
  A[Experience edge] --> B[Group by scope type]
  B -->|page| C[Render]
  B -->|proposition| E[Do not render]
  B -->|view| D[View cache]
  D -->|only this view| C
Loading

Calling sendEvent without rendering decisions

If you call sendEvent with "renderDecisions: false", nothing will be rendered, but the viewCache will still be updated.

flowchart TD
  A[Experience edge] --> B[Group by scope type]
  B -->|page| E[Do not render]
  B -->|proposition| E
  B -->|view| D[View cache]
  D -->|only this view| E
Loading

Redirects

Redirects are a special case that are given priority over all other propositions. If a redirect proposition is present nothing else is rendered, and the redirect is executed right away.

Return value from sendEvent

After a sendEvent completes it returns the propositions in two keys:

  • propositions - This includes all the page, current view, and proposition type propositions. An additional key is added "renderAttempted" which is true or false depending on if the proposition will be rendered.
  • decisions - (deprecated) This only includes the propositions from above that were not rendered.

Display notifications

After propositions are rendered, a display notification is sent to experience edge so that the personalization providers can know that the user actually saw the notification. Display notifications record which propositions were rendered by echoing back the id, scope, and scopeDetails from the original proposition. This data is recorded as an array in xdm._experience.decisioning.propositions.

Single page application (SPA)

As mentioned previously, scope type view propositions are saved in a view cache. If you call sendEvent again with xdm.web.webPageDetails.viewName set, the propositions for that view will be rendered. This rendering will be done before sending the event. The event will also include the display notifications for the propositions that were rendered.

Proposition items

Propositions have a set of items that contain the information needed for rendering. The item has a schema and data. The schema tells what kind of item it is and the data has the specific details. In the code, rendering has been organized by schema. Each schema has its own processing code. An item processor accepts an item, and returns an object with the following fields:

  • "render" - function - The async render function to call to render the item.
  • "setRenderAttempted" - boolean - This controls the renderAttempted flag within the returned propositions.
  • "includeInNotification" - boolean - This controls whether or not to include this proposition in a display notification.
  • "onlyRenderThis" - boolean - This is used for redirect item rendering so that only the redirect is rendered.
Clone this wiki locally