Werbemittelkennzeichen

Werbemittelkennzeichen ordnen Bestellpositionen einem Werbemittel wie beispielsweise einem Katalog, einer Anzeige oder einem Mailing, zu.

Werbemittelkennzeichen, auch Werbemittelcodes genannt, sind kurze Codes, anhand derer sich nachvollziehen lässt, über welches Werbemittel eine Bestellung zustande gekommen ist. Beispiele hierfür sind ein bestimmter Katalog, eine Anzeige oder ein Mailing. Der Code wird an die Produktnummer angehängt, beispielsweise 123456-09 . Dabei steht 123456 für die Produktnummer und 09 für das Werbemittelkennzeichen.

In den Bereichen Konfiguration, Templates und Schnittstellen trägt dieses Konzept den technischen Namen Insert . Die zugehörigen Felder heißen etwacontent.inserts (Konfiguration), validInsertCodes (gültige Codes je Produkt) und insert (Code einer einzelnen Position). Die Tabelle im Abschnitt Begriffe und technische Namen ordnet alle Namen einander zu.

Die vollständigen technischen Details je Ebene (Template-Modul, Konfiguration, REST- und Storefront-API) stehen auf den unter Weiterführende Links verlinkten Detailseiten.

Die Funktion ist standardmäßig ausgeschaltet. Solange sie nicht aktiviert und eingerichtet ist (siehe Voraussetzungen), verhält sich der Shop unverändert: keine zusätzlichen Eingabefelder, keine zusätzlichen Anzeigen, nichts wird gespeichert.

​

Voraussetzungen

Damit ein Werbemittelkennzeichen wirken kann, müssen drei Dinge erfüllt sein. Fehlt auch nur eines davon, bleibt die Funktion für das betroffene Produkt wirkungslos - es erscheint in diesem Fall auch keine Fehlermeldung.

1. Die Funktion ist aktiviert. In der Konfiguration muss content.inserts.enabled auf true stehen. Solange sie aus ist, wird kein Code erfasst, aufgelöst oder angezeigt.
2. Die Feldzuordnung ist eingerichtet (einmalig pro Shop). Der Shop muss wissen, welches Produktfeld die gültigen Codes enthält. Diese Zuordnung wird in content.usedFields.products.validInsertCodes hinterlegt. Fehlt sie, findet der Shop die am Produkt gepflegten Codes nicht und behandelt jedes Produkt so, als hätte es keine gültigen Codes.
3. Am Produkt sind gültige Codes gepflegt. Erst wenn ein Produkt im Feld validInsertCodes konkrete Codes trägt, kann für dieses Produkt ein Code übernommen werden. Ist die Liste leer, greift der Standardcode (defaultInsertCode), sofern einer konfiguriert ist.

Die konkreten Schritte dazu stehen weiter unten im Abschnitt Einrichtung.

Ohne Feldzuordnung (Punkt 2) wirken die produktspezifischen Codes nicht . Es reicht nicht, das Produktfeld nur anzulegen und Codes einzutragen. Fehlt die Zuordnung in usedFields.products, erhält jede Position stillschweigend den Standardcode (oder gar kein Kennzeichen), auch wenn an den Produkten Codes gepflegt sind.

​

Begriffe und technische Namen auf einen Blick

Je nach Ebene (Admin-Interface, Konfiguration, Template oder Schnittstelle) heißt das Konzept der Werbemittelkennzeichen unterschiedlich. Diese Tabelle ordnet die verschiedenen Bezeichnungen einander zu.

Konzept	Admin Interface	Konfiguration	Template	Schnittstelle
Funktion aktiv	Einstellungen -> Shop-Konfiguration -> Gruppe "Werbemittelkennzeichen"	$wsConfig.inserts.enabled	enabled in GET config/inserts
Standardcode	Einstellungen -> Shop-Konfiguration -> Gruppe "Werbemittelkennzeichen"	content.inserts.defaultInsertCode	$wsConfig.inserts.defaultInsertCode	defaultInsertCode in config/inserts
Trennzeichen	Einstellungen -> Shop-Konfiguration -> Gruppe "Werbemittelkennzeichen"	content.inserts.separator	$wsConfig.inserts.separator	separator in config/inserts
Position (davor/dahinter)	Einstellungen -> Shop-Konfiguration -> Gruppe "Werbemittelkennzeichen"	content.inserts.position	$wsConfig.inserts.position	position in config/inserts
Gültige Codes je Produkt	Feld „Gültige Werbemittelkennzeichen” (Details)	validInsertCodes (Produktfeld)	—	custom.validInsertCodes (Admin-API)
Feldzuordnung (einmalig)	—	usedFields.products.validInsertCodes	—	—
Code je Warenkorbposition	—	—	$item.insert	insert (add / update)
Produktnummer inklusive Code	—	—	$item.itemNumberWithInsert	itemNumberWithInsert (Response)
Code an einer URL übergeben	—	—	—	URL-Parameter insert

In den gespeicherten Bestelldaten trägt der Code den Namen insertCode (nicht insert). Beim Auslesen einer abgeschlossenen Bestellung ist daher dieser Name maßgeblich. Die genauen Feldnamen je Schnittstelle stehen auf den jeweiligen Detailseiten (siehe Weiterführende Links).

​

Wie der Shop ein Werbemittelkennzeichen ermittelt

Sind die Voraussetzungen erfüllt, ermittelt der Shop beim Hinzufügen eines Produkts in den Warenkorb das Werbemittelkennzeichen für diese Position in folgender Reihenfolge:

1. Ein gültiger Code wurde angegeben → Der Code wird für das Produkt übernommen.
2. Kein Code wurde angegeben → Der Shop versucht, den zuletzt in dieser Sitzung verwendeten Code (das sitzungsweite Werbemittelkennzeichen) zu übernehmen, sofern er für dieses Produkt gültig ist.
3. Andernfalls → Es greift der in der Konfiguration hinterlegte Standardcode (defaultInsertCode). Ist keiner hinterlegt, bleibt die Position ohne Kennzeichen.

Die drei Fälle bauen aufeinander auf. Fall 3 greift nur, wenn kein Code angegeben wurde und es keinen passenden Sitzungscode gibt. “Kein Code → Standardcode” ist also keine Absolutregel, sondern der letzte Schritt der Kette.

​

Sitzungsweites Werbemittelkennzeichen

Sobald ein gültiger Code erkannt wurde, merkt sich der Shop diesen für die laufende Sitzung. Dabei handelt es sich um den in Fall 2 oben beschriebenen Code, der für nachfolgende Produkte ohne eigene Code-Angabe herangezogen wird. Der Code bleibt auch erhalten, wenn ein Artikel zwischendurch aus dem Warenkorb entfernt wird.

Gibt der Besucher später auf einem der Erfassungswege einen weiteren gültigen Code an, tritt dieser an die Stelle des bisherigen. Ab dann gilt der neue Code als sitzungsweites Werbemittelkennzeichen. Ein leerer oder ungültiger Code überschreibt den gemerkten Code hingegen nicht. Mit Abschluss der Bestellung wird der gemerkte Code gelöscht.

​

Was bedeutet „gültiger Code”

Welche Codes für ein Produkt zulässig sind, legt die Produktpflege fest. Die Prüfung erfolgt zeichengenau und unter Beachtung der Groß-/Kleinschreibung. So sind beispielsweise DA und da nicht dasselbe.

​

Speicherung in der Bestellung

Das ermittelte Werbemittelkennzeichen wird mit der Bestellung gespeichert und steht damit in der Bestellauswertung als eigene Information zur Verfügung.

​

Wo ein Code erfasst werden kann

Es gibt drei voneinander unabhängige Wege, auf denen ein Werbemittelkennzeichen in den Shop gelangt.

• Über die URL: Ein Werbemittelkennzeichen lässt sich per URL-Parameter insert an einen Produktaufruf anhängen - ideal für Links aus Katalogen, Anzeigen oder Mailings. Dies ist auf zwei unabhängigen Wegen möglich:
  • an einer technischen View-URL über die Produkt-ID: ?view=Product&productId=<ProduktId>&insert=<Code>
  • an einer SEO-URL des Produkts: /buntes-t-shirt?insert=<Code>
• Direktbestellung: Auf der Direktbestellseite kann pro Eingabezeile ein Feld für das Werbemittelkennzeichen hinzugefügt werden. Dies ist eine Template-Erweiterung. Die Umsetzung ist unter Beispiele beschrieben.
• Warenkorb (Schnittstelle): Beim Hinzufügen oder Ändern eines Postens kann der Code direkt mitgegeben werden - siehe Storefront-API Warenkorb.

Eine View-URL ist dabei eine über die Template-Funktion $wsViews.url(...) bzw. $wsViews.viewUrl(...) erzeugte, technische Shop-URL (im Gegensatz zur sprechenden SEO-URL) - Details siehe Modul $wsViews. Beide URL-Arten nehmen den insert-Parameter gleichermaßen an.

Wird ein Produkt ohne insert-Parameter aufgerufen, bleibt ein bereits gesetztes sitzungsweites Werbemittelkennzeichen erhalten - „kein Parameter” wird also nicht wie „kein Code” behandelt. Der Sitzungscode wird erst beim Hinzufügen des Produkts in den Warenkorb herangezogen und dort gegen die gültigen Codes geprüft.

​

Praxisbeispiel: von der Anzeige bis zur Bestellung

Folgendes Szenario veranschaulicht, wie die Regeln zusammenspielen:

Ein Kunde erhält ein Mailing mit einem Produktlink, an den das Werbemittelkennzeichen 09 angehängt ist (beispielswiese/buntes-t-shirt?insert=09). Mit einem Klick gelangt er auf die Produktseite. Der Code 09 wird als sitzungsweites Werbemittelkennzeichen gespeichert.

Anschließend legt er das T-Shirt in den Warenkorb. Da 09 für dieses Produkt ein gültiger Code ist, trägt die Position das Kennzeichen und die Artikelnummer erscheint als 123456-09.

Anschließend stöbert er weiter und legt eine Hose in den Warenkorb, ohne dabei einen Code aufzurufen. Der Shop zieht den gemerkten Sitzungscode 09 heran. Wenn 09 auch für die Hose gültig ist, wird auch diese Position mit 09 gekennzeichnet. Andernfalls greift der Standardcode oder die Position bleibt ohne Kennzeichnung.

Beim Wechsel zur Kasse und dem Abschluss der Bestellung wird das ermittelte Kennzeichen jeder Position zusammen mit der Bestellung gespeichert. Anschließend wird die Sitzung beendet und der gemerkte Code 09 wird verworfen.

In der Bestellhistorie steht das gespeicherte Kennzeichen zwar in den Bestelldaten (als insertCode), die fertig zusammengesetzte Anzeige itemNumberWithInsert ist dort jedoch nicht verfügbar. Wie sich das Kennzeichen in der Bestellhistorie darstellen lässt, ist unter Beispiele → Bestellhistorie beschrieben.

​

Sonderfälle

Set-Artikel: Der Code wird sowohl für die Hauptposition als auch für die enthaltenen Unterartikel aufgelöst. Jeder Unterartikel prüft den Code gegen seine eigenen gültigen Codes (sonst greift der Standardcode). Das funktioniert genauso wie bei einem einzeln hinzugefügten Artikel.

Varianten: Die zulässigen Codes werden auf Ebene des Hauptprodukts gepflegt und gelten gleichermaßen für dessen Varianten. Beim Hinzufügen einer Variante wird das sitzungsweite Kennzeichen gegen die gültigen Codes des Hauptprodukts geprüft.

​

Einrichtung

Dieser Abschnitt beschreibt die konkreten Schritte zu den unter Voraussetzungen genannten Bedingungen.

​

Konfiguration

Die Einstellungen liegen im Konfigurationsbereich unter (content.inserts):

Einstellung	Bedeutung	Standard
enabled	Schaltet die gesamte Funktion ein bzw. aus.	aus
defaultInsertCode	Wird verwendet, wenn kein oder ein ungültiger Code erfasst wurde. Leer lassen, wenn in diesem Fall gar kein Kennzeichen gesetzt werden soll.	leer
separator	Zeichen zwischen Produktnummer und Code, beispielsweise -.	-
position	Steht der Code hinter der Produktnummer (123456-09) oder davor (09-123456).	dahinter

Solange enabled deaktiviert ist, bleibt die Funktion im gesamten Shop wirkungslos - unabhängig davon, wie die einzelnen Produkte gepflegt sind.

Hinweis zu defaultInsertCode: Der Standardcode greift produktübergreifend für jede Eingabe, die nicht zu einem gültigen Code aufgelöst werden kann. Wer den Code auf einen festen Wert setzt, sollte bedenken, dass dieser Wert dann auch für Posten verwendet werden kann, für die eigentlich kein Werbemittelkennzeichen vorgesehen ist. Im Zweifel sollten Sie den Wert leer lassen.

​

Produktfeld anlegen

Ist das Feld validInsertCodes im Shop noch nicht vorhanden, wird es einmalig als benutzerdefiniertes Produktfeld angelegt. Im Admin Interface geschieht das im Bereich Katalog → Produkte über die Produktfelder-Einstellungen (Einstellungen / Zahnrad rechts oben anwählen). Die dortige Tabelle zeigt alle vorhandenen Produktfelder mit Name, Typ und maximaler Länge. Über die Schaltfläche Neu wird das Feld mit folgenden Einstellungen angelegt:

Einstellung	Wert
Name	validInsertCodes
Label	Gültige Werbemittelkennzeichen
Typ	Liste (Texteinträge)
Maximale Länge	16 Zeichen je Eintrag

Alternativ kann das Feld über die REST API Konfiguration im Knoten content.customProductField erstellt werden.

​

Feldzuordnung einrichten

Nach dem Anlegen des Produktfelds muss es einmalig der Funktion zugeordnet werden. Erst durch diese Zuordnung weiß der Shop, in welchem Produktfeld die gültigen Werbemittelkennzeichen stehen.

Die Zuordnung wird im Konfigurationsknoten content.usedFields gepflegt. Im Bereich products verweist der Eintrag validInsertCodes auf das angelegte Produktfeld:

{
  "products": {
    "validInsertCodes": "content.customProductField.validInsertCodes"
  }
}

Das Beispiel zeigt nur den relevanten Eintrag. Der Knoten enthält daneben die Zuordnungen aller anderen Funktionsbereiche (beispielsweise weight, crossSelling, metaTitle). Diese bestehenden Einträge bleiben unverändert erhalten, es wird ausschließlich der Wert von validInsertCodes gesetzt.

Ohne diese Zuordnung wirken die am Produkt gepflegten Codes nicht. Der Shop kann die gültigen Codes eines Produkts dann nicht ermitteln, und jeder Posten erhält stillschweigend den Standardcode oder bleibt ohne Kennzeichen, auch wenn an den Produkten Codes gepflegt sind. Es reicht also nicht, das Produktfeld nur anzulegen, es muss auch zugeordnet werden.

​

Zulässige Codes am Produkt

Das Feld „Gültige Werbemittelkennzeichen” (validInsertCodes) ist ein benutzerdefiniertes Produktfeld und wird im Admin Interface auf der Detailseite des jeweiligen Produkts gepflegt. Wie jedes benutzerdefinierte Feld erscheint es in der Feldgruppe, der es zugeordnet wurde - andernfalls in der Sammelgruppe „Sonstige”. Über dieses Feld wird pro Produkt festgelegt, welche Codes für dieses Produkt erlaubt sind.

Es handelt sich um ein Listenfeld. Jeder gültige Code wird als eigener Eintrag erfasst. Ein Trennzeichen wird nicht benötigt und die Codes werden nicht als zusammenhängende Zeichenkette gepflegt. Folgende Voraussetzungen gelten für das Anlegen eines Codes:

• Jeder Eintrag darf maximal 16 Zeichen lang sein.
• Jeder Code ist ein eigener Listeneintrag. Die Codes werden nicht durch Kommas oder andere Trennzeichen in einem Feld aneinandergereiht.
• Die Codes sind case-sensitiv (beispielsweise ist DA nicht gleich da).
• Das Feld wird auf Ebene des Hauptprodukts gepflegt und gilt für dessen Varianten mit.
• Ist die Liste leer, kann für dieses Produkt kein Code übernommen werden (es greift höchstens der Standardcode, sofern gesetzt).

Im Template steht das Feld als Liste zur Verfügung, beispielsweise über $cProduct.custom.validInsertCodes auf der Produktseite oder $item.product.custom.validInsertCodes an der Warenkorbposition. Die Ausgabe erfolgt per Schleife oder mit join und frei wählbarem Trennzeichen:

{{= $cProduct.custom.validInsertCodes | join(", ") }}

Ergebnis
Die gültigen Codes des Produkts werden kommagetrennt angezeigt, beispielsweise DA, 09.

​

Anzeige im Shop

Das Werbemittelkennzeichen kann als Teil der Artikelnummer im Warenkorb, in der Bestellübersicht, in der Bestätigungs-E-Mail, im Bestell-PDF und in der Bestellhistorie angezeigt werden (beispielsweise 123456-09) - in der konfigurierten Reihenfolge und mit dem konfigurierten Trennzeichen. Voraussetzung ist, dass die Ausgabe im jeweiligen Template eingebunden ist (siehe Beispiele).

Die Anzeige setzt sich aus der am Produkt gepflegten Artikelnummer (itemNumber) und dem Code zusammen. Ist am Produkt keine Artikelnummer gepflegt, erscheint nur der Code.

Wird ein unbekannter Code eingegeben, verwirft der Shop diesen und greift, sofern eingerichtet, auf den Standardwert zurück. Dadurch wird die Bestellung nie blockiert.

​

Module

Für die Ausgabe des Werbemittelkennzeichens im Template werden diese Module verwendet:

• $wsConfig - liefert über $wsConfig.inserts die aktuellen Einstellungen (aktiv, Trennzeichen, Position, Standardcode) und wird benötigt, um Ausgaben nur bei aktiver Funktion anzuzeigen.
• $wsBasket - liefert je Warenkorbposition das Kennzeichen über $item.insert und die fertige Anzeige über $item.itemNumberWithInsert.

Die Erfassung eines Codes (URL, Direktbestellung, Warenkorb-Schnittstelle) benötigt kein eigenes Modul, dies geschieht über URL-Parameter, das Direktbestellformular oder die Storefront-API.

​

Beispiele

​

Artikelnummer mit Werbemittelkennzeichen ausgeben

Im Warenkorb (und analog dazu in der Bestellübersicht, der E-Mail und dem PDF) genügt es, itemNumberWithInsert als Artikelnummer auszugeben. Die Reihenfolge und das Trennzeichen sind darin bereits berücksichtigt. Wenn kein Code gesetzt ist, enthält das Feld die reine Produktnummer.

{{ foreach $item in $wsBasket.items }}
  <p>Art.-Nr.: {{= $item.itemNumberWithInsert }}</p>
  <p>Produktname: {{= $item.product.name }}</p>
{{ /foreach }}

Ergebnis
Jede Position zeigt ihre Artikelnummer inklusive Werbemittelkennzeichen, sofern eines erfasst wurde. Andernfalls wird die reine Produktnummer angezeigt.

​

Werbemittelkennzeichen als eigenes Feld ausgeben

Wenn der reine Code zusätzlich als eigenes Feld erscheinen soll, prüfen Sie zuerst, ob die Funktion aktiv ist. Andernfalls erscheint bei ausgeschalteter Funktion nichts.

{{ if $wsConfig.inserts.enabled }}
  {{ foreach $item in $wsBasket.items }}
    {{ if $item.insert }}
      <p>Werbemittelcode: {{= $item.insert }}</p>
    {{ /if }}
  {{ /foreach }}
{{ /if }}

Ergebnis
Der Werbemittelcode erscheint nur bei aktiver Funktion und nur für Positionen, die einen Code tragen.

​

Werbemittelkennzeichen in der Direktbestellung erfassen

Auf der Direktbestellseite (Template modules/directOrder.htm, Modul $wsDirectOrder) geben Kunden Produktnummern zeilenweise ein. Standardmäßig ist dort kein Eingabefeld für das Werbemittelkennzeichen vorhanden, es muss pro Eingabezeile ergänzt werden.

Fügen Sie das folgende Feld in jede Eingabezeile des Formulars ein, und zwar neben dem bestehenden Feld name="id". Entscheidend ist der Feldname insert: Darüber liest der Shop den Code ein und löst ihn beim Übernehmen in den Warenkorb gegen die für das jeweilige Produkt gültigen Codes auf (siehe Wie der Shop ein Werbemittelkennzeichen ermittelt). Über {{ if $wsConfig.inserts.enabled }} erscheint das Feld nur, wenn die Funktion aktiv ist.

{{ if $wsConfig.inserts.enabled }}
<div class="col col-sm-auto">
  <div class="form-floating">
    <input type="text"
           name="insert"
           value="{{= $wsDirectOrder.items[$cDirectOrderProduct].insert | ifNull('') }}"
           class="form-control"
           id="directorder.insert.{{= $cDirectOrderProduct }}"
           placeholder="Werbemittelkennzeichen"
           aria-label="Werbemittelkennzeichen">
    <label aria-hidden="true" tabindex="-1" for="directorder.insert.{{= $cDirectOrderProduct }}">Werbemittelkennzeichen</label>
  </div>
</div>
{{ /if }}

Ergebnis
Pro Zeile erscheint neben der Produktnummer ein Eingabefeld für das Werbemittelkennzeichen. Der eingegebene Code wird zusammen mit der Zeile erfasst und beim Übernehmen in den Warenkorb wieder aufgelöst. Mit der Funktion $wsDirectOrder.items[…].insert wird der bereits erfasste Code nach einem Neuladen der Zeile wieder in das Feld geschrieben.

​

Bestellhistorie

Die Bestellhistorie arbeitet nicht mit dem Warenkorb, sondern mit den gespeicherten Bestelldaten ($order.orderList.item). Das fertig zusammengesetzte Feld itemNumberWithInsert steht dort nicht zur Verfügung, sodass die Anzeige im Template aus der Produktnummer, dem Code und den Werten aus $wsConfig.inserts (Position und Trennzeichen) selbst zusammengesetzt werden muss.

​

Weiterführende Links

• $wsConfig - Einstellungen über $wsConfig.inserts (aktiv, Trennzeichen, Position, Standardcode).
• $wsBasket - Ausgabe je Position über $item.insert und $item.itemNumberWithInsert.
• $wsViews - Erzeugung von View-URLs (url(), viewUrl()), an die sich der insert-Parameter anhängen lässt.
• content - Katalog - Konfigurationsblock content.inserts und die zwingende Feldzuordnung usedFields.products.
• API-Referenz Produkte - Pflege der zulässigen Codes je Produkt (custom.validInsertCodes); setzt die Feldzuordnung usedFields.products voraus (siehe Voraussetzungen).
• API-Referenz Konfiguration - Pflege des Konfigurationsblocks content.inserts über die Konfigurationsknoten-Endpunkte.
• Storefront-API Warenkorb - Setzen und Auslesen des Kennzeichens über das insert-Feld sowie GET /api/v1/config/inserts.