$wsOptIn - Opt-in processes - WEBSALE Dokumentation

With the $wsOptIn module, you implement token-based opt-in processes in the frontend. Typical use cases are confirming an email address, confirming a newsletter subscription, or resetting a password. The token itself is generated by the respective shop action. In the email template, the module appends it to the confirmation link, and on the confirmation page it checks whether the token is still valid. This section first explains how an opt-in process works and then lists all token names you can use in your email templates. After that, the module’s variables and methods are described in detail.

Module overview

Example / excerpt of $wsOptIn

{{= $wsOptIn | json }}

JSON output

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

Note: ƒ() denotes a function. Variables and methods overview:

Variable	Type	Description
`current`	map	Returns a map with info about the token passed in the current URL. Without a token, the value is `null`.
`valid`	bool	Returns `true` if the passed token is valid and the associated action has not yet been performed.
`token`	string	Returns the passed token as text.
`createTokenUrl()`	string	Appends a token generated by an action in the same call to a URL.

How an opt-in link works

An opt-in process always runs in three steps:

The action generates the token: The customer triggers an action, for example AccountRegister or NewsletterSubscribe. The action generates a token, stores it under a fixed token name and sends the associated email.
The email template generates the link: In the email template, you call $wsOptIn.createTokenUrl() with the URL of the confirmation page and exactly this token name. The method appends the token to the URL.
The confirmation page performs the action: When the customer clicks the link, the confirmation page uses $wsOptIn.current.valid to check whether the token is valid. The customer then performs the confirming action, for example EmailVerify or NewsletterSubscribeConfirm.

Each token applies only to the one confirming action for which it was generated and can only be used once. By default, a token is valid for four hours. For the tokens AcceptInvitation and passwordReset, the validity period of the invitation link from b2b.userInvitation applies, but at least four hours.

The token name in the email template must exactly match the name under which the action generated the token. The name is case-sensitive. If the name does not match, createTokenUrl() returns the URL without a token. The link in the email then does not work, and no error message is shown.

Token names

The following tables show which token name is used in which email. The Email column specifies the configuration in which the email template is stored. The Confirming action column lists the action the customer performs with the token on the confirmation page.

Tokens from shop actions

Token name	Triggered by	Email	Confirming action
`verifyEmail`	`AccountRegister`, `GuestRegister`, completion of an account activation, completion of an email address change	`actions.accountRegister` → `verifyEmail` `actions.guestRegister` → `verifyEmail` `actions.accountActivateConfirm` → `verifyEmail` `actions.emailUpdate` → `verifyEmail`	`EmailVerify`
`accountActivateOptIn`	`AccountActivate`, if an opt-in is intended for the account activation	`actions.accountActivate` → `optInEmail`	`AccountActivateOptIn`
`accountDeleteOptIn`	`AccountDelete`, if the double opt-in email is enabled	`actions.accountDelete` → `doubleOptInEmail`	`AccountDeleteOptIn`
`emailUpdateOptIn`	`EmailUpdate`, if the double opt-in email is enabled	`actions.emailUpdate` → `doubleOptInEmail`	`EmailUpdateOptIn`
`passwordReset`	`PasswordForgotten` for customer accounts and employee accounts, `TriggerMemberPasswordReset`	`actions.passwordForgotten` → `email`	`ResetPassword`
`ResetPassword`	`SubAccountCreate` (invitation of a new employee account)	`b2b.subAccounts` → `email`	`ResetPassword`
`unlockLogin`	Login lock after too many failed sign-in attempts with `Login`	`accounts.account` → `login` → `loginBlockEmail`	`UnlockLogin`
`confirmSubscribeNewsletter`	`NewsletterSubscribe`	`newsletter.newsletter` → `doubleOptInEmailSubscribe`	`NewsletterSubscribeConfirm`
`confirmUnsubscribeNewsletter`	`NewsletterUnsubscribe`, if `unsubscribeSelfDoubleOptIn` is active	`newsletter.newsletter` → `doubleOptInEmailUnsubscribe`	`NewsletterUnsubscribeConfirm`
`confirmBlacklistAdd`	`BlacklistAdd`, if `blacklistSelfDoubleOptIn` is active	`newsletter.newsletter` → `doubleOptInEmailBlacklist`	`BlacklistAddConfirm`

An account activation is complete when AccountActivate activates the account immediately without opt-in or when the customer confirms the opt-in link with AccountActivateOptIn. An email address change is complete when EmailUpdate changes the address immediately without double opt-in or when the customer confirms the change with EmailUpdateOptIn. In both cases, the shop then sends the email with the verifyEmail token.

Tokens from the Admin Interface API

Some endpoints of the Admin Interface API also send emails with opt-in links. This also applies if you trigger the function in the Admin Interface, for example when you invite a customer.

Token name	Triggered by	Email	Confirming action
`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}`, only if the email address changes `POST import/newsletterSubscriber/start`, only for new subscribers and only if `importSubscribeDoubleOptIn` is active	`newsletter.newsletter` → `doubleOptInEmailSubscribe`	`NewsletterSubscribeConfirm`

When the email address is changed via the PUT newsletter/subscriber/{id} method, the confirmSubscribeNewsletter token additionally contains the ID of the existing subscriber. NewsletterSubscribeConfirm then transfers the confirmed address to this subscriber instead of creating a new one. The email template and the token name remain unchanged. For more information, see NewsletterSubscribeConfirm. The reminder email for open invitations (b2b.userInvitation → reminderEmail) does not generate a token. In its template, createTokenUrl() therefore only returns the URL without a token.

There are two token names for resetting a password. The email from actions.passwordForgotten uses passwordReset, while the invitation of a new employee account from b2b.subAccounts uses ResetPassword. Both tokens lead to the ResetPassword action. Therefore, make sure to use the correct name in both email templates.

Templates

The $wsOptIn module is used in two places. In the email templates, the createTokenUrl() function generates the confirmation link. On the confirmation pages, for example for resetting the password or confirming a new email address, $wsOptIn.current checks the passed token.

Variables

$wsOptIn.current

Contains information about the token passed in the current URL. Is null if no token is present in the URL.

{{ if $wsOptIn.current }}
    // Token was passed
{{ /if }}

$wsOptIn.current.valid

Returns true if the passed token is valid and the associated action has not yet been performed with this token. If the token is expired, unknown or already used, the variable returns false.

{{ if $wsOptIn.current.valid }}
    // Token is valid
{{ else }}
    // Token is invalid or expired
{{ /if }}

$wsOptIn.current.token

Returns the passed token.

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

Methods

$wsOptIn.createTokenUrl()

Appends an opt-in token to a URL. The method does not generate a token itself. It uses the token that an action generated in the same call under the specified token name. Therefore, use the method in the email template sent by this action. Which action uses which token name is listed under Token names. Signature
$wsOptIn.createTokenUrl(url, tokenName) Return value
string - URL with appended token.

If no token with the specified name was generated in the current call, the method returns the URL unchanged.
If url or tokenName is not text, the method returns null.

Parameters

Name	Type	Required	Description
`url`	string	yes	URL of the confirmation page to which the token is appended. In emails, use an absolute URL.
`tokenName`	string	yes	Name of the token, for example `"verifyEmail"`. The name is case-sensitive.

Example that generates a link with token in the email template for verifying the email address.

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

Actions

No dedicated actions are available for $wsOptIn. The actions for generating or confirming opt-in tokens can be found under Account and Newsletter.

Examples for data access

Confirming the email address via opt-in link

After a customer account is created, the AccountRegister action generates the verifyEmail token and sends an email to confirm the email address. In the template of this email, you generate the confirmation link like this, for example:

<a href="{{= $wsOptIn.createTokenUrl($wsViews.viewUrl('account/emailVerify.htm', {}, 'absolute'), 'verifyEmail') }}">
  Confirm email address
</a>

The confirmation link contains a token that ensures only the recipient can perform the confirmation.

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

When the customer clicks the link and the confirmation page (emailVerify.htm) is opened, the page checks whether the token is valid. If so, the customer can complete the verification by clicking a button, which performs the EmailVerify action.

{{ if $wsOptIn.current }}
    {{ if $wsOptIn.current.valid }}
      Button to confirm
    {{ else }}
      This link is no longer valid.
    {{ /if }}
{{ else }}
    Invalid access to the confirmation page.
{{ /if }}

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

$wsOptIn - Opt-in processes

Module overview

How an opt-in link works

Token names

Tokens from shop actions

Tokens from the Admin Interface API

Templates

Variables

$wsOptIn.current

$wsOptIn.current.valid

$wsOptIn.current.token

Methods

$wsOptIn.createTokenUrl()

Actions

Examples for data access

Confirming the email address via opt-in link

​Module overview

​How an opt-in link works

​Token names

​Tokens from shop actions

​Tokens from the Admin Interface API

​Templates

​Variables

​$wsOptIn.current

​$wsOptIn.current.valid

​$wsOptIn.current.token

​Methods

​$wsOptIn.createTokenUrl()

​Actions

​Examples for data access

​Confirming the email address via opt-in link

​Related links

Module overview

How an opt-in link works

Token names

Tokens from shop actions

Tokens from the Admin Interface API

Templates

Variables

$wsOptIn.current

$wsOptIn.current.valid

$wsOptIn.current.token

Methods

$wsOptIn.createTokenUrl()

Actions

Examples for data access

Confirming the email address via opt-in link

Related links