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:
- Your website can not communicate with the conversational model.
- Iframes are a pretty old but reliant technology. However, there are many more powerful alternatives nowadays.
- Generally speaking, iframes don't work great on mobile devices. They were developed in a pre-smartphone era and do not automatically adapt their size to the screen of your users' phones and the size of your conversation.
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:
pidandpathhave exactly the same purpose as in the static example.- You can choose between different scroll behaviors. See below to learn more about it.
- State can be imported before initializing the conversational model. In the example above
nameandcustomerIdwould need to be reflected by explicit state keys. In other words, you need to define two explicit state keys "name" and "customerId" of type string. - After configuring your page, you have to manually initialize the conversational model by calling
page.init(). This function will return a Promise that might end up being rejected for various reasons. Therefore, it is good practice to act upon a potential error to provide an alternative or explanation to the enduser.
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:
| Attribute | Behaviour |
|---|---|
"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.
| Attribute | Behaviour |
|---|---|
"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:
- Zircel cannot and doesn't want to install third-party cookies to identify users.
- If Zircel manages user sessions/state you (as a developer) don't have control over the lifespan of the state.
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:
- You could save the user id to the localStorage and then retrieve it whenever a visitor returns to your website.
- If you use a conversational model within an application with proper user-authentication you could persist the user id with other user-related data on your own database.
- If you have a public website chances are high that you don't have to hold on to the user id at all. Maybe it is even required or wished for that every user visit starts with a fresh state.
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)
}
})
- The Zircel Event API is built with the CustomEvent API. If you are unfamiliar with CustomEvents you can read more about it here.
- You can grab the id of a certain node in your tree by heading over to the Tree Editor. Once the editor is loaded, click on any node and notice the its id shows up at the very bottom of the sidepanel.
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)
| Argument | Behaviour |
|---|---|
id | A string of an existing node in your execution tree. Once the event is triggered the conversation will jump to the specified node. |
opts.clearConversation | Boolean. 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)
| Argument | Behaviour |
|---|---|
state | Object. 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)
| Argument | Behaviour |
|---|---|
opts.allButLast | Boolean. 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.