@crystallize/app-signal

@crystallize/app-signal

Provides a way for your app or frontend to talk to the Crystallize app.

Changelog

Apps 📱

Signal that the app is ready

import { signal } from '@crystallize/app-signal';

document.addEventListener("DOMContentLoaded", () => signal.send('ready'));

Links to the Crystallize App

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>

Here are all the things you can navigate to

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>'
});

Other signals

import { signal } from '@crystallize/app-signal';

// The menu listing all apps
await signal.toggleAreaMenu(true);

// Change app language
await signal.changeLanguage('pt');

Frontend previews 🖥

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.

No config setup

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>

Advanced setup

This is to be used if you want more control over how the frontend is embedded within Crystallize. You should implement two distinct handlers:

1. Notify that the frontend preview is ready

import { signal } from '@crystallize/app-signal';

document.addEventListener("DOMContentLoaded", () => signal.send('ready'));

1. 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');
})

Catching errors

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);
}

SSR

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'
})