WID/Current/SDK/Engagement-combined

Learn how to use the Genesys Engage plugin to integrate any Engage solution with Genesys Widgets.

Related documentation:

• How Widgets works

The Genesys Engage plugin can integrate any Engage solution with Widgets. This plugin is generic and contains commands that automate engagement within Widgets. Starting with version 9.0.015.11, the Engage plugin includes Offers, which allows a customer to view a product or promotion on a page. It comes with many display modes and rendering options, such as overlay/toaster mode with text or image-only layouts, or both.

Overview

The Genesys Engage plugin can integrate any Engage solution with Widgets. This plugin is generic and contains commands that automate engagement within Widgets. Starting with version 9.0.015.11, the Engage plugin includes Offers, which allows a customer to view a product or promotion on a page. It comes with many display modes and rendering options, such as overlay/toaster mode with text or image-only layouts, or both.

Usage

The Engage plugin can be used to show either an invite or an offer via the following methods:

• Calling the Engage.invite command
• Calling the Engage.offer command

Namespace

The Engage plugin has the following namespaces tied to each of the following types.

Type	Namespace
i18n - Localization	Engage
CXBus - API Commands & API Events	Engage
CSS	.cx-engage

Screenshots

Engage Invite

• 

  Mobile mode Engage Invite view with dark theme

• 

  Mobile mode Engage Invite view with light theme

Engage Offer

• 

  Desktop Toast view with both image and text

• 

  Desktop Modal Overlay view with text on top

• 

  Desktop Overlay view with text at bottom

• 

  Desktop Toast view with text content on right side

• 

  Desktop Toast view with text content on left side

• 

  Desktop Overlay view with text on right side

• 

  Desktop Modal Overlay view with text on left side

• 

  Mobile Offer inserted onto the top of a web page

• 

  Mobile Offer view in modal overlay with background area grayed out

• 

  Mobile Offer view in modal overlay

Configuration

The Genesys Engage plugin doesn't have any configuration options.

Localization

The Genesys Engage plugin doesn't have any localization options.

API Commands

Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

Important

The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see Genesys Widgets extensions for more information about extending Genesys Widgets.

var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('Engage.invite');

invite

Opens the Engage Widget and renders the text based on the options provided. If no options are provided, it doesn't open.

Example

oMyPlugin.command('Engage.invite', {
	'type':'toast',
	'timeout':3000,
	'title':'Engage Title',
	'body':'Engage invite body content',
	'accept':'Yes',
	'decline':'No, thanks',
	'command': 'WebChat.open',
	'options':{'proactive'; true, 'userData': {'category': 'shoes'}}
});

oMyPlugin.command('Engage.invite',{
	'type':'toast',
	'timeout':3000,
	'title':'Engage Title',
	'body':'Engage invite body content',
	'accept':'Yes',
	'decline':'No, thanks'
}).done(function(response){

	// Act upon the received response code 

	switch(response){
	case 'accepted':oMyPlugin.command('WebChat.open'); 
			break;
	case 'declined': break;
	case 'closed': break;
	case 'timeout': break;
}

});

Options

Option	Type	Description	Accepted Values
type	string	Widget display type.	toast
timeout	number	Timeout integer in milliseconds.	n/a
title	string	String for widget title.	n/a
body	string	String for offer body text.	n/a
accept	string	String for Accept button text.	n/a
decline	string	String for Decline button text.	n/a
command	string	Command to execute.	n/a
options	object	Options related to the command provided.	n/a

Resolutions

Status	When	Returns
resolved	When engage invite is accepted by user.	accepted
resolved	When engage invite is declined by user.	declined
resolved	When engage invite widget is closed by user.	closed
resolved	When engage invite widget closes due to timeout.	timeout

offer

Opens an Offer Widget using the data sent through the command options provided below. It can include both rendering options and the actual data that needs to be displayed in the Offer Widget. If no options are provided, it will not open.

Example

 oMyPlugin.command('Engage.offer', {
 
 	mode:'overlay',
 	modal:true,
 	layout:'leftText',
 	title: 'GRAB WHAT YOU NEED!!',
 	headline:'We Got All!',
 	description:'Get free NextDay delivery on orders of $35 or more. Start shopping now!',
 
 	cta:{
 		text:'Join',
 		url:'<nowiki>https://www.genesys.com'</nowiki>,
 		target:'_blank'
 	},
 
 	image:{
 		src:'<nowiki>https://picsum.photos/id/237/300/300'</nowiki>,
 		alt:'Alternate Text for Image'
 	},
 
 	styles:{
 		closeButton:{
 			'color':'red'
 		}
 	}
 });

Options

Option	Type	Description	Accepted values	Default	Introduced/Updated
mode	string	Display type of Offer Widget	overlay, toaster	toaster	9.0.015.04
modal	boolean	Applicable only when mode is 'overlay'. A smokescreen will be shown in the background of overlay modal window. This window can be dismissed by clicking anywhere in the smokescreen area.	n/a	false	9.0.015.04
layout	string	Additional layout options supported for all modes.	minimal, leftText, rightText, topText, bottomText	leftText	9.0.015.04
headline	string	Offer title header text.	n/a	n/a	9.0.015.04
description	string	Offer body description text.	n/a	n/a	9.0.015.04
cta	object	An object containing html attributes and/or CXBus command for the CTA (call to action) button.	n/a	n/a	9.0.015.04
cta.text	string	CTA button text.	n/a	n/a	9.0.015.04
cta.url	string	URL string for the CTA button. Note: The URL must be properly defined with the complete Protocol URL Address. For example, https://www.genesys.com.	_blank, _parent, _self, _top, framename	n/a	9.0.015.04
cta.target	string	To specify where the URL should be opened.	n/a	n/a	9.0.015.04
cta.command	string	A CXBus command to execute.	n/a	n/a	9.0.015.04
cta.commandOptions	string	Options related to CXBUs command.	n/a	n/a	9.0.015.04
image	object	An object containing image tag attributes.	n/a	n/a	9.0.015.04
image.src	string	URL of the image.	n/a	n/a	9.0.015.04
image.alt	string	Alternate text for the image.	n/a	n/a	9.0.015.04
insertAfter	string	Applicable only in mobile mode. An id or class name of an html selector from the host page. The Offer will be inserted after this element. The value mentioned here should be preceded with the standard Class ('.') and ID selector ('#') character.	n/a	n/a	9.0.015.04
insertBefore	string	Applicable only in mobile mode. An id or class name of an html selector from the host page. The Offer will be inserted before this element. The value mentioned here should be preceded with the standard Class ('.') and ID selector ('#') character.	n/a	n/a	9.0.015.04
insertInto	string	Applicable only in mobile mode. An id or class name of an html selector from the host page. The Offer will be appended inside this element. The value mentioned here should be preceded with the standard Class ('.') and ID selector ('#') character.	n/a	n/a	9.0.015.04
styles	object	An Object containing styles for the Offer content.	n/a	n/a	9.0.015.04
styles.closeButton	object	An Object containing styles for the close button.	n/a	n/a	9.0.015.04
styles.closeButton.color	string	Color of the close button.	n/a	n/a	9.0.015.04
styles.closeButton.opacity	number	CSS 'opacity' property for the close button.	n/a	n/a	9.0.015.04
styles.overlay	object	An Object containing styles for the overlay container.	n/a	n/a	9.0.015.04
styles.overlay.top	string	CSS 'top' property for the overlay container.	n/a	n/a	9.0.015.04
styles.overlay.right	string	CSS 'right' property for the overlay container.	n/a	n/a	9.0.015.04
styles.overlay.bottom	string	CSS 'bottom' property for the overlay container.	n/a	n/a	9.0.015.04
styles.overlay.left	string	CSS 'left' property for the overlay container. Note: When all the position values are provided, the order of precedence will be Top, Right, Bottom and Left.	n/a	n/a	9.0.015.04
styles.overlay.center	boolean	Aligns overlay container to the center of the screen.	n/a	true	9.0.015.04
styles.offer	object	An Object containing styles for the Offer window.	n/a	n/a	9.0.015.04
styles.offer.backgroundColor	string	Background color of the Offer.	n/a	n/a	9.0.015.04
styles.offer.color	string	Text color of the Offer.	n/a	n/a	9.0.015.04
styles.offer.padding	string	Padding for the Offer container.	n/a	0	9.0.015.04
styles.title	object	An Object containing styles for the title.	n/a	n/a	9.0.015.04
styles.title.font	string	CSS 'font' property for the title.	n/a	n/a	9.0.015.04
styles.title.textAlign	string	CSS 'text-align' property for the title.	n/a	n/a	9.0.015.04
styles.headline	object	An Object containing styles for the header text.	n/a	n/a	9.0.015.04
styles.headline.font	string	CSS 'font' property for the header text.	n/a	n/a	9.0.015.04
styles.headline.textAlign	string	CSS 'text-align' property for the header text.	n/a	n/a	9.0.015.04
styles.description	object	An Object containing styles for the Offer description text.	n/a	n/a	9.0.015.04
styles.description.font	string	CSS 'font' property for the description text.	n/a	n/a	9.0.015.04
styles.description.textAlign	string	CSS 'text-align' property for the description text.	n/a	n/a	9.0.015.04
styles.ctaButton	object	An Object containing styles for call to action button in the Offer window.	n/a	n/a	9.0.015.04
styles.ctaButton.font	string	CSS 'font' property for the text in call to action button.	n/a	n/a	9.0.015.04
styles.ctaButton.textAlign	string	CSS 'text-align' property for the text in call to action button.	n/a	n/a	9.0.015.04
styles.ctaButton.background	string	CSS 'background' property for the call to action button.	n/a	n/a	9.0.015.04
styles.ctaButton.color	string	CSS 'color' property for the text in call to action button.	n/a	n/a	9.0.015.04
styles.ctaButton.fontSize	string	CSS 'font-size' property for the text in call to action button.	n/a	n/a	9.0.015.04

API Events

Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

Important

The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see Genesys Widgets extensions for more information about extending Genesys Widgets.

 var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
 
 oMyPlugin.subscribe('Engage.ready', function(e){});

Name	Description	Data	Introduced/Updated
ready	The Engage Widget is initialized and ready to accept commands on the bus.	n/a
opened	The Engage Widget has opened. Note: Applicable only to Engage.offer command	Metadata	9.0.015.04
CTA	When the user clicks on the CTA button in Engage Widget. Note: Applicable only to Engage.offer command	Metadata	9.0.015.04
hover	When the user first hovers over the Engage Widget. Note: Applicable only to Engage.offer command	Metadata	9.0.015.04
dismissed	When the user closes the Engage Widget by clicking on the close button. Note: Applicable only to Engage.offer command	Metadata	9.0.015.04
closed	The Engage Widget has closed. Note: Applicable only to Engage.offer command	Metadata	9.0.015.04

Metadata

Important

Applicable only for Engage.offer command.

Interaction Lifecycle

Every Offer Engage interaction has a sequence of events we describe as the 'Interaction Lifecycle'. This is a sequence of events that tracks progress and choices from the beginning of an interaction (opening Engage Offers), to the end (closing Offers), and every step in between.

The following events are part of the Interaction Lifecycle:

ready
opened
CTA
hover
dismissed
closed

Lifecycle Scenarios

An Interaction Lifecycle can vary based on each user's intent and experience with the Offer Engage Widget. Here are several sequences of events in the lifecycle that correspond to different scenarios.

The user opened the Offer Engage Widget but changed their mind and closed it without seeing the Offer details:

ready -> opened -> dismissed -> closed

The user opened the Offer Engage Widget, hovered over Offer details then closed it:

ready -> opened -> hover -> dismissed -> closed

The user opened the Offer Engage Widget and clicked on the button, which triggers CTA:

ready -> opened -> CTA -> closed

Tip

For a list of all Offer Engage events, see API Events.

Metadata

Each event in the Interaction Lifecycle includes the following block of metadata. By default, all values are set to false. As the user progresses through the lifecycle of an Offer Engage interaction, these values are updated.

The metadata block contains boolean state flags, timestamps, and elapsed times. These values can be used to track and identify trends or issues with interactions. During run-time, the metadata can help you offer a smart and dynamic experience to your users.

Reference

Name	Type	Description	Introduced/Updated
opened	integer (timestamp)	Timestamp indicating when the Offer was opened.	9.0.015.04
closed	integer (timestamp)	Timestamp indicating when the Offer was closed.	9.0.015.04
dismissed	integer (timestamp)	Timestamp indicating when the user dismissed the Offer by clicking the close button.	9.0.015.04
triggeredCTA	integer (timestamp)	Timestamp indicating when the CTA was triggered.	9.0.015.04
timeBeforeCTA	integer (milliseconds)	Total time in milliseconds from when the user opened the Offer to when the CTA is triggered.	9.0.015.04
timeFirstHover	integer (timestamp)	Timestamp indicating when the user first hovered over Offer.	9.0.015.04
timeBeforeHover	integer (milliseconds)	Total time in milliseconds from when the user opened the Offer to when the user first hovered over Offer.	9.0.015.04
timeElapsedHover	integer (milliseconds)	Total time in milliseconds when the user hovered over Offer.	9.0.015.04
elementClicked	string	Name of CTA element that was clicked ('button').	9.0.015.04