ShareView
ShareView is a mode of the Frontend API ecosystem that allows users to preview content outside the ContentCreator without requiring it to be released in FirstSpirit.
This feature involves a token generation process that grants users access to a generated token, enabling them to view preview content from the Frontend API Backend or a similar implementation of the Frontend API Server package.
While the functionality works out of the box, some configuration steps are required to enable this view.
Frontend API Server: Configuration
A token secret must be synchronized between the Connect for Commerce module and the Frontend API Server configuration, as these two systems do not have direct access to each other.
A JWT token is an encrypted and signed string that contains information about the permissions required to securely access preview content. This security measure ensures that preview content is only accessible to authorized users.
The required configuration is located inside the core.project.shareView configuration object as follows:
# ...
core:
# ...
project:
# ...
shareView:
# Secret for decrypting token and verifying its integrity; must be base64-encoded.
secret: 'i-am-a-secret' # Important! Use a base64-encoded secret.
Secret
The secret can be generated within the Connect for Commerce Project App Configuration. The secret configured there must match the secret configured in the Frontend API Server configuration for the feature to function properly.
Token
A token includes the following information:
Expiration
The expiration duration can be set to a custom value. A token with a validity period of several hours to several days is typically reasonable.
Signature
A token is encrypted and signed using a specified secret. This base64-encoded secret is processed exclusively on the server side or within the Connect for Commerce module, ensuring that it is never sent to the storefront or browser.
Access to all pages
The Frontend API supports two modes:
-
Allow preview of one specific page
The user is authorized to view a single page with preview content from CaaS, while other pages will display only the released version. -
Allow preview of all pages
The token grants the user access to preview content across all pages, ensuring that every navigation within the storefront fetches the preview version from CaaS.
Generate a token
Setup Executable
To generate a token, the project component of the Connect for Commerce module must be configured. A JWT secret must be generated and applied to both the module and the Frontend API Server configuration.
Refer to the chapter Configuration of the Project Component.
Call EcomApi
Within the ContentCreator Preview, the EcomAPI can trigger an Executable to generate a valid token. The following example illustrates this:
import { EcomApi, PageTarget } from 'fcecom-frontend-api-client/src';
import { LogLevel } from 'fsxa-api';
const ecomApi = new EcomApi('https://example.com', LogLevel.INFO);
const pageTarget: PageTarget = {
id: 'i-am-an-id',
type: 'product',
fsPageTemplate: 'product',
isFsDriven: false,
};
ecomApi
// Request token from Executable: Allow a single page
.getShareViewLink({
id: pageTarget.id,
type: pageTarget.type,
lifetimeMs: 24 * 60 * 60 * 1000, // 24h
})
// Copy result to clipboard
.then((result) => navigator.clipboard.writeText(result));
ecomApi
// Request token from Executable: Allow all pages
.getShareViewLink({
universalAllow: true,
lifetimeMs: 24 * 60 * 60 * 1000, // 24h
})
// Copy result to clipboard
.then((result) => navigator.clipboard.writeText(result));
// ** Extra: FirstSpirit-driven pages **
ecomApi
// Request token from Executable: Allow a single FirstSpirit-driven page
.getShareViewLink({
isFsDriven: true,
fsPageId: 'i-am-an-fs-page-id',
lifetimeMs: 24 * 60 * 60 * 1000, // 24h
})
// Copy result to clipboard
.then((result) => navigator.clipboard.writeText(result));