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:

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

The “myLauncher” CSS rule sets the format and layout for the launcher. It contains the properties and values for the launcher that we have defined above:

#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.

Note: API commands must be placed after the Web Widget snippet in your web page source code.

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

The behaviour of the openWidget() function needs to be configured, which is referenced in the myLauncher <div> element on your web page. Copy and paste the code snippet in bold between the script tags in your HTML editor:

<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

Next, you’ll use the Web Widget on close command to call a function when the user closes the widget. Copy and paste the code snippet in bold between the script tags in your HTML editor:

<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!

Join the discussion about this article in the community.

5 Comments

Tetiana Kharchenko
- April 14, 2020 08:38
Comment actions Permalink
Thank you so much for this article! We had a hard time customizing the launcher and failed, but this really helped!

0
Wesley Bowles
- August 10, 2020 16:13
Comment actions Permalink
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?

0
Bryan - Community Manager
- August 11, 2020 21:27
Comment actions Permalink
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!
0
Danish Kamal
- October 15, 2020 13:15
Comment actions Permalink
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');
```
1
kemuel sanchez
- April 24, 2021 12:59
Comment actions Permalink
@Danish Kamal idea should be the one in the tutorial. Much clearer and intuitive.

0

Please sign in to leave a comment.

Quickstart – Creating a launcher for the Web Widget