Onsite personalization - WEBSALE Dokumentation

With onsite personalization, you deliver shop content tailored to target groups. Depending on the customer group, you display different banners, design your own color schemes or redirect the customer to a landing page intended for them each time they open the shop. Control is handled by a cookie that the shop manages itself. Its content is encrypted, so the customer cannot change it. This is the key difference from control via URL parameters, which any visitor can rewrite in the address bar.

How personalization works

Using the example of a pet supplies shop for dogs and cats:

Step	What happens
You send target-group-specific newsletters	One newsletter for cat owners, one for dog owners
The customer clicks a link in the newsletter	They land on a specific shop page
This page sets the cookie	Key `kundengruppe`, value `katze`
On every further page request, the shop reads the cookie	The cat owner sees the bestsellers from cat supplies, the dog owner those from dog supplies

The same procedure also supports other personalizations, for example custom color schemes or a redirect to a fixed landing page, both in the current session and on later visits. The shop stores any number of key-value pairs in a single cookie. It encrypts the content with AES-256 and then compresses it. So the cookie can neither be used to read nor to influence which target group a visitor is assigned to. The cookie name is ws_<Shop>_<Sprache>_design_cookie.

The language code is part of the cookie name. A visitor who switches language therefore starts in the new language without an assignment. If your personalization should apply across languages, you must set the cookie again in each language.

Keys are compared case-insensitively. Kundengruppe and kundengruppe are therefore the same key. If you set the same key again, the previous value is replaced.

Keys and values must not contain a vertical bar. The shop separates the entries in the cookie with this character, so a value like hund|katze breaks the cookie.

Prerequisites

Onsite personalization does not need to be activated by WEBSALE AG. However, two conditions must be met for the cookie to be written at all:

The customer has enabled cookies in their browser.
Consent has been given for the service, if you use consent management.

As soon as you use the shop’s consent management in production, onsite personalization requires consent. The associated WEBSALE service is called DesignCookie and must be assigned to a consent entry in the shop configuration.

If no consent has been given, DC-CookieData_set silently does not work. There is no error message and no empty output value; the cookie is simply neither written nor read. If your personalization has no effect in live operation, first check whether the DesignCookie service is in a consent group that has been agreed to.

If consent management is not active at all, this check is skipped and the cookie is always written. Please clarify with your data protection officer which information texts your customers need about the use of cookies.

Guide: Cookies · Consent management

Step 1: Define the validity period

The validity period of the cookie is 30 days by default. You define it in the shop configuration shop.config in the Basic section.

<Basic>
   ...
   DesignCookieDays       = 30
   ...
</Basic>

Without an entry or with the value 0, 30 days apply.

Reference: Basic section

Step 2: Create the displays as includes (optional)

You have two ways to deliver the target-group-specific content. Either you load separate include templates, or you store the content directly in the template and show and hide it with brackets. Step 4 shows both ways. For the include approach, create the templates now and save them in the template directory benutzer/templates/translation. In the example, these are:

File	Content
`incl_katze.htm`	Display for cat owners
`incl_hund.htm`	Display for dog owners
`incl_startseite.htm`	Default content if there is no cookie

The structure of the file names is no coincidence. The shop later assembles the file name from a fixed prefix and the value of the cookie, following the pattern incl_<Wert des Cookies>.htm. The file names therefore determine the values you assign in the next step: katze and hund. On the pages that should identify a target group, add the following code. In the example, this is the landing page for cat owners.

~DC-CookieData_set(kundengruppe,katze)~
{DC-CookieData_cookieHasChanged}
<script type="text/javascript">
   var newDate=new Date();
   var days=30; //{WS-TPLComment} Muss mit DesignCookieDays in der shop.config übereinstimmen {/WS-TPLComment}
   newDate.setTime(newDate.getTime()+(days*24*60*60*1000));
   document.cookie ="~DC-CookieData_cookieName~=\"~DC-CookieData_cookieValue~\"; expires="+newDate.toGMTString();
</script>
{/DC-CookieData_cookieHasChanged}

The landing page for dog owners contains the same block, only with the value hund:

~DC-CookieData_set(kundengruppe,hund)~

The shop additionally sends the design cookie itself as a Set-Cookie header, using the value from DesignCookieDays. That is why var days in the script must have the same value. If the two do not match, the lifetime of the cookie depends on which of the two ways wrote it last.

The DC-CookieData_cookieHasChanged bracket only applies if something has actually changed in the cookie content. If you set the same key with the same value again, the script is not output. This is intentional and saves unnecessary write operations in the browser.

DC-CookieData_set needs both values. If the key or the value is missing, nothing happens. So make sure that a tag you pass as a value is actually filled.

Browsers limit the size of a cookie to about 4 KB. The shop also logs a warning if the encrypted content becomes too large and discards it completely if it exceeds twice the upper limit. So only write short identifiers into the cookie, not entire data records.

Reference: DC-CookieData_set() · DC-CookieData_cookieHasChanged · DC-CookieData_cookieName · DC-CookieData_cookieValue

Step 4: Deliver the content

Both ways depend on the same bracket. {DC-CookieData(kundengruppe)} applies if the key is present in the cookie; the negated form {!DC-CookieData(kundengruppe)} applies if it is missing. Within the bracket, ~DC-CookieData_touchKey(kundengruppe)~ remembers which key is currently meant. Only then does $DC-CookieData_lastValueTouched$ return its value.

Way A: Include technique

The value from the cookie is inserted into the file name. If the cookie contains the value hund,

~WS-DynIncludeTpl(incl_$DC-CookieData_lastValueTouched$.htm)~

becomes the call ~WS-DynIncludeTpl(incl_hund.htm)~. In full, it looks like this:

<!-- Anfang Content mit Cookie -->
{DC-CookieData(kundengruppe)}
   ~DC-CookieData_touchKey(kundengruppe)~
   ~WS-DynIncludeTpl(incl_$DC-CookieData_lastValueTouched$.htm)~
{/DC-CookieData(kundengruppe)}

{!DC-CookieData(kundengruppe)}
   ~WS-IncludeTpl(incl_startseite.htm)~
{/!DC-CookieData(kundengruppe)}
<!-- Ende Content mit Cookie -->

The file name is created from a value stored in the cookie. Create an include template for every value you ever set. If a file is missing, nothing appears at that point, and the customer does not see the default content either, because the key is present.

Guide: Reuse: Includes Reference: DC-CookieData() · DC-CookieData_touchKey · DC-CookieData_lastValueTouched · WS-DynIncludeTpl · WS-IncludeTpl

Way B: Brackets directly in the template

Instead of loading include templates, you pass the value to a design parameter and use it to bracket the content directly in the template.

<!-- Anfang Content mit Cookie -->
{DC-CookieData(kundengruppe)}
   ~DC-CookieData_touchKey(kundengruppe)~
   ~DC-FPZielgruppe_set($DC-CookieData_lastValueTouched$)~

   {DC-FPZielgruppe(katze)}
      Unsere Bestseller: die meistverkauften Produkte für Katzen
      {CAT-LoadData(<Index Kategorie Katze>,999)}
         {CAT-LoadData_OK}
            {CAT-LoadData_HasProducts}
               {@PR-Data}
                  ~PR-Name~
               {/@PR-Data}
            {/CAT-LoadData_HasProducts}
         {/CAT-LoadData_OK}
      {/CAT-LoadData(<Index Kategorie Katze>,999)}
   {/DC-FPZielgruppe(katze)}

   {DC-FPZielgruppe(hund)}
      Unsere Bestseller: die meistverkauften Produkte für Hunde
      {CAT-LoadData(<Index Kategorie Hund>,999)}
         {CAT-LoadData_OK}
            {CAT-LoadData_HasProducts}
               {@PR-Data}
                  ~PR-Name~
               {/@PR-Data}
            {/CAT-LoadData_HasProducts}
         {/CAT-LoadData_OK}
      {/CAT-LoadData(<Index Kategorie Hund>,999)}
   {/DC-FPZielgruppe(hund)}
{/DC-CookieData(kundengruppe)}

{!DC-CookieData(kundengruppe)}
   Katzen- und Hundefreunde finden bei uns die besten Angebote für ihre Lieblinge.
{/!DC-CookieData(kundengruppe)}
<!-- Ende Content mit Cookie -->

Replace <Index Kategorie Katze> and <Index Kategorie Hund> with the indexes of your categories.

Way B is suitable for manageable differences such as headings, banners or color schemes. As soon as entire page areas differ, way A becomes clearer, because each target group gets its own file and the main template stays lean.

Reference: DC-FPX · DC-CookieData() · DC-CookieData_touchKey · DC-CookieData_lastValueTouched In addition to the tags used above, further tags are available that in some cases get you to your goal more quickly.

Tag	Effect
`DC-CookieData_get(schlüssel)`	outputs the value for a key, without a preceding `touchKey`
`DC-CookieData_lastKeyTouched`	outputs the key last set with `touchKey`
`{DC-CookieData}` without parameters	loop over all key-value pairs in the cookie

Within the loop, ~DC-CookieData~ returns the key and ~DC-CookieData_get~ without parameters returns the associated value. This is the most convenient way to check in test mode what the cookie actually contains.

Reference: DC-CookieData_get · DC-CookieData_lastKeyTouched

Guide: Cookies
Guide: Reuse: Includes
Guide: Consent management

​How personalization works

​What the cookie contains

​Prerequisites

​Consent in consent management

​Step 1: Define the validity period

​Step 2: Create the displays as includes (optional)

​Step 3: Set the cookie

​Step 4: Deliver the content

​Way A: Include technique

​Way B: Brackets directly in the template

​Further tags for accessing the cookie

​Related topics

How personalization works

What the cookie contains

Prerequisites

Consent in consent management

Step 1: Define the validity period

Step 2: Create the displays as includes (optional)

Step 3: Set the cookie

Step 4: Deliver the content

Way A: Include technique

Way B: Brackets directly in the template

Further tags for accessing the cookie

Related topics