$wsOptIn - Opt-In-Prozesse - WEBSALE Dokumentation

Mit dem Modul $wsOptIn setzen Sie im Frontend Token-basierte Opt-In-Prozesse um. Typische Anwendungsfälle sind die Bestätigung einer E-Mail-Adresse, die Bestätigung einer Newsletter-Anmeldung oder das Zurücksetzen eines Passworts. Den Token selbst erzeugt die jeweilige Shop-Aktion. Das Modul hängt ihn im E-Mail-Template an den Bestätigungslink an und prüft auf der Bestätigungsseite, ob er noch gültig ist. In diesem Abschnitt wird zunächst der Ablauf eines Opt-In-Prozesses erklärt und anschließend werden alle Token-Namen aufgeführt, die Sie in Ihren E-Mail-Templates verwenden können. Danach folgen die Variablen und Methoden des Moduls im Detail.

Modulübersicht

Beispiel / Ausschnitt über $wsOptIn

{{= $wsOptIn | json }}

JSON-Ausgabe

{
  "current": {
    "valid": true,
    "token": "..."
  },
  "createTokenUrl": "ƒ()"
}

Anmerkung: ƒ() kennzeichnet eine Funktion. Variablen und Methoden in der Übersicht:

Variable	Typ	Beschreibung
`current`	map	Gibt eine Map mit Infos zum Token aus, der in der aktuellen URL übergeben wurde. Ohne Token ist der Wert `null`.
`valid`	bool	Gibt `true` aus, wenn der übergebene Token gültig ist und die zugehörige Aktion noch nicht ausgeführt wurde.
`token`	string	Gibt den übergebenen Token als Text aus.
`createTokenUrl()`	string	Hängt einen Token, den eine Aktion im selben Aufruf erzeugt hat, an eine URL an.

So funktioniert ein Opt-In-Link

Ein Opt-In-Prozess läuft immer in drei Schritten ab:

Aktion erzeugt den Token: Der Kunde löst eine Aktion aus, beispielsweise AccountRegister oder NewsletterSubscribe. Die Aktion erzeugt einen Token, speichert ihn unter einem festen Token-Namen und versendet die zugehörige E-Mail.
E-Mail-Template erzeugt den Link: Im E-Mail-Template rufen Sie $wsOptIn.createTokenUrl() mit der URL der Bestätigungsseite und genau diesem Token-Namen auf. Die Methode hängt den Token an die URL an.
Bestätigungsseite führt die Aktion aus: Klickt der Kunde auf den Link, prüft die Bestätigungsseite mit $wsOptIn.current.valid, ob der Token gültig ist. Anschließend führt der Kunde die bestätigende Aktion aus, beispielsweise EmailVerify oder NewsletterSubscribeConfirm.

Jeder Token gilt nur für die eine bestätigende Aktion, für die er erzeugt wurde, und kann nur einmal verwendet werden. Standardmäßig ist ein Token vier Stunden gültig. Für die Token AcceptInvitation und passwordReset gilt die Gültigkeitsdauer des Einladungslinks aus b2b.userInvitation, mindestens aber vier Stunden.

Der Token-Name im E-Mail-Template muss exakt dem Namen entsprechen, unter dem die Aktion den Token erzeugt hat. Dabei wird die Groß- und Kleinschreibung berücksichtigt. Wenn der Name nicht stimmt, gibt createTokenUrl() die URL ohne Token zurück. Der Link in der E-Mail funktioniert dann nicht, ohne dass eine Fehlermeldung erscheint.

Token-Namen

Die folgenden Tabellen zeigen, welcher Token-Name in welcher E-Mail verwendet wird. In der Spalte E-Mail ist die Konfiguration angegeben, in der das Template der E-Mail hinterlegt ist. In der Spalte Bestätigende Aktion ist die Aktion aufgeführt, die der Kunde mit dem Token auf der Bestätigungsseite ausführt.

Token aus Shop-Aktionen

Token-Name	Ausgelöst durch	E-Mail	Bestätigende Aktion
`verifyEmail`	`AccountRegister`, `GuestRegister`, Abschluss einer Kontoaktivierung, Abschluss einer Änderung der E-Mail-Adresse	`actions.accountRegister` → `verifyEmail` `actions.guestRegister` → `verifyEmail` `actions.accountActivateConfirm` → `verifyEmail` `actions.emailUpdate` → `verifyEmail`	`EmailVerify`
`accountActivateOptIn`	`AccountActivate`, wenn für die Kontoaktivierung ein Opt-In vorgesehen ist	`actions.accountActivate` → `optInEmail`	`AccountActivateOptIn`
`accountDeleteOptIn`	`AccountDelete`, wenn die Double-Opt-In-E-Mail aktiviert ist	`actions.accountDelete` → `doubleOptInEmail`	`AccountDeleteOptIn`
`emailUpdateOptIn`	`EmailUpdate`, wenn die Double-Opt-In-E-Mail aktiviert ist	`actions.emailUpdate` → `doubleOptInEmail`	`EmailUpdateOptIn`
`passwordReset`	`PasswordForgotten` für Kundenkonten und Mitarbeiterkonten, `TriggerMemberPasswordReset`	`actions.passwordForgotten` → `email`	`ResetPassword`
`ResetPassword`	`SubAccountCreate` (Einladung eines neuen Mitarbeiterkontos)	`b2b.subAccounts` → `email`	`ResetPassword`
`unlockLogin`	Sperre des Logins nach zu vielen fehlgeschlagenen Anmeldeversuchen mit `Login`	`accounts.account` → `login` → `loginBlockEmail`	`UnlockLogin`
`confirmSubscribeNewsletter`	`NewsletterSubscribe`	`newsletter.newsletter` → `doubleOptInEmailSubscribe`	`NewsletterSubscribeConfirm`
`confirmUnsubscribeNewsletter`	`NewsletterUnsubscribe`, wenn `unsubscribeSelfDoubleOptIn` aktiv ist	`newsletter.newsletter` → `doubleOptInEmailUnsubscribe`	`NewsletterUnsubscribeConfirm`
`confirmBlacklistAdd`	`BlacklistAdd`, wenn `blacklistSelfDoubleOptIn` aktiv ist	`newsletter.newsletter` → `doubleOptInEmailBlacklist`	`BlacklistAddConfirm`

Eine Kontoaktivierung ist abgeschlossen, wenn AccountActivate das Konto ohne Opt-In sofort aktiviert oder wenn der Kunde den Opt-In-Link mit AccountActivateOptIn bestätigt. Eine Änderung der E-Mail-Adresse ist abgeschlossen, wenn EmailUpdate die Adresse ohne Double-Opt-In sofort ändert oder wenn der Kunde die Änderung mit EmailUpdateOptIn bestätigt. In beiden Fällen versendet der Shop danach die E-Mail mit dem Token verifyEmail.

Token aus der Admin Interface API

Einige Endpunkte der Admin-Interface-API versenden ebenfalls E-Mails mit Opt-In-Links. Das gilt auch, wenn Sie die Funktion im Admin-Interface auslösen, beispielsweise wenn Sie einen Kunden einladen.

Token-Name	Ausgelöst durch	E-Mail	Bestätigende Aktion
`AcceptInvitation`	`POST customerAccounts/{accountId}/activate`	`b2b.userInvitation` → `email`	`AcceptInvitation`
`passwordReset`	`POST customerAccounts/{accountId}/passwordReset`	`actions.passwordForgotten` → `email`	`ResetPassword`
`confirmSubscribeNewsletter`	`POST newsletter/subscriber` `PUT newsletter/subscriber/{id}`, nur wenn sich die E-Mail-Adresse ändert `POST import/newsletterSubscriber/start`, nur für neue Abonnenten und nur wenn `importSubscribeDoubleOptIn` aktiv ist	`newsletter.newsletter` → `doubleOptInEmailSubscribe`	`NewsletterSubscribeConfirm`

Bei einer Änderung der E-Mail-Adresse über die Methode PUT newsletter/subscriber/{id} enthält der Token confirmSubscribeNewsletter zusätzlich die ID des bestehenden Abonnenten. NewsletterSubscribeConfirm überträgt die bestätigte Adresse dann auf diesen Abonnenten, statt einen neuen anzulegen. Das E-Mail-Template und der Token-Name bleiben unverändert. Weitere Informationen finden Sie unter NewsletterSubscribeConfirm. Die Erinnerungs-E-Mail zu offenen Einladungen (b2b.userInvitation → reminderEmail) erzeugt keinen Token. createTokenUrl() gibt in ihrem Template deshalb nur die URL ohne Token zurück.

Für das Zurücksetzen eines Passworts gibt es zwei Token-Namen. Die E-Mail aus actions.passwordForgotten verwendet passwordReset, die Einladung eines neuen Mitarbeiterkontos aus b2b.subAccounts verwendet ResetPassword. Beide Token führen zur Aktion ResetPassword. Achten Sie deshalb in beiden E-Mail-Vorlagen darauf, den passenden Namen zu verwenden.

Templates

Das Modul $wsOptIn wird an zwei Stellen verwendet. In den E-Mail-Templates erzeugt die Funktion createTokenUrl() den Bestätigungslink. Auf den Bestätigungsseiten, beispielsweise für das Zurücksetzen des Passworts oder die Bestätigung einer neuen E-Mail-Adresse, prüft $wsOptIn.current den übergebenen Token.

Variablen

$wsOptIn.current

Enthält Informationen zum Token, der in der aktuellen URL übergeben wurde. Ist null, wenn kein Token in der URL vorhanden ist.

{{ if $wsOptIn.current }}
    // Token wurde übergeben
{{ /if }}

$wsOptIn.current.valid

Gibt true aus, wenn der übergebene Token gültig ist und die zugehörige Aktion mit diesem Token noch nicht ausgeführt wurde. Ist der Token abgelaufen, unbekannt oder bereits verwendet, gibt die Variable false aus.

{{ if $wsOptIn.current.valid }}
    // Token ist gültig
{{ else }}
    // Token ist ungültig oder abgelaufen
{{ /if }}

$wsOptIn.current.token

Gibt den übergebenen Token aus.

Token: {{= $wsOptIn.current.token }}

Methoden

$wsOptIn.createTokenUrl()

Es wird ein Opt-In-Token an eine URL angehängt. Die Methode erzeugt selbst keinen Token. Sie verwendet den Token, den eine Aktion im selben Aufruf unter dem angegebenen Token-Namen erzeugt hat. Verwenden Sie die Methode deshalb in dem E-Mail-Template, das diese Aktion versendet. Welche Aktion welchen Token-Namen verwendet, ist unter Token-Namen aufgeführt. Signatur
$wsOptIn.createTokenUrl(url, tokenName) Rückgabe
string - URL mit angehängtem Token.

Wurde im aktuellen Aufruf kein Token mit dem angegebenen Namen erzeugt, gibt die Methode die URL unverändert zurück.
Ist url oder tokenName kein Text, gibt die Methode null zurück.

Parameter

Name	Typ	Pflicht	Beschreibung
`url`	string	ja	URL der Bestätigungsseite, an die der Token angehängt wird. In E-Mails verwenden Sie eine absolute URL.
`tokenName`	string	ja	Name des Tokens, beispielsweise `"verifyEmail"`. Groß- und Kleinschreibung werden unterschieden.

Beispiel, das im E-Mail-Template zur Verifizierung der E-Mail-Adresse einen Link mit Token erzeugt.

{{= $wsOptIn.createTokenUrl($wsViews.viewUrl('account/emailVerify.htm', {}, 'absolute'), 'verifyEmail') }}

Aktionen

Für $wsOptIn stehen keine eigenen Aktionen zur Verfügung. Die Aktionen zum Erzeugen oder Bestätigen von Opt-In-Token finden Sie unter Account und Newsletter.

Beispiele für den Datenzugriff

Bestätigung der E-Mail-Adresse per Opt-In-Link

Nach der Erstellung eines Kundenkontos erzeugt die Aktion AccountRegister den Token verifyEmail und versendet eine E-Mail zur Bestätigung der E-Mail-Adresse. Den Bestätigungslink erzeugen Sie im Template dieser E-Mail beispielsweise so:

<a href="{{= $wsOptIn.createTokenUrl($wsViews.viewUrl('account/emailVerify.htm', {}, 'absolute'), 'verifyEmail') }}">
  E-Mail-Adresse bestätigen
</a>

Der Bestätigungslink enthält einen Token, der sicherstellt, dass nur der Empfänger die Bestätigung durchführen kann.

https://www.beispielshop.de/account/emailVerify.htm?token=abc123xyz

Wenn der Kunde auf den Link klickt und die Bestätigungsseite (emailVerify.htm) geöffnet wird, prüft diese, ob der Token gültig ist. Falls ja, kann der Kunde die Verifizierung per Klick auf einen Button abschließen, wodurch die Aktion EmailVerify ausgeführt wird.

{{ if $wsOptIn.current }}
    {{ if $wsOptIn.current.valid }}
      Button zum Bestätigen
    {{ else }}
      Dieser Link ist nicht länger gültig.
    {{ /if }}
{{ else }}
    Ungültiger Zugriff auf die Bestätigungsseite.
{{ /if }}

WEBSALE

Frontend

Die Basics

Getting Started

Referenz – Aktionen

Referenz – Sprache

Referenz – Module

Integrationsanleitung

Praxisbeispiele

$wsOptIn - Opt-In-Prozesse

Modulübersicht

So funktioniert ein Opt-In-Link

Token-Namen

Token aus Shop-Aktionen

Token aus der Admin Interface API

Templates

Variablen

$wsOptIn.current

$wsOptIn.current.valid

$wsOptIn.current.token

Methoden

$wsOptIn.createTokenUrl()

Aktionen

Beispiele für den Datenzugriff

Bestätigung der E-Mail-Adresse per Opt-In-Link

Weiterführende Links

​Modulübersicht

​So funktioniert ein Opt-In-Link

​Token-Namen

​Token aus Shop-Aktionen

​Token aus der Admin Interface API

​Templates

​Variablen

​$wsOptIn.current

​$wsOptIn.current.valid

​$wsOptIn.current.token

​Methoden

​$wsOptIn.createTokenUrl()

​Aktionen

​Beispiele für den Datenzugriff

​Bestätigung der E-Mail-Adresse per Opt-In-Link

​Weiterführende Links

Modulübersicht

So funktioniert ein Opt-In-Link

Token-Namen

Token aus Shop-Aktionen

Token aus der Admin Interface API

Templates

Variablen

$wsOptIn.current

$wsOptIn.current.valid

$wsOptIn.current.token

Methoden

$wsOptIn.createTokenUrl()

Aktionen

Beispiele für den Datenzugriff

Bestätigung der E-Mail-Adresse per Opt-In-Link

Weiterführende Links