Provides a way for your app or frontend to talk to the Crystallize app.
import { signal } from '@crystallize/app-signal';
document.addEventListener("DOMContentLoaded", () => signal.send('ready'));
For creating links to the Crystallize app, you should follow this practice:
import { signal } from '@crystallize/app-signal';
const linkToParams = { area: 'item', id: '123' }
<a href={signal.getUrl(linkToParams)} target={linkToParams.target} onClick={(event) => {
// Stop if the user wants to open in a new tab
if (!(2 === event.which || event.metaKey || event.ctrlKey)) {
event.preventDefault();
signal.navigateTo(linkToParams);
}
})>Go to {linkToParams.area} in the Crystallize app</a>
import { signal } from '@crystallize/app-signal';
// Navigate to an item using id
await signal.navigateTo({
area: 'item',
id: '<itemId>'
});
// Navigate to an item using external reference
await signal.navigateTo({
area: 'item',
externalReference: '<refId>'
});
// Navigate to a product variant using SKU
await signal.navigateTo({
area: 'productVariant',
sku: '<sku>'
});
// Navigate to a customer
await signal.navigateTo({
area: 'customer',
identifier: '<identifier>'
});
// Navigate to an order
await signal.navigateTo({
area: 'order',
id: '<orderId>'
});
// Navigate to a grid
await signal.navigateTo({
area: 'grid',
id: '<id>'
});
// Navigate to a topic
await signal.navigateTo({
area: 'topic',
id: '<id>'
});
// Navigate to a fulfilment pipeline
await signal.navigateTo({
area: 'fulfilmentPipeline',
id: '<id>'
});
// Navigate to an app
await signal.navigateTo({
area: 'app',
id: '<identifier>'
});
import { signal } from '@crystallize/app-signal';
// The menu listing all apps
await signal.toggleAreaMenu(true);
// Change app language
await signal.changeLanguage('pt');
Frontend previews are a way of embedding your websites within Crystallize, allowing you to preview how content will look like for the end user. Learn more at Frontend previews.
This will work with the majority of frontends, and will trigger page reload using location.reload()
when the app wants it to.
<script src="https://unpkg.com/@crystallize/app-signal/dist/frontend-preview-listener.js"></script>
This is to be used if you want more control over how the frontend is embedded within Crystallize. You should implement two distinct handlers:
- Notify that the frontend preview is ready
import { signal } from '@crystallize/app-signal';
document.addEventListener("DOMContentLoaded", () => signal.send('ready'));
- Reload the page when the app wants to. This will be when the reload button is pressed, or when content is changed and "live mode" is activated.
import { signal } from '@crystallize/app-signal';
signal.on('reload', function () {
location.reload();
signal.send('reloading');
})
Every signal sent to the app is async, and should be wrapped in a try...catch clause, like so:
import { signal } from '@crystallize/app-signal';
try {
await signal.send('some.bogus.message');
} catch(error) {
console.error('Could not send the message');
console.log(error);
}
In order to generate the correct links and such on the server side, you need to pass the context.
import { signal } from '@crystallize/app-signal';
signal.setContext({
origin: 'https://app.crystallize.com',
tenantId: '<your-tenant-id>',
tenantIdentifier: '<your-tenant-identifier>',
language: 'en'
})