Z/Docs
Create Accountlogin

Website Plugin with Web Components

In this chapter you will learn how to integrate a conversational model into your own website. As you will see, there is more to it than simply including the conversation: your website can interact, exchange state or manipulate the conversation with a bit of JS code.

Using the Plugin

There are two ways how you can include your conversational model on your own website: iframes and web components.

Iframes

The easiest (but not recommended) way to include your conversational model into your website is by using an iframe.

<iframe src="https://zircel.com/hello/5891d72c07d37b8c12266e8a/introwelcome"></iframe>

Simply paste the above snippet into the html <body> tag of your website and you are ready to go. However, don't forget to replace the profile id and the tree in the url. The most convenient way to get the correct url is to start the live version of your conversational model and copy/past the url from the browser bar.

That being said, we at Zircel suggest you not to use iframes for the following reasons:

Web Components

We advise you to use Web Components to include your conversational model into our own website. It takes one (and a half) additional steps in the setup, but once installed, your experience and capabilities will be much greater.

To get started, you will have to let us know about the domain name of your website. Go to the "Dev" tab on the welcome page and enter your plugin URL. We need to know your domain so our servers can be sure they only allow you the super-powers of web components and not any other website on the interwebs. If you want to learn more why we need to know your domain, you can read a wikipedia article about CORS.

Be aware that once you try to load your website and your plugin url is incorrect or missing your browser will show an error message that says: domain 'http://your-website.com' is not registered.

Next, you can add the following script to the <head> tag of your website:

<script src="https://zircel.com/dist/hello/component.js"></script>

Once you have done so the beauty of web components begins to shine. You can add your conversational model to your website by adding an element to your html body. Here's how this would look like:

<zircel-page pid="5891d72c07d37b8c12266e8a" path="/introwelcome"></zircel-page>

Don't forget to replace the pid (profile id) and the path (the name of your execution tree).

Hooray! Your zircel page is set up.

Creating the Plugin with JS

Instead of adding the <zirce-page> manually to your html file, you can also achieve the same result by loading the conversational model dynamically with a bit of JS code:

const body = document.querySelector('body') const page = document.createElement('zircel-page') // Configuration page.pid = '5891d72c07d37b8c12266e8a' page.path = '/introwelcome' page.scrolling = 'document' page.state = { name: 'Mike', customerId: '125-124-123' } page.mode = 'production' page.init().catch(err => console.error(err)) body.appendChild(page)

Notice a few things:

Auto-Scroll Behaviour

One important aspect of the enduser experience is the scroll behaviour of your conversational page. One can control the experience by setting page.scrolling. There are three options:

AttributeBehaviour
"document"This is the default and will automatically scroll your whole website to the latest selected node.
"page"Sometimes, you only want a specific section of your website to scroll within your whole website. You can achieve this result by setting page.scrolling = "page". Notice that you will also have to set a CSS rule in your stylesheet to assign a fixed height to the web component and subsequently turning on scrolling when the content of the conversation gets too large to be displayed within the fixed size of the component. Here's how you can do this:
zircel-page { height: 400px; overflow: scroll; }
"off"This will turn off auto scrolling completely.

Development vs Production Mode

If you are working on a new conversational website which hasn't been released yet and you try to include this conversational model into your own website you will get an error saying "there is nothing to find here" (i.e. your model cannot be found because you haven't released your tree yet). What if you still want to preview how your conversational model will look like intregrated into your own website before it is released?

Setting the property page.mode to "development" can help with that.

AttributeBehaviour
"production"This is the default and will load the latest released version of your conversational model. Analytics and the State Management are enabled.
"development"By setting the mode to "development" Zircel will load your current working tree (that is the one you see in the Tree Editor). Analytics are turned off. State Management is simulated with the Test State. User Identification is simulated with a fake user id (more in the next chapter).

PS: don't forget to switch the mode back to default (=production) once you want to go live with your website.

User Identification

When dealing with user state a go-to method is using a http-session with cookies. Unfortunately, this method doesn't work here for several reasons:

Therefore, we give the control over the users' state into your hands. Consider (the slighthly modified) example from before:

const body = document.querySelector('body') const page = document.createElement('zircel-page') // Configuration page.pid = '5891d72c07d37b8c12266e8a' page.path = '/introwelcome' page.mode = 'production' page.init() .then( uid => console.log(uid)) .catch( err => console.error(err)) body.appendChild(page)

Notice the second last line. Here, page.init() returns a Promise that resolves with the user id (uid). This user id is created for every new user that visits your conversational model. The user id is cached in the memory until the user leaves your website or refreshes the page. If you use the above snippet and refresh your browser window you will see that a new uid is generated. You can observe this by looking at your browser's console. At this point, the state of your previous visit is lost since Zircel isn't able to identify any state with your current (and newly generated) user id.

So, how can you hold on to your user's state over multiple website visits? Simple: you need to store the user id for as long as you want/need. You can then re-instantiate a users' state by passing a user id to the plugin:

const body = document.querySelector('body') const page = document.createElement('zircel-page') // Configuration page.pid = '5891d72c07d37b8c12266e8a' // re-initialize a users state page.uid = 'your-uid-goes-here' page.path = '/introwelcome' page.mode = 'production' page.init() .then( uid => console.log(uid)) .catch( err => console.error(err)) body.appendChild(page)

By setting page.uid before initialization you can re-instantiate a users' state. Notice that the page.uid property must be set to a valid/existing uid. As a consequence, the above example does not work since 'your-uid-goes-here' is neither a valid nor an existing user id. It will result in an error (see the browser console). To quickly show the correct effect manually copy the logged user id from the console and replace 'your-uid-goes-here' with it. Then, reload the page. Now, the Promise returned by page.init() should resolve with the same uid as before i.e. the user (state/id) is not newly created but re-initialized.

Another question you might have is how to hold on to the user id. There are multiple options for you to choose from depending on your use case:

In development mode (page.mode = 'development') user identification can only be simulated. A static and fake uid with the value 111111111111222222222222 is assigned to you (i.e. you are always the same "simulated/fake" user no matter how many times you reload the browser). Further, your state is also simulated with Test State.

Zircel Event API

With the Zircel Event API your personal website can interact with the conversational model. For example, this allows you to listen to all the state changes that occur during conversations of your users. You could then proceed and use the gathered state information directly in your own application.
Further, the Zircel Event API also allows you to send commands to the conversational website by triggering a ZircelEvent.

Listening to the Conversation

Whenever a user clicks on a button within your conversational website a new node is rendered to the user's browser window. You can follow along and listen to any updates:

page.addEventListener('zircel-update', e => { const data = e.detail // print the latest state console.log(data.state) // print the new node (object) console.log(data.node) // often, one wants to wait for a certain node // to be triggered in order to react to it if (data.node.id === 'bubble-71c5-af81-40d6') { // do stuff (e.g. delete older nodes) } })

Triggering Events

By calling a ZircelEvent function you can manipulate the state and appearance of the conversation. Here's an example

page.jumpTo('basic-a17e-97fc-ee06')

In the above example a 'jump-to' command is triggered which will append (i.e. render to screen) the node with id 'basic-a17e-97fc-ee06' to the user's conversation.

Here's a list of supported functions:

page.jumpTo(id, opts)


ArgumentBehaviour
idA string of an existing node in your execution tree. Once the event is triggered the conversation will jump to the specified node.
opts.clearConversationBoolean. If true all nodes that are currently rendered on the screen get deleted and the conversation starts fresh with a clean sheet.

page.setState(state)


ArgumentBehaviour
stateObject. The property-value pairs of the state object are used to update the state manager during runtime. Every property acts as a key in the key-value based state manager. The submitted state object will thus not completely overwrite the current state but only the submitted properties/keys. Notice also that imported state (keys) need to be matched with explicit state keys and throw an error otherwise.

The function setState returns a Promise which will resolve in case the state update is successful. If the state update fails the Promise is rejected.

page.deleteNodes(opts)


ArgumentBehaviour
opts.allButLastBoolean. When set to true, this event will delete all previously appended nodes except the last one (the one that was last appended to the conversation). When set to false, all nodes get deleted.

Misc

Browser Support

Web Components are a new Web Technology which is not yet supported by all major browsers. Safari, Chrome and Firefox do support it, but Microsoft Edge is still working on releasing the feature. If you want to stay up to date you can check caniuse.com.

Privacy Policy and Cookies

As soon as the web component plugin is included in your personal website, Zircel will no longer prompt Privacy Policy and Cookie Warnings to new visitors/users. We assume that you have the required legal documents already in place on your current website to comply with regulations such as GDPR.