Userplane

Webmessenger

Jump to

Documentation → Webmessenger

Overview

The webmessenger is a popup instant messaging experience. It’s primary advantage as an experience lies in it’s stateless nature in that it can maintain a video session while the parent page is being reloaded or navigating from page to page. Being a popup experience provides a whole host of specific use cases along with configurable options that pertain specifically to the pop-out experience.

Embed

There is no need to enable the webmessenger as it is the default experience, simply embeding Userplane will result in the Webmessenger being available on your website. In order to full implement the experience though you will need to add a way to start a conversation using the badge.

APIs

EVENT: HANDLE_CLICK

Below is an explanation of the properties that are provided in the HANDLE_CLICK event. This event occurs when the handle of a user is clicked.

Property	Description	Example
userId	The userId of the user who’s handle was clicked.	event.context.userId

Example

// All bindings should be made inside of the READY event callback to ensure that Userplane is fully loaded when you beging registering callbacks in your code.
up.api.addEventListener( up.api.events.READY, function() {
     // Add an event listener for the HANDLE_CLICK event
     up.api.addEventListener(up.api.events.HANDLE_CLICK, function(event){ 
            // when the handle is clicked this callback function will be triggered.
            console.log("clicked handle:", event.context.userId); 
     });
});

EVENT: AVATAR_CLICK

Below is an explanation of the properties that are provided in the AVATAR_CLICK event. This event occurs when the avatar of a user is clicked.

Property	Description	Example
userId	The userId of the user who’s avatar was clicked.	event.context.userId

Example

// All bindings should be made inside of the READY event callback to ensure that Userplane is fully loaded when you beging registering callbacks in your code.
up.api.addEventListener( up.api.events.READY, function() {
     // Add an event listener for the AVATAR_CLICK event
     up.api.addEventListener(up.api.events.AVATAR_CLICK, function(event){ 
            // when the handle is clicked this callback function will be triggered.
            console.log("clicked handle:", event.context.userId); 
     });
});

Properties

The following properties are values that can be provided via the settings object of the embed code. Simply add them to your settings object and the SDK will use them in your experience.

Property	Value	Default
wmWindowHeight	The height of the window for Webmessenger.
wmWindowWidth	The width of the window for Webmessenger.
wmWindowName	The label of the window for the Webmessenger.
enableNotifications	Controls whether or not the built-in notifications are used.	true

Localization

If you are interested in replacing the static string values used in the Webmessenger you can do so by overwriting the locale values for any particular locale. Below are a set of locale properties our publishers typically are interested in overwriting within the Webmessenger experience. For more information on overriding locale settings please see: Overriding Locale Settings

Property	Value	Default
line1Label	The label for the first line of profile data.	Age
line2Label	The label for the second line of profile data.	Sex
line3Label	The label for the third line of profile data	Location
line4Label	Not currently used.
invitationMessage	Text display to let the user know its an incoming conversation request.	Incoming Conversation Request!

Sample

This sample is of a locale override being added to your up.init call inside the settings object.

// this object would be added to your up.init call
settings: { locale: {
		line1Label: "Age",
		line2Label: "Sex",
		line3Label: "Location",
		line4Label: "",
		invitationMessage:"Would you like to chat?"
	}
}

FAQ

How do I launch my own help from the help icon?

There is a way to launch a help page from the Webmessenger3 window. You will just need to create a javascript function to launch the page and pass the function into the Userplane embed code in the the html of your web page within the

Javascript

function helpClickHandler(){
window.open("http://www.example.com/help.html);
}

Here is an example of how to pass the function into the embed code:

<script type="text/javascript" src="http://cdn.userplane.com/release/sdk/userplane.js"></script>
<script>
       up.init({
      siteId:"YOUR_SITE_ID",
      key: "",
      token: "YOUR_SSO_TOKEN",
      settings: {
            helpClickHandler:helpClickHandler
      },
      lang: "en-us"
   });

</script>

How do I launch a profile page using the avatar and handle?

In order to launch a profile page using the avatar and handle you need to capture the AVATAR_CLICK and HANDLE_CLICK events.

I have an existing account. How can I upgrade to the new Webmessenger 3?

If you would like to upgrade to the new platform, please contact support@userplane.com.

How do I launch and Instant Message using just Javascript?

While we do highly suggest that you use the badge widget or the hover cards as your call to action for sending an instant message, we understand that our implementations may not meet your design or business requirements around launching an instant message. So in its place we recommend you use the following code to launch an Instant Message from the local logged in user to a target user. Do understand that this code is deferred until after your page load so if you attempt to execute the custom launcher code before the Userplane SDK has fully loaded and connected, nothing will happen.

Example

// Format Example
up.api.startInstantMessage('INSERT_USER_ID_HERE');

// Code Example
<a onClick="up.api.startInstantMessage('414267')" href="#OpenIM">Send IM</a>

How do I add advertisements in Webmessenger?

Adding your custom html to the Webmessenger requires that you add a custom footer to the popup window whereby you can load any html you wish to to the popup window. The Webmessenger will automatically adjust to the space your code takes up, so you shouldn't need to do anything beyond providing your html to your userplane embed code.

<script type="text/javascript" src="http://cdn.stage.userplane.com/release/sdk/userplane.js"></script>
<script>
   // Embed the Userplane SDK and provide the general configuration for your account.
   up.init({
      siteId:"YOUR_SITE_ID",
      token: "YOUR_SSO_TOKEN",
      lang: "en-us",
      settings: {
          popupWindowCustomHeader: "Some Custom Code Here",
	  popupWindowCustomFooter: "Some Custom Code Here"
      }
   });

</script>

Note that the code placed into these properties must either appear on one line or be properly formated as it may potentially cause issues with your javascript syntax if you simply copy an paste into it.

Inserting Advertisements

Given the above, adding your advertismeents is as simple as compressing you entire advertisement snippet into a single line and placing it into the popupWindowCustomerFooter property above.

Note For Adsense Customers

Due to the way adsense embed code works and in order to comply with the Terms of Service you must add the following snippet of CSS to your footer in order to get the ad to render in the right location

<style>ins { position: absolute !important; bottom: 5px !important; left: 5px; }</style>

How to launch a help page using help icon

Javascript

function helpClickHandler(){
window.open("http://www.example.com/help.html);
}

Here is an example of how to pass the function into the embed code:

<script type="text/javascript" src="http://cdn.userplane.com/release/sdk/userplane.js"></script>
<script>
       up.init({
      siteId:"YOUR_SITE_ID",
      key: "",
      token: "YOUR_SSO_TOKEN",
      settings: {
            helpClickHandler:helpClickHandler
      },
      lang: "en-us"
   });

</script>

How do I launch Webmessenger 3 from Webchat 2

There is a way to launch the Webmessenger 3 from within the Webchat 2. You will just need to add a javascript function to launch the Webmessenger 3 and the userplane embed code to the wc file.You will need to remove or comment out the launchWM javascript function in the 'InstantCommunicator.StartConversation' event in the wc file.

Then you will replace it with the following javascript function:

Javascript

up.api.startInstantMessage(strUserID);

Example

if( strEvent == "InstantCommunicator.StartConversation" )
         {
            var strUserID = strParameter1;
            var bServer = strParameter2;
            // open up an InstantCommunicator window.  For example:
            //launchWM( "", strUserID );
            up.api.startInstantMessage(strUserID);

         }

Finally, in the wc file you will add the following userplane embed code to the

Embed

<script type="text/javascript" src="http://cdn.userplane.com/release/sdk/userplane.js"></script>
<script type="text/javascript">
    up.init({
   siteId:"YOUR_SITE_ID",
   key: "",
   token: "YOUR_TOKEN",
   settings: {}, 
   lang: "en-US"
} );
</script>

You must set the siteID and session parameters with a values. The siteID should already be input in your embed code or we will provide you with one. The session parameter will be the same value as the sessionGUID you are currently using in the wc file.