TAF- (Tell-A-Friend) - WEBSALE Dokumentation

A logged-in existing customer receives a personal referral link in the shop. If they pass this link on and the recipient then places an order, the referrer and the referred customer appear side by side in the order data. What comes of this, such as loyalty points, rewards or gifts, is decided by the merchandise management system. The shop system takes on exactly three tasks: it generates the referral link, it remembers the referrer in the session and, if desired, in a cookie, and it writes the referral information into the order data. It does not award any rewards itself, does not keep statistics and does not send invitation emails.

How a referral works

The existing customer logs in and calls a page on which you have built in the referral link. The shop system encrypts their identifier and appends it to the link as a URL parameter.
They pass the link on, through whatever channel.
The recipient calls the link. The shop system decrypts the parameter, checks it and remembers the referrer in the session.
The recipient places an order. The identifier and customer number of the referrer are added to the order data.
The merchandise management system reads the order and starts its own refer-a-friend process.

The feature is available from release version 82 and does not need to be enabled. However, the transfer to a merchandise management or ERP system cannot be mapped via the WSP Manager; a connector module is required for this. Without this module, the shop does generate links and recognise referrers, but the information remains in the order data. Contact your WEBSALE contact person about the connector module.

Shop configuration

Add the TellAFriend section to the shop configuration shop.config. The following values correspond to the defaults.

<TellAFriend>
   Allow            = yes
   AttributionModel = last-touch
   CookieDays       = 0
</TellAFriend>

Parameter	Meaning	Values
`Allow`	Controls whether the referrer information is written into the order data. With `no`, the entry is omitted entirely.	`yes`, `no`. Default `yes`
`AttributionModel`	Determines which referrer counts if several referral links are called in one session. `last-touch` lets the most recently called link win, `first-touch` keeps the first referrer and discards later links.	`last-touch`, `first-touch`. Default `last-touch`
`CookieDays`	Lifetime of the cookie in days. With `0`, the assignment only applies to the current session. With a value greater than `0`, the referrer is still recognised on a later visit.	Integer. Default `0`

Allow only affects writing the order data. With Allow = no, the shop system continues to generate referral links, recognise referrers and respond to all TAF- tags as usual. Only the two lines in the order are missing. If you want to switch off the feature in the shop completely, also remove the referral link from the templates.

If you set CookieDays to a value greater than 0, register the cookie as a WEBSALE service in the AgreementCookies section of the shop configuration shop.config.

<AgreementCookies>
   Allow = yes
   ...
   <+Entry>
      ...
      +WEBSALEService = TellAFriendCookie
   </+Entry>
   ...
</AgreementCookies>

Without consent, the shop system neither writes nor reads the cookie. The assignment of the referrer then continues to work, but only within the current session. If the visitor gives consent later in the same visit, the cookie is written retroactively.

Reference: TellAFriend section, AgreementCookies section

Generating the referral link in the template

The referral link is an ordinary shop link with an additional parameter. TAF-Name returns the parameter name, TAF-Value the encrypted value. Both are assembled with the DC-CustomLink tags. Because only logged-in customers can make recommendations, the link belongs in a bracketing with ST-LoggedIn. The following example attaches the link to the product detail view ws_product.htm.

{PR-Data}
   ...
   {ST-LoggedIn}
      ~DC-CustomLink_SetLink($PR-Link$)~
      ~DC-CustomLink_AppendParameter($TAF-Name$,$TAF-Value$)~

      <a href="~DC-CustomLink~">Dieses Produkt weiterempfehlen</a>
   {/ST-LoggedIn}
   ...
{/PR-Data}

The finished link then looks like this:

https://www.ihrshop.de/ws_product.htm?...&taf=4f3a1c...e9b2

The {TAF-Value} bracketing applies exactly when a customer is logged in, and is therefore equivalent to {ST-LoggedIn} at this point. You can also bracket the block with TAF-Value instead of ST-LoggedIn if that reads better in the template. Both at the same time are not necessary.

The referral link only works in the shop in which it was generated. The shop identifier is encrypted in the parameter and is checked against the called shop when the link is opened. A link from the German shop does not work in another shop of the mall.

Reference: PR-Data, ST-LoggedIn, DC-CustomLink_SetLink(), DC-CustomLink_AppendParameter(), DC-CustomLink

What happens when the referral link is called

The shop system takes the taf parameter from the URL and checks it in several steps before writing the referrer into the session.

Check	The link does not apply if …
Attribution	`AttributionModel = first-touch` is configured and there is already a referrer in the session
Character set and length	the parameter value contains characters other than hexadecimal digits and hyphens, or is too long
Decryption	the value cannot be decrypted, for example because it was truncated or altered when passed on
Shop binding	the link was generated in a different shop
Self-referral	the logged-in visitor is the referrer themselves
Customer account	the referrer’s customer account no longer exists or is no longer active

All these cases are silently discarded. There is no error message and no notice in the template; the visitor simply lands on a page without a referrer. An entry at Info level appears in the log. To check a link during testing, use TAF-UserIndex.

The self-referral case is checked twice: when the link is called and again immediately before the order is written. This also covers the case in which someone calls their own link while logged out and only logs in afterwards.

Where the referrer comes from

The shop system first looks for the referrer in the URL parameter. If there is nothing there, it reads the cookie, but only if there is no referrer in the session yet and consent has been given. The cookie is only renewed if the value came from the URL and CookieDays is greater than 0. The referrer’s customer number is not in the link. The encrypted parameter contains the shop identifier, the internal customer identifier and a timestamp. The shop system fetches the customer number from the customer account as soon as it is needed.

How long the assignment applies

A recognised referrer applies to exactly one order. After a successful order, the shop system resets the assignment and deletes the cookie, even if CookieDays provides for a longer lifetime. A second purchase therefore does not count towards the same referrer again unless a referral link is called again.

The order data

If Allow = yes is set and a referrer has been recognised, the shop system writes two additional lines into the Order section of the order data.

<Order>
   ...
   TellAFriend_UserIndex      = 48213
   TellAFriend_CustomerNumber = K-100043
   ...
</Order>

Field	Content
`TellAFriend_UserIndex`	the referrer’s internal customer identifier in the shop system
`TellAFriend_CustomerNumber`	the referrer’s customer number from the customer account

Both lines always appear together or not at all. If no referrer has been recognised, they are missing entirely; no empty fields are written. Your merchandise management system should therefore check for the presence of the field and not for an empty value.

TAF-Name

Returns the name of the URL parameter via which the encrypted referral information is passed. The value is fixed and is taf.

{ST-LoggedIn}
   ~DC-CustomLink_SetLink($PR-Link$)~
   ~DC-CustomLink_AppendParameter($TAF-Name$,$TAF-Value$)~

   <a href="~DC-CustomLink~">Dieses Produkt weiterempfehlen</a>
{/ST-LoggedIn}

Use TAF-Name instead of hard-coding taf in the template. If the parameter name changes in a future version of the shop system, your templates will follow automatically.

Usable as	Single tag	Area tag	Negative area tag	Loop tag
`TAF-Name`	yes	–	–	–

Permitted in all templates.

TAF-Value

Returns the encrypted value that follows the parameter name in the referral link. It contains the shop identifier, the internal customer identifier of the logged-in customer and a timestamp. The value is hexadecimal-encoded and can therefore be used in a URL without further encoding. As a bracketing, the tag applies if a customer is logged in.

{TAF-Value}
   ~DC-CustomLink_SetLink($PR-Link$)~
   ~DC-CustomLink_AppendParameter($TAF-Name$,$TAF-Value$)~

   <a href="~DC-CustomLink~">Dieses Produkt weiterempfehlen</a>
{/TAF-Value}

{!TAF-Value}
   <p>Melden Sie sich an, um dieses Produkt weiterzuempfehlen.</p>
{/!TAF-Value}

The encrypted value is generated once per session and reused afterwards. All referral links of a session therefore carry the same value, regardless of which page they point to. After logging out, a new session begins and thus a new value.

If encryption fails, the single tag outputs nothing and reports no error. The template then produces a link with an empty parameter, which is discarded when called. During setup, check a generated link to make sure there actually is a value after taf=.

Usable as	Single tag	Area tag	Negative area tag	Loop tag
`TAF-Value`	yes	yes	yes	–

Permitted in all templates.

TAF-IsSet

Applies if a referrer has been recognised in the current session, that is, if the visitor entered the shop via a valid referral link. Use it to show notices that only apply to referred customers.

{TAF-IsSet}
   <p>Sie wurden empfohlen. Ihre Prämie wird nach der Bestellung gutgeschrieben.</p>
{/TAF-IsSet}

{!TAF-IsSet}
   <p>Noch keine Empfehlung hinterlegt.</p>
{/!TAF-IsSet}

TAF-IsSet is exclusively a bracketing. As a single tag ~TAF-IsSet~, the shop system reports an invalid tag.

Usable as	Single tag	Area tag	Negative area tag	Loop tag
`TAF-IsSet`	–	yes	yes	–

Permitted in all templates.

TAF-UserIndex

Outputs the referrer’s internal customer identifier. As a bracketing, the tag applies if a referrer is set and thus behaves like TAF-IsSet.

{TAF-UserIndex}
   <!-- Werbender: ~TAF-UserIndex~ -->
{/TAF-UserIndex}

{!TAF-UserIndex}
   <!-- Kein Werbender in der Sitzung -->
{/!TAF-UserIndex}

The tag is intended for troubleshooting. When testing a referral link, the output identifier lets you determine whether the correct referrer was recognised and look up the customer in the merchandise management system. The number has no meaning for shop visitors, so only output it in a comment or on an internal test page.

Usable as	Single tag	Area tag	Negative area tag	Loop tag
`TAF-UserIndex`	yes	yes	yes	–

Permitted in all templates.

Tags at a glance

Tag	Single tag	Area tag	Negative area tag	Loop tag
`TAF-Name`	yes	–	–	–
`TAF-Value`	yes	yes	yes	–
`TAF-IsSet`	–	yes	yes	–
`TAF-UserIndex`	yes	yes	yes	–

Troubleshooting

Observation	Possible cause
The link contains no `taf=`	The customer is not logged in. `TAF-Value` only returns a value for logged-in customers.
There is nothing after `taf=`	Encryption failed. In this case, the tag silently outputs nothing.
`TAF-IsSet` does not apply	One of the checks when calling the link discarded it. The table in the section on calling the referral link lists the cases.
`TAF-IsSet` does not apply for your own link	Self-referral is rejected. Test with a second customer account or while logged out.
After a second link, the first referrer is still set	`AttributionModel = first-touch` is configured.
After restarting the browser, the referrer is gone	`CookieDays = 0`, or consent for the cookie has not been given.
After an order, the referrer is gone	This is intended. The assignment applies to exactly one order.
The order data contains no TAF fields	`Allow = no`, or no referrer was recognised.

​How a referral works

​Shop configuration

​Cookie and consent

​Generating the referral link in the template

​What happens when the referral link is called

​Where the referrer comes from

​How long the assignment applies

​The order data

​TAF-Name

​TAF-Value

​TAF-IsSet

​TAF-UserIndex

​Tags at a glance

​Troubleshooting

How a referral works

Shop configuration

Cookie and consent

Generating the referral link in the template

What happens when the referral link is called

Where the referrer comes from

How long the assignment applies

The order data

TAF-Name

TAF-Value

TAF-IsSet

TAF-UserIndex

Tags at a glance

Troubleshooting