Developer Guidelines

ProDuck Javascript Integration

  • ProDuck kann dank einer öffentlich abrufbaren Javascript-Bibliothek in wenigen Schritten auf einer Website integriert werden.

    Einbinden des ProDuck-Javascript-SDK

  • Die Voraussetzung für alles Weitere ist das Hinzufügen des Verweises auf das ProDuck-SDK. Dieser muss auf jeder Website eingebunden sein, welche den ProDuck-Chat oder einen Expertenlink enthalten soll.
  •               
      <script type="application/javascript" src="https://www.produck.de/sdk/[VERSION]-producklib.min.js">
      </script>
                  
                
    Beispiel:
                  
      <script type="application/javascript" src="https://www.produck.de/sdk/20200224-producklib.min.js">
      </script>
                  
                
  • Um die konkrete Konfiguration einzelner Elemente vornehmen zu können, ist es nötig, Javascript-Code auf der Website einzubinden. Je nach Situation kann dies auf unterschiedliche Weise geschehen. Bei Seiten aus kompletter Eigenentwicklung ist dies gar kein Umstand, da beliebiger Code überall einfach eingefügt werden kann. Bei zum Beispiel einer Wordpress-Seite würde dies tiefere Kenntnisse des technischen Aufbaus von Wordpress voraussetzen. Ändert man hier interne Code-Templates ab, verliert man außerdem die Möglichkeit, Wordpress einfach zu aktualisieren. Es empfiehlt sich, entsprechende Plug-Ins einzusetzen, die es ermöglichen, Javascipt-Code in das Kopfelement einer Seite einzubinden.

ProDuck-Chat

  • Konfiguration des ProDuck-Chats

  • Die erste Möglichkeit, den ProDuck-Chat auf einer Website einzubinden, ist die direkte Variante. Nach Konfiguration und Konstruktion erscheint ein kleines Symbol rechts unten auf der Seite. Durch einen Klick darauf wird der Chat geöffnet.
  • Das erforderliche Konfigurationsobjekt akzeptiert folgende Parameter:
  • Name Datentyp Erforderlichkeit Standardwert
    cid integer erforderlich ---
    gid integer optional ---
    price number optional ---
    priceThreshold number optional 30.01
    product string optional ---
    link string bedingt erforderlich2 ---
    label string optional ---
    width integer optional 55
    bgcolor string optional #fff
    ftcolor string optional #5a5a5a
    pulse boolean optional false
    icon string optional URL des ProDuck Logos
    --- kein Standardwert definiert
    1 Der Wert des Parameters muss, wenn angegeben, größer sein als der Standardwert.
    2 siehe Beschreibung

  • Beschreibung der Parameter:

    • cid: Dies ist die Kundenidentifikationsnummer des ProDuck-Kundenkontos. Sie kann auf produck.de im Bereich „Profil“ eingesehen werden.
    • gid: Eine technische Identifikationsnummer für die Expertengruppe, welche für das Produkt eingesetzt werden soll. Diese Nummer wird von ProDuck zur Verfügung gestellt, sobald die Expertengruppe zusammengestellt und einsatzbereit ist. Die gid können Sie einfach weglassen, wenn Sie keine Expertengruppe gebucht haben und einen eigenen Kundenservice über ProDuck anbieten wollen.
    • price: Der Expertenlink wird nur eingebunden, wenn der Preis des auf der aktuellen Seite eingebundenen Produkts eine interne Grenze überschreitet. Dies ist für den Fall gedacht, dass ein Algorithmus die Detailseiten von Produkten auf einer Website erstellt. Die dürfte auch der Regelfall sein. Dieser Algorithmus ist dann auch dafür verantwortlich, die Konfiguration des Expertenlinks auf der jeweiligen Seite einzubinden und kann den Preis für das jeweilige Produkt hier setzen.
    • priceThreshold: Die zum Vergleich mit dem Parameter price herangezogene Preisgrenze kann durch die Angabe einer von Ihnen definierten ersetzt werden. Beachten Sie bitte, dass auf diese Weise lediglich eine Erhöhung möglich ist. Näheres zum Thema finden Sie in Abschnitt „Wozu dient die Preisegrenze?“.
    • product: Wird dieser Parameter gesetzt, so erhalten die Experten mit der Anfrage auch gleich die Information, welches Produkt das Thema des Chats werden wird. Es ist dringend empfohlen, diesen Wert immer sinnvoll zu setzen, da nicht davon ausgegangen werden kann, dass Kunden in Ihrer Frage immer einen sinnvollen Bezug herstellen.
    • link: Zusätzlich zum Produktnamen kann ein Link zur Detailseite des Produkts angegeben werden. Auch das Setzen dieses Wertes wird dringend empfohlen, um den Experten eine einfache und schnelle Orientierung zu ermöglichen. Wenn Sie für Ihren Chat ProDuck-Experten einsetzen, ist die Angabe des Links zur Produktseite bzw. zu der Seite, die das Thema des Chats vorgibt, erforderlich. So ist gewährleistet, dass sich der jeweilige Experte schnellstmöglich bezüglich des Kundenanliegens orientieren kann.
    • label: Das kleine Symbol zum Öffnen des Chats ist mit einem Label versehen. Der darauf angezeigte Text kann mit diesem Parameter festgelegt werden. Wir kein Label angegeben, wird auch kein Label-Element angezeigt, sodass nur das Icon angezeigt wird.
    • width: Hiermit kann die Breite des oben erwähnten Labels festgelegt werden, damit der gewählte Text vollumfänglich darauf passt.
    • bgcolor: Hiermit kann die Hintergrundfarbe des oben erwähnten Labels und im geöffneten Zustand die Hintergrundfarbe im Header des Chats definiert werden.
    • ftcolor: Hiermit kann die Schriftfarbe des oben erwähnten Labels und im geöffneten Zustand die Schriftfarbe im Header des Chats definiert werden.
    • pulse: Wenn der Blick des Benutzers zum Chat gelenkt werden soll, kann mit diesem Parameter festgelegt werden, dass das Chatsymbol zehn Sekunden nach dem Laden der Seite für zehn Sekunden durch eine pulsierende Animation auf sich aufmerksam macht.
    • icon: Das Chatsymbol kann frei gewählt werden. Hierfür ist einfach eine Zeichenkette anzugeben, die eine gültige URL zu einem Bild repräsentiert. Ohne die explizite Angabe einer URL wird das ProDuck-Logo verwendet.

  • Wozu dient die Preisgrenze?

    Unter der Voraussetzung, dass überhaupt die provisionsbasierte Anbindung an Expertenteams gewählt wurde, ist die Beratung für beispielsweise eine Schraube im Wert von 23 Cent nicht lohnenswert. Sinnvoll wird der ProDuck-Service eingesetzt bei Produkten, die einen relevanten Wert haben uns an sich beratungsintensiv sind. Um keine Kunden bei einer Beratung ins Leere laufen zu lassen, ist es empfehlenswert, bei sehr günstigen Produkten, den ProDuck-Expertenlink nicht zum Start einer Beratung anzubieten.
    Aktuell ist die Preisgrenze bei 30 € angesetzt. Die MonsTec GmbH behält sich jedoch vor, diese für ihren Service ProDuck anzupassen, wenn es sinnvoll erscheint.
  • Beispiele

    Minimale Konfiguration:
                  
    
                    <script  type="application/javascript">
                      window.onload = function() {
                        var chatConfig = {
                          'cid': 1751
                        };
    
                        produckLib.integrateChat(chatConfig);
                      }
                    </script>
                  
                
    Konfiguration unter Angabe aller Parameter:
                  
                    <script type="application/javascript">
                      window.onload = function() {
                        var chatConfig = {
                          'cid': 1751,
                          'gid': 27,
                          'price': myShop.getPrice(),
                          'priceThreshold': 50.0,
                          'product': 'Awesome Product',
                          'link': window.location.href,
                          'label': 'ProDuck Chat',
                          'width': 180,
                          'bgcolor': '#ededed',
                          'ftcolor': '#000000',
                          'pulse': false,
                          'icon': 'https://www.produck.de/assets/img/ducky.png'
                        };
    
                        produckLib.integrateChat(chatConfig);
                      }
                    </script>
                  
                
  • Konfiguration eines Expertenlinks

  • Eine andere Variante ist es, den ProDuck-Chat erst sichtbar werden zu lassen, wenn der Benutzer der Website auf einen bestimmten Link klickt. Ein solcher Link kann mithilfe des ProDuck-SDK einfach an einen bestimmten HTML-Container angehängt werden.
    Bei der Konfiguration eines Expertenlinks wird auch immer ein Chat-Konfigurationsobjekt benötigt (siehe oben).
  • Das erforderliche Konfigurationsobjekt akzeptiert folgende Parameter:
  • Name Datentyp Erforderlichkeit Standardwert
    linkElement string optional ---
    parent bedingt erforderlich1 optional ---
    linkText string optional Expertenrat einholen
    linkClass string optional produck-open-chat-link
    --- kein Standardwert definiert
    1 siehe Beschreibung

  • Beschreibung der Parameter:

    • linkElement: Wird mit diesem Parameter ein HTML-Element mit HTML-ID oder dem HTML-Namen angegeben so erstellt der Konfigurationsalgorithmus einen click-Handler für das Element. Somit wird dieses Element als derjenige „Link“ verwendet, welcher den ProDuck-Chat öffnet. HTML-Namen sind in der Regel nicht eindeutig. Wird ein solcher verwendet, so hängt das ProDuck-SDK den Link an das erste gefundene Element mit dem angegebenen Namen. You may add a listener for the event produckchatloaded to implement a loading indicator.
    • parent: Dies ist die HTML-ID oder auch der HTML-Name eines Elements, an das der Konfigurationsalgorithmus einen automatisch erstellten Link anhängt, wenn kein linkElement definiert wurde.
    • linkText: Der Parameter linkText bestimmt die Zeichenkette, die gegebenenfalls für die Visualisierung des automatisch erstellten Expertenlinks verwendet wird.
    • linkClass: Hiermit lässt sich eine CSS-Klasse an den Integrationsmechanismus übergeben, welche den CSS-Style des gegebenenfalls automatisch erstellten Expertenlinks bestimmt. Alternativ kann auch einfach die Standard-CSS-Klasse (produck-open-chat-link) in den Stylesheets der Website mit Eigenschaften versehen werden.
  • Beispiele:

    Minimale Konfiguration:
                  
                    <script  type="application/javascript">
                      window.onload = function() {
                        var linkConfig = {
                          'gid': 3453,
                          'parent': 'container'
                        };
    
                        var chatConfig = {
                          'cid': 1751
                        };
    
                        produckLib.createChatLink(linkConfig, chatConfig);
                      }
                    </script>
                  
                
    Konfiguration unter Angabe der meisten Parameter:
                  
                    <script type="application/javascript">
                      window.onload = function() {
                        var linkConfig = {
                          'parent': 'produckChatLinkContainer',
                          'linkText': 'Frag den Experten!',
                          'linkClass': 'style-me'
                        };
    
                        var chatConfig = {
                          'cid': 1751,
                          'gid': 27,
                          'price': myShop.getPrice(),
                          'priceThreshold': 50.0,
                          'product': 'Awesome Product',
                          'link': window.location.href,
                          'label': 'ProDuck Chat',
                          'width': 180,
                          'bgcolor': '#ededed',
                          'ftcolor': '#000000',
                          'pulse': false,
                          'icon': 'https://www.produck.de/assets/img/ducky.png'
                        };
    
                        produckLib.createChatLink(linkConfig, chatConfig);
                      }
                    </script>
                  
                

Die Übermittlung der Bestellung an ProDuck

  • Auf der Webseite, welche den erfolgreichen Abschluss eines Bestellung durch den Besucher auf der Website des Anbieters anzeigt, wird das Affiliate-Cookie verwendet, um die Übermittlung der Transaktion an das ProDuck-System auszulösen.
    Für das Anstoßen dieses Vorgangs ist der Anbieter verantwortlich. ProDuck bietet einen Webservice-Endpunkt an, an den die entsprechenden Daten übermittelt werden müssen.
  • Schnittstelle

    Die Schnittstelle ist folgendermaßen definiert:
  • URL: https://api.produck.de/billing/sale Methode: POST Content-Type: JSON Content:
                  
                    {
                      'acc': [integer],
                      'cht': [integer],
                      'lnk': [integer],
                      'lnd': [date],
                      'ref': [string],
                      'amt': [number],
                      'cur': [string]
                    }
                  
                

    Beschreibung der Eigenschaften des Content-Objekts:

    • acc: ProDuck-Kundennummer des Anbieters aus dem Profil auf ProDuck
    • cht: Chat-Identifikationsnummer aus dem Affiliate-Cookie
    • lnk: Link-Identifikationsnummer aus dem Affiliate-Cookie
    • lnd: Link-Datum im ISO-Format aus dem Affiliate-Cookie
    • ref: Eindeutiger Bezeichner des Anbieters für die Transaktion
    • amt: Gesamtbetrag der Produkte im Warenkorb des Besuchers der Seite des Anbieters
    • cur: ISO-Währungsbezeichner

  • Die Eigenschaft cht und das Paar aus lnk und lnd müssen dabei nicht zusammen vorhanden sein. Jedoch muss stets eine der beiden Angaben im Content-Objekt enthalten sein, also entweder cht allein oder lnk und lnd zusammen. Es kann aber auch vorkommen, dass alle drei Angaben sinnvoll sind, wenn zum Beispiel ein Besucher über einen Affiliate-Link auf die Website des Anbieters gelangt, dann aber auch noch einen Chat führt. Eine Provision wird in einem solchen Fall selbstverständlich nur einmal fällig.
  •               
                    {
                      'acc': 1751,
                      'cht': 534253,
                      'lnk': 23454523,
                      'lnd': '2020-01-01T12:34:56.789Z',
                      'ref': 'ORDER202012768',
                      'amt': 189.99,
                      'cur': 'EUR'
                    }