> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # TAF- (Tell-A-Friend) > Existing customers recommend products via a personal link. The four TAF tags generate this link and show in the shop whether the visitor was referred. With configuration, check chain and transfer to the merchandise management system. 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 1. 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. 2. They pass the link on, through whatever channel. 3. The recipient calls the link. The shop system decrypts the parameter, checks it and remembers the referrer in the session. 4. The recipient places an order. The identifier and customer number of the referrer are added to the order data. 5. The merchandise management system reads the order and starts its own refer-a-friend process. > [!NOTE] > > 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. ```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Allow = yes AttributionModel = last-touch CookieDays = 0 ``` | 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` | > [!WARNING] > > `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. ### Cookie and consent 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. ```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Allow = yes ... <+Entry> ... +WEBSALEService = TellAFriendCookie ... ``` > [!NOTE] > > 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. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {PR-Data} ... {ST-LoggedIn} ~DC-CustomLink_SetLink($PR-Link$)~ ~DC-CustomLink_AppendParameter($TAF-Name$,$TAF-Value$)~ Dieses Produkt weiterempfehlen {/ST-LoggedIn} ... {/PR-Data} ``` The finished link then looks like this: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www.ihrshop.de/ws_product.htm?...&taf=4f3a1c...e9b2 ``` > [!NOTE] > > 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. > [!WARNING] > > 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 | > [!WARNING] > > 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`. > [!NOTE] > > 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. ```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ... TellAFriend_UserIndex = 48213 TellAFriend_CustomerNumber = K-100043 ... ``` | 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 | > [!NOTE] > > 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`. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {ST-LoggedIn} ~DC-CustomLink_SetLink($PR-Link$)~ ~DC-CustomLink_AppendParameter($TAF-Name$,$TAF-Value$)~ Dieses Produkt weiterempfehlen {/ST-LoggedIn} ``` > [!NOTE] > > 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. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {TAF-Value} ~DC-CustomLink_SetLink($PR-Link$)~ ~DC-CustomLink_AppendParameter($TAF-Name$,$TAF-Value$)~ Dieses Produkt weiterempfehlen {/TAF-Value} {!TAF-Value}

Melden Sie sich an, um dieses Produkt weiterzuempfehlen.

{/!TAF-Value} ``` > [!NOTE] > > 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. > [!WARNING] > > 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. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {TAF-IsSet}

Sie wurden empfohlen. Ihre Prämie wird nach der Bestellung gutgeschrieben.

{/TAF-IsSet} {!TAF-IsSet}

Noch keine Empfehlung hinterlegt.

{/!TAF-IsSet} ``` > [!WARNING] > > `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`. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {TAF-UserIndex} {/TAF-UserIndex} {!TAF-UserIndex} {/!TAF-UserIndex} ``` > [!NOTE] > > 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. | ## Related topics - [DC- (comparisons and other tags)](https://dokumentation.websale.de/en/v8s/referenz/tags/dc/vergleiche.md) - [External services and interfaces](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/externe-dienste-und-schnittstellen.md) - [Cookies used](https://dokumentation.websale.de/en/v8s/referenz/verwendete-cookies.md) - [Materials: consent to data processing](https://dokumentation.websale.de/en/v8s/materialien/materialien-einwilligung-zur-datenverarbeitung.md) - [E-BP- (BestPrice order)](https://dokumentation.websale.de/en/v8s/referenz/tags/e-bp.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.