Voice Commerce

Einleitung

Amazon Pay bietet Ihnen die Möglichkeit kostenlos und ohne Entwicklungskenntnisse einen Alexa Skill mit Commerce Funktionalität zu erstellen. Der Skill bietet Ihren Kunden u.a. die Möglichkeit, sich über den aktuellen Bestellstatus zu informieren, einen Preisalarm einzurichten, Angebote zu finden oder die eigene Wunschliste zu befüllen.

Installation / Updates

Wichtig

Um den Commerce Skill mit allen Funktionalitäten nutzen zu können, muss Amazon Pay in Ihrem Shop aktiviert sein.

Systemvoraussetzungen

  • JTL-Shop ab Version 4.05
  • PHP-Version 5.6 oder höher
  • von "außen" erreichbarer JTL-Shop (falls Ihr Shop hinter einem .htaccess-Schutz liegt, kann die Skill-Anlage nicht abgeschlossen werden)
  • Testkonto im Shop, mit dem Amazon die Funktionalität vor der Freigabe des Skills prüfen kann
  • Installiertes und aktives Amazon Pay-Plugin

Installationsvorgang

(alternativ siehe auch https://guide.jtl-software.de/Plugins_f%C3%BCr_JTL-Shop_verwalten#Kurzanleitung_Plugin-Installation)

  1. Laden Sie nach dem Entpacken den Plugin-Ordner s360_amazon_voicecommerce per FTP in das Shop-Verzeichnis /includes/plugins hoch, sodass Sie die info.xml des Plugins dann im Pfad /includes/plugins/s360_amazon_voicecommerce/info.xml sehen.
    Achten Sie beim Upload per FTP darauf, dass Ihr FTP-Client die Daten im binären Modus überträgt.
  2. In der Plugin-Verwaltung sollte das Plugin nun im Tab "Verfügbar" auftauchen. Markieren Sie den Haken vor dem Plugin und klicken Sie auf "Installieren".

Updatevorgang

(alternativ siehe auch https://guide.jtl-software.de/Plugins_f%C3%BCr_JTL-Shop_verwalten#Plugins_aktualisieren)

  1. Laden Sie - wie bei der Installation - nach dem Entpacken den Plugin-Ordner s360_amazon_voicecommerce per FTP in das Shop-Verzeichnis /includes/plugins hoch, sodass Sie die info.xml des Plugins dann im Pfad /includes/plugins/s360_amazon_voicecommerce/info.xml sehen.
    Achten Sie beim Upload per FTP darauf, dass Ihr FTP-Client die Daten im binären Modus überträgt.
  2. In der Plugin-Verwaltung sollte das Plugin nun im Tab "Aktiviert" mit einem Update-Hinweis versehen sein. Betätigen Sie den Update-Button, um das Update zu vervollständigen.
  3. Danach sollten Sie wie im Bereich Konfiguration beschrieben, den Skill aktualisieren und erneut veröffentlichen.

Konfiguration

Zur Erstellung eines Alexa Skills mit Commerce Funktionalität wird ein Amazon Entwickler-Konto benötigt. Bitte loggen Sie sich mit Ihrem Entwickler-Konto via “Login mit Amazon” ein. Sollten Sie noch keines besitzen können Sie auf die gleiche Weise ein bestehendes Amazon-Konto zum Entwickler-Konto machen oder ein neues Konto erstellen.

Die angeforderten Berechtigungen sind zur automatisierten Erstellung des Skills notwendig, bitte akzeptieren Sie diese, um fortzufahren.

Wenn Sie das Plugin-Backend aufrufen, sehen Sie zunächst nur einen Hinweistext und einen Login-mit-Amazon-Button. Sie müssen sich via Amazon in Ihr Entwickler-Konto einloggen, damit das Plugin weiß, in welchem Konto es den Skill für Ihren Shop anlegen soll.

Nach dem Login werden Sie ggf. gefragt, ob und welchen bereits in Ihrem Konto vorhandenen Skill Sie editieren wollen. Diese Abfrage erfolgt nur, wenn Sie bereits einen Skill in Ihrem Entwicklerkonto haben und das Plugin sich nicht sicher ist, dass es sich um den von ihm selbst erstellten/bearbeiteten Skill handelt.

Danach können Sie die eigentliche Skill-Konfiguration durchführen.

Skill-ID

Dieser Wert wird vom Plugin automatisch gesetzt, wenn der Skill erfolgreich angelegt worden ist oder mit einem existierenden Skill auf Ihrem Entwicklerkonto verknüpft wurde.

Vendor-ID

Hier muss Ihre sogenannte Vendor-ID stehen. Sie können dem Link unter dem Eingabefeld folgen, um sich Ihre Vendor-ID im Entwickler-Konto anzeigen zu lassen. Ggf. müssen Sie sich erst ins Konto einloggen und den Link dann nochmal anklicken.

Skill-Name

Tragen Sie hier den Namen Ihres Skills ein. Das ist der Name, den der Skill im Alexa App-Store haben wird.

Aufruf-Name

Hier definieren Sie den Aufrufnamen Ihres Skills. Das ist der Name, mit dem der Skill vom Kunden aktiviert werden kann, wenn er den Skill installiert hat und mit Alexa spricht.

Halten Sie sich bitte strikt an die Vorgaben zur Erstellung des Aufrufnamens, da es sonst passieren kann, dass die Skill-Veröffentlichung nicht erfolgreich ist.

Insbesondere:

  • Verwenden Sie nur Kleinbuchstaben und Leerzeichen
  • Ziffern bzw. Zahlen müssen Sie ausschreiben (also "eins" statt "1")
  • Bestimmte Alexa-Kontroll-Wörter sind im Aufrufnamen des Skills nicht erlaubt (z.B. starte, öffne)
  • Der Aufrufname darf nur unter bestimmten Umständen aus einem einzigen Wort bestehen (bitte ziehen Sie die verlinkte Dokumentation unterhalb des Eingabefeldes zu Rate)

Kurzbeschreibung

Hier können Sie einen kurzen Satz angeben, der den Skill beschreibt.

Keywords

Hier können Sie Suchbegriffe komma-separiert eingeben, mit denen der Kunde Ihren Skill im Alexa App-Store finden können soll. Beachten Sie die maximal erlaubte Anzahl.

Datenschutz-URL

Stellen Sie hier den absoluten Link (inkl. https://) zu Ihrer Datenschutz-URL ein. Das Plugin versucht, diese URL bereits vorauszufüllen.

AGB-URL

Stellen Sie hier den absoluten Link (inkl. https://) zu Ihrer AGB-URL ein. Das Plugin versucht, diese URL bereits vorauszufüllen.

SSL-Zertifikat-Typ

Wählen Sie hier aus, welchen Typ SSL-Zertifikat Sie im Shop konfiguriert haben. Ein Wildcard-Zertifikat haben Sie, wenn es auf *.ihredomain.de ausgestellt wurde. Ansonsten haben Sie ein Domain-spezifisches Zertifikat.

Das Plugin versucht, den Typ automatisch zu erkennen, dieser Vorgang ist aber nicht 100%ig präzise.

Im Zweifelsfall fragen Sie einfach Ihren Hoster.

Checkbox: Export-Compliance

Bitte lesen Sie die Erklärung zur Export-Compliance (wird Ihnen angezeigt, wenn Sie auf "Export Compliance" klicken) aufmerksam durch und bestätigen Sie diese, wenn Sie zustimmen.

Skill-Icons

Wählen Sie hier zwei Icons für die Darstellung des Skills in Alexa aus. Sie benötigen ein kleines und ein großes Icon.

Bitte beachten Sie, dass die vorgebenen Formate bezüglich Dateityp und Abmessungen exakt eingehalten werden müssen!

Sie können sich bei Bedarf auch einfach über das verlinkte Tool von Amazon die passenden Icons bauen und herunterladen.

Testdaten

Geben Sie hier E-Mail und Passwort für ein Testkonto in Ihrem Shop ein, welches Amazon nutzen kann, um die Funktionalität des Skills zu verifizieren. Falls Sie noch kein entsprechendes Konto haben, legen Sie bitte eines an.

Ohne dieses Testkonto kann Ihr Skill nicht veröffentlicht werden.

Im Shop Speichern

Wenn Sie alle Einstellungen konfiguriert haben, können Sie die Einstellungen lokal im Shop speichern.
Diese Funktion speichert die aktuellen Einstellungen in der Plugin-Datenbanktabelle und kommuniziert noch nicht mit Amazon.

Skill anlegen/aktualisieren

Um Inkonsistenzen zu vermeiden, müssen Sie Änderungen an der Skill-Konfiguration immer erst "Im Shop Speichern", bevor Sie den Skill anlegen oder aktualisieren können.

Nachdem Sie die Konfiguration im Shop gespeichert haben, können Sie den Skill anlegen (bzw. aktualisieren, wenn er bereits erfolgreich angelegt wurde).

Betätigen Sie dazu den entsprechenden Button.

Technischer Ablauf

  1. Das Plugin prüft zunächst intern sämtliche Eingaben auf Validität.
  2. Wenn alles ok ist, sendet das Plugin zunächst das Skill-Manifest an Amazon und wartet auf die Antwort, ob dieses ok ist. Handelt es sich um eine Skill-Anlage, übernimmt das Plugin dann die Skill-ID, die Amazon erzeugt hat.
    Wenn dieser Schritt erfolgreich ist (Skill-Manifest-Status ist dann grün), taucht der Skill auch in Ihrem Entwickler-Konto auf.
  3. Das Plugin sendet das Interaction-Model und die Account-Linking-Daten an Amazon.
  4. Es kann eine Weile dauern, bis das Interaction-Model und die Account-Linking-Daten von Amazon verifiziert sind. Laden Sie das Plugin-Backend ggf. mit F5 neu, bis der Status (unten angezeigt) eindeutig ist.

Vorgehen bei Fehlern

Falls Ihre Konfiguration invalide Werte enthält, oder Amazon einen Fehler zurückwirft, wird Ihnen dies in einem Popup angezeigt, sowie, wenn von Amazon der Fehler kommt, wird Ihnen auch am Status von Skill-Manifest/Interaction-Model/Account-Linking der Fehler gezeigt.

Bitte lesen Sie aufmerksam die Fehlermeldung und beheben Sie diesen.

Skill Veröffentlichen

Wenn die Skill-Anlage erfolgreich war, existiert Ihr Skill vollständig in Alexa - ist aber noch nicht über den Alexa App-Store zu finden.

Hierzu muss Ihr Skill veröffentlicht werden.

Betätigen Sie den entsprechenden Button im Plugin-Backend, um Ihren Skill zur Veröffentlichung freizugeben.

Daraufhin wird Ihr Skill eingehend auf Korrektheit geprüft. Da diese Prüfung manuell erfolgt, dauert dieser Vorgang eine Weile. Solange Ihr Skill in Prüfung ist, können Sie diesen auch jederzeit von der Veröffentlich zurückziehen. Sollten Probleme bei der Veröffentlichung auftauchen, werden Sie von Amazon per E-Mail benachrichtigt.

Skill löschen

Sie können einen angelegten Skill über diesen Button wieder komplett löschen. Achtung: Der Skill wird dann permanent, auch in Ihrem Entwickler-Konto, gelöscht!

Bedienung

Die Bedienung des Skills erfolgt über Alexa.

Nachdem der Skill mit "Starte <Aufrufname>" gestartet wurde, können Sie sich mit "Hilfe" weitere Informationen zur Bedienung erläutern lassen.

FAQ

Fehlermeldung: "Skill-Anlage ist mit HTTP Code 401 fehlgeschlagen."

Bitte prüfen Sie, ob Ihr verwendeter Amazon-Account vollständig die Konfiguration als Developer-Account durchlaufen hat. Prüfen Sie bitte außerdem, ob die konfigurierte Vendor-ID/Händlernummer mit der ID übereinstimmt, die Sie im Backend des Amazon-Developer-Accounts sehen. (Den Link zu der Anzeige finden Sie im Plugin-Backend bei der Vendor-ID.)

Wo kann ich den Skill gegenprüfen?

Wenn Sie sich auf developer.amazon.com anmelden, finden Sie im Bereich Alexa bei Ihren Skills den vom Plugin erzeugten Skill. Hier können Sie - falls notwendig - manuell eingreifen. Beachten Sie jedoch, dass das Plugin beim Aktualisieren des Skills manuell gemachte Einstellungen ggf. überschreibt.

Begriffsklärungen

Skill-Manifest

Das Skill-Manifest ist ein Teil der Skill-Konfiguration, welche an Amazon übermittelt wird. Hier sind die meisten Konfigurationen, die Sie einstellen können, enthalten.

Interaction-Model

Das Interaction-Model ist ein Teil der Skill-Konfiguration, welche an Amazon übermittelt wird. Das Modell beschreibt die sprachliche Interaktion des Kunden mit dem Skill. Hier ist auch der Aufrufname des Skills enthalten.

Account-Linking

Das Account-Linking ist ein Teil der Skill-Konfiguration, welche an Amazon übermittelt wird. Das Account-Linking wird für die Verknüpfung des Alexa-Konto des Kunden mit Ihrem Shop benötigt.

Changelog

v1.07

  • Installationshinweis: Ein Update des Plugins genügt, der Skill muss nicht gegen Amazon aktualisiert werden.
  • Verbesserung: Alexa erlaubt "und" im Invocation Name, wenn es in Zahlen enthalten ist (z.B. vier und zwanzig)
  • Techn. Anpassung: Die Testing-Instructions für die Zertifizierung wurden angepasst

v1.06

  • Installationshinweis: Ein Update des Plugins genügt, der Skill muss nicht gegen Amazon aktualisiert werden.
  • Verbesserung: Zusätzliche Hinweise zur Möglichkeit des Kaufabschlusses in Sprachvariablen hinzugefügt.
    (Dies hilft der erfolgreichen Zertifizierung Ihres Skills. Die Sprachvariablen werden beim Update normalerweise automatisch aktualisiert. Sollte das nicht automatisch funktionieren, setzen Sie bitte die Sprachvariable lpa_alexa_helpwelcome auf den Installationsstand zurück.)

v1.05

  • Installationshinweis: Ein Update des Plugins genügt, der Skill muss nicht gegen Amazon aktualisiert werden.
  • Bugfix: OAuth gibt u.U. Debugmeldung aus, die den weiteren Verlauf des Accountmappings behindert
  • Verbesserung: Erklärungen im Admin-Backend zur korrekten Auswahl des Aufruf-Namens wurden angepasst / verbessert.

v1.04

  • Installationshinweis: Ein Update auf diese Version erfordert eine Aktualisierung des Skills gegen Amazon!
  • Bugfix: Hinweis auf Benachrichtigungen aus der Default-Antwort für Hilfe entfernt.
  • Verbesserung: Hinweis zum potentiellen Account-Linking in die Skill-Langbeschreibung aufgenommen.

v1.03

  • Installationshinweis: Ein Update des Plugins genügt, der Skill muss nicht gegen Amazon aktualisiert werden.
  • Bugfix: Alexa SSML versteht nicht alle HTML-Maskierungen

v1.02

  • Installationshinweis: Ein Update des Plugins genügt, der Skill muss nicht gegen Amazon aktualisiert werden.
  • Bugfix: Merklistenfunktion wird - nur scheinbar - aufgerufen, obwohl kein Account Linking vorhanden ist.
  • Verbesserung: Skill teilt Endnutzer den Namen der Merkliste mit, auf der ein Artikel hinzugefügt wurde.
  • Verbesserung: Besserer Umgang mit HTML-Zeichen in Artikelnamen bzgl. SSML-Kompatibilität.

v1.01

  • Installationshinweis: Ein Update auf diese Version erfordert eine Aktualisierung des Skills gegen Amazon!
  • Fix für nicht unterstützten Interface-Typ

v1.00

  • Initiales Plugin-Release



Kontakt / Support

siehe Support und Kontakt