In this document, you will learn how to enable co-browsing on your existing Contact your customer installation. If you haven't done so yet, start by putting the tracking code in your web pages.

Co-browsing: how does it work?

When you enable the co-browsing feature of Butterflive, when an agent and a visitor are chatting together, they are viewing the same page. Unlike most screen-sharing technologies, in Butterflive, the content of the visitor screen is not sent to the agent. Instead, the agent and the visitors are visiting together the same page. This means Butterflive is sharing the URLs.
This has a few consequences. Indeed, to be able to successfully enable the co-browsing, you must be sure that one URL displays the same information on both sides (whether you are an agent or a visitor).

To add some interactivity, some elements of the screen are shared between the agent and the visitor. For instance, you can share the state of a textbox. This means that each time some text is typed in the textbox, the text typed will be visible to the other user. You can also share your mouse pointer, etc...

In the next chapter, we will see how to enable the co-browsing of specific events.

Enable co-browsing

By default, co-browsing at the page level is enabled. If a visitor browses your website while an agent is chatting with the visitor, the agent will automatically be switched from page to page. If you want to enable co-browsing at a deeper level (for instance to enable the sharing of a form), you have to add a few lines of Javascript code in your page.

Full co-browsing

The easiest way to access full co-browsing capability is to use the shareAll option:
Add the shareAll option to the startup options:

        bflOptions = {
        key: "Your butterflive key",
        src: "/path/to/butterflive.js",
        shareAll: true
        };
 

If you want to enable full co-browsing once Butterflive is loaded, you can use the Butterflive.shareAll() method:

        Butterflive.shareAll();
 

When full co-browsing is enabled, all the forms on your web pages are shared. The scrollbars are shared too and mouse pointers are displayed as "ghosts" on your interlocutor's screen.
Of course, to respect privacy, you might want to share only a part of your screen. In the following sections, we will see how to share only elements of the page.

Share your mouse cursor

To share your mouse cursor with your visitor (the visitor will see your mouse cursor as a "ghost" cursor), use the shareMouse startup option:

          bflOptions = {
          ...
          shareMouse: true
          };
 

Alternatively, if Butterflive is already loaded, you can use the Butterflive.shareMouse() method:

          Butterflive.shareMouse();
 

Share a form

To share a form, you must individually share the form elements. To do this, you can use the share startup option.
This option takes an array of CSS selector in parameter, and shares the elements described by the selector.
For instance:

          // This would share all input tags whose class is "cobrowse"
          // and the field whose id is "name":
          bflOptions = {
          ...
          share: [
          "input.cobrowse",
          "#name"
          ]
          };
 

          // This would share all input fields that are part of the forms whose class is "shared"
          bflOptions = {
          ...
          share: [
          "form.shared input"
          ]
          };
 

          // This would share all input fields on the page
          bflOptions = {
          ...
          share: [
          "input"
          ]
          };
 

If Butterflive is already loaded, you can use the Butterflive.share() function instead. This function takes a CSS selector in parameter, and shares the elements described by the selector.
For instance:

          // This will share all input tags whose class is "cobrowse"
          Butterflive.share("input.cobrowse");
 
          // This will share the field whose id is "name"
          Butterflive.share("#name");
 
          // This will share all input fields that are part of the forms whose class is "shared"
          Butterflive.share("form.shared input");
 
          // This will share all input fields on the page
          Butterflive.share("input");
 

Share other elements

If your web pages are big, you might want to share the scroll bars, to be sure that when a visitor scrolls the page to view a part of it, the agent is automatically scrolled to the same position. For this, you just have to scroll the "window" element.

          bflOptions = {
          ...
          share: ["window"]
          };
 

or

          Butterflive.share('window');
 

If you have "div" elements with scroll bars (for instance "div" elements with the CSS "overflow" property set to "scroll", you can share those scrollbars too:

          bflOptions = {
          ...
          share: ["div"]
          };
 

or

          Butterflive.share('div');
 

Preventing cobrowsing on some pages

Butterflive shares URLs between users. When a user takes his interlocutor to a new page, the interlocutor loads the page using an HTTP "GET" request. Therefore, if your application uses POST requests (for instance to submit a form), the POST requests should ideally lead to an HTTP redirect, to a URL loaded via GET, so the page can be shared. Alas, this is not always possible.
Furthermore, there are cases where you might want to prevent cobrowsing. Typically, while helping a visitor, an agent might be browsing in admin pages. The visitor is not logged and logically, he cannot see these pages. You want to prevent him from seeing an "Access denied" page.
For all these reasons, you can prevent cobrowsing on some pages. Preventing cobrowsing is easy, you just have to use the "dontCobrowsePage" option in the Butterflive startup options:

            // Prevents cobrowsing on this page
            bflOptions = {
            ...
            dontCoBrowsePage: true
            };
 

When a user arrives on such a page, its interlocutor is redirected in a waiting page. As soon as the user leaves the page, cobrowsing starts again normally.
You can customize the waiting page at will. Just modify the "nocobrowse.html" in your Butterflive Tracking Code directory.

Troubleshooting co-browsing issues

The first thing you must remember is that the co-browsing feature in Butterflive is done in Javascript. This means that is has the limitations and security features of any Javascript program. The best known security feature is the "cross-domain" protection. It implies that you cannot start co-browsing in a website, and expand it to another website. If the visitor, using your website, starts a co-browsing with an agent, and if the visitor, using a link, goes into another website, the agent will lose the ability to "co-browse" on the new site. This is actually a good thing, as it limits possible interaction into your website only, which is secure.