FirstSpirit Omnichannel Manager API

This library enables the use of FirstSpirit editorial functions in any frontend application like Single Page Applications and Progressive Web Apps.

This API is built to be used with the FirstSpirit Omnichannel Manager (short: OCM).

Learn more about FirstSpirit.

API

This module provides the frontend API snap since v1.2 onwards. To get a better idea how things work together see the documentation links above and refer to our demo application (Snap Shop).

The demo application includes a readme which describes how to set it up and how the development process works. There is another API for fetching content from the CaaS backend which is also included in the demo application (caas.js, see also below).

API Documentation

There is an online version of the API documentation. If you have to stick to an older version you find the matching version of the documentation in the deliverables you obtained from our technical support team.

Release Notes

See here: Release Notes.

Usage in your application

Determine the version of the OCM module in your FirstSpirit setup. Always include the exact matching version in your frontend. We do not recommend using LATEST as version identifier.

At least for development time it is recommended to expose the snapAPI so that it can be accessed from the browser console to ease trouble shooting.

snap.js

Include the snap.js somewhere in your markup.

CDN (browser, recommended)

<script src="https://cdnjs.cloudflare.com/ajax/libs/fs-tpp-api/VERSION/snap.js"></script>

Please replace VERSION in the above url with the correct module version (see above), e.g. https://cdnjs.cloudflare.com/ajax/libs/fs-tpp-api/2.1.1/snap.js. You can also use a tag name after the @ (you can find a list of valid tags at the npm package site). See https://cdnjs.com/api for a full documentation of the url format.

This is just an example, you may use other CDNs.

NPM (server-side builds)

# install
npm i fs-tpp-api@VERSION -s

# further usage
const TPP_SNAP = require('fs-tpp-api/snap');

Initialization

In the editorial mode it is mandantory to initialize the API by registering a callback to the onInit handler. In the callback code you should at least register handlers for these two callbacks:

0. onRerenderView - called every time the (changed) editorial content has to be rendered.
1. onRequestPreviewElement - called every time the routing of the application has to adapt to a request from the editorial ui (aka ContentCreator), e.g. when a search result entry has been clicked.

Preview content notation

Use the data-preview-id attribute on DOM nodes providing the FirstSpirit preview contents. Set the attribute value to the identifier attribute provided in the standard FirstSpirit JSON. If the JSON is crafted manually you can create the value in your template code using the previewId template function:

  $CMS_VALUE(previewId())$

IFrame handling

...or how does OCM integrate with the FirstSpirit ContentCreator?

In the ContentCreator the third party app is embedded in an iframe. The script is also part of the third party app. It communicates with the ContentCreator by means of window.postMessage.

DOM handling

...or how does OCM affect the DOM tree?

The implementation adds UI elements to your DOM tree. This is done by appending DIV nodes as children of document.body. We also listen to mouse events fired on annotated elements. A MutationObserver is also used.

caas.js

Include caas.js from the demo project in your markup to simplfy reading editorial content from the CAAS backend in your application.

Usage example:

const options = {
    host: "example.com"
    apikey: "my-apikey"
    project: "myCaasProject"
}
let response = await caas.get(options, "tutorials")
let data = response.data

Browser support

We support the following browsers:

• Chrome >= 59
• Firefox >= 61
• Edge >= 15
• Safari >= 10.1
• IE 11 (please import snap.ie11.js)