The launcher is a button on a web page that is used to open the Web Widget. Whilst some launcher customization is available, there may be instances where you want to create your own launcher and define how it behaves. This quickstart tutorial shows how to do this using HTML, CSS, and Web Widget JavaScript APIs.
This tutorial contains the following topics:
- Requirements
- Creating a sample web page
- Adding the Web Widget on your web page
- Building a custom launcher
Related information:
In this tutorial, you’ll replace the default launcher with a custom launcher with a “Click to chat with me!” label.
Requirements
- CodePen, a free online code editor. While this tutorial uses CodePen, you can use other code editors such as JSFiddle and JS Bin.
- A Zendesk Support account or a trial account.
- Supported web browsers for the Web Widget, as described in Using Web Widget to embed customer service in your website.
Creating a sample web page
In this section, we’ll create a “Hello World” web page using CodePen, an online code editor.
To create a “Hello World!” web page
- In your web browser, go to https://codepen.io/pen/.
- In the top UI pane, click Change View, and select the left view option.
- In the HTML editor on the top right side, click the dropdown menu, and select Maximize HTML Editor.
- Copy and paste the following HTML code into the HTML editor.
<!DOCTYPE html> <html lang="en"> <head> <title>Hello, World!</title> </head> <body> <p>Hello, World!</p> </body> </html>
The web page is displayed in the window on the right side.
Adding the Web Widget on your web page
To add the Web Widget on your web page, you need to copy and paste the Web Widget script in Zendesk Support.
- Click the Admin icon (
) in the sidebar, then select Channels > Widget.
- Click the Setup tab, if it is not already selected.
- Under the code box, click Copy to clipboard.
- In your HTML editor, paste the script before the closing </body> tag. For example:
<!DOCTYPE html> <html lang="en"> <head> <title>Hello, World!</title> </head> <body> <p>Hello, World!</p> <!-- Start of Zendesk Widget script --> <script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_SNIPPET_KEY"> </script> <!-- End of Zendesk Widget script --> </body> </html>
By default, the Web Widget is displayed on the bottom right of your web page.
Building a custom launcher
After adding the Web Widget to your web page, creating your custom launcher requires three steps:
- Adding the div element to the web page for your custom launcher.
- Using HTML and CSS to customize your launcher style and format.
- Using client-side Web Widget JavaScript APIs to define how you want the launcher and Web Widget to behave.
In this part of the tutorial, you’ll create a launcher that opens the Web Widget, and when the Web Widget is closed, will revert back to the custom launcher.
Adding the launcher <div> element to your web page
The <div> element you’ll add to the web page contains the following launcher-related content:
- A <div> element with an id of “myLauncher”
- An onclick event handler to open the Web Widget when the launcher button is clicked
- Custom launcher button text: “Click to chat with me!”
In the HTML editor, copy and paste the following code between the <body> tags after the Web Widget snippet:
<div id='myLauncher' onclick='openWidget()'>Click to chat with me!</div>Next, you’ll add the CSS.
Creating the launcher
You'll create custom launcher with the following design parameters:
- Red background color
- 10px padding
- 4px border
- 100px width
- Launcher text to be center aligned
- Text to be a sans-serif font
- Text color to be white
- 300ms for the launcher to transition in and out
#myLauncher {
background-color: red;
padding: 10px;
border-radius: 4px;
width: 100px;
text-align: center;
color: white;
font-family: sans-serif;
}To add the custom launcher CSS
- Copy and paste the CSS element into the CSS window editor.
- Refresh your web page. The custom launcher is displayed.
You can experiment modifying CSS properties and values to observe what happens to the custom launcher format and styling. To learn more about what CSS options are available, see the MDN docs Learn to style HTML using CSS.
Defining the custom launcher and Web Widget behaviour
The custom launcher and Web Widget behaviour is configured using Web Widget JavaScript API commands. You access the API settings using JavaScript in the source code of your website. For the purposes of this tutorial, a script is added directly to the web page.
Hide the launcher on page load
In the HTML editor, add the hide command between script tags after the Web Widget snippet:<script type="text/javascript">
zE('webWidget', 'hide');
</script>The hide command prevents the Web Widget launcher displaying when the custom launcher is loaded.
When clicking the custom launcher, hide the launcher, and open the Web Widget
<script type="text/javascript">
zE('webWidget', 'hide');
function openWidget() {
zE('webWidget', 'show');
zE('webWidget', 'open');
document.querySelector('#myLauncher').style.opacity = 0;
};
</script>
The openWidget() function is called when the user clicks your launcher. The following is added to the function:
- the show command to show the Web Widget since the hide command is used to suppress the Web Widget launcher on page load
- the open command to force the Web Widget to appear
- the document.querySelector() method to select the ‘myLauncher’ element and set its opacity to 0. This hides the custom launcher
If you don't want to hide the custom launcher when the Web Widget is open, you can leave out document querySelector() line.
When the Web Widget is closed, hide the Web Widget, and show the custom launcher
<script type="text/javascript">
zE('webWidget', 'hide');
function openWidget() {
zE('webWidget', 'show');
zE('webWidget', 'open');
document.querySelector('#myLauncher').style.opacity = 0;
};
zE('webWidget:on', 'close', function() {
zE('webWidget', 'hide');
document.querySelector('#myLauncher').style.opacity = 1;
})
</script>For the on close command, the:
- hide command is called to hide the Web Widget
- Document method querySelector() is used to show the custom launcher by setting the opacity to 1.
Now try out your custom launcher!
4 Comments
Thank you so much for this article! We had a hard time customizing the launcher and failed, but this really helped!
Darren Chan thank you, this helped a lot however am noticing some unintended behaviour.
We've followed these instructions and got our Custom launcher working as expected but we have one issue where proactive notifications or agents initiating chats on their end aren't allowing the widget to open itself.
If we don't use the custom launcher, the widget will automatically open on the user's screen without requiring the user to open the widget manually. However with our custom launcher, built exactly as above, the user has to manually open the widget to see any notifications or proactive messages. Are we missing something?
Hi Wesley. I'll let Darren offer input as well, but this is definitely a tutorial — specific needs may vary. This is just to demonstrate some of the basic features that are available.
That said, you can add code that considers different events. For example, this code is triggered when a chat message comes in:
zE('webWidget:on', 'chat:unreadMessages', (number) => {console.log(`You have ${number} unread messages`);
})
You could use the above and then call:
zE('webWidget:on', 'open', function() {console.log('The widget has been opened!')
})
Your needs may of course be different. The above are just ideas. Hope they help!
Just wanted to share if we want to a Custom Button to as a toggle button we can just do it by attaching onClose and onOpen to zE and just use the toggle command from the button.
Global Script
window.zE('webWidget', 'hide');window.zE('webWidget:on', 'close', function () {
window.zE('webWidget', 'hide');
});
window.zE('webWidget:on', 'open', function () {
window.zE('webWidget', 'show');
});
Button OnClick
window.zE('webWidget', 'toggle');Please sign in to leave a comment.