Offers

From Genesys Documentation
Jump to: navigation, search
This topic is part of the manual Widgets API Reference for version Current of Widgets.

Learn how to display a product or promotion on the customer's page.

Related pages:
Warning
This version of Offers is deprecated as of 9.0.015.11. See the Engage topic for information on the latest version. If you're currently using the Offers widget and need help, please reach out to your Genesys representative.


Overview

Use the Offers widget to display a product or promotion on the customer's web page. Offers includes many display modes, and options such as text, image and video. Other features include a timeout and video event binding support.

CXOffersOverlayImageLeftDark.png

Usage

Although you can configure an offer using static configuration, you must launched an offer using the following method:

Customization

The full configuration for the offers widget can be passed in as a JSON object to the open command.

If you call an empty open command, Widgets will attempt to open the last successful widget configuration.

Static configuration

You can define a static configuration for the Offers widget. It will be displayed by calling an empty open command.

3rd party video libraries

An optional parameter is available to enable YouTube and Vimeo videos to be displayed using the widget. This feature requires the loading of 3rd party libraries from YouTube and Vimeo. It is disabled by default in order to prevent 3rd party library loading.

Sidebar configuration

A SideBar configuration is available forOffers.

Namespace

The Offers plugin has the following namespaces tied up with each of the following types.

Type Namespace
Configuration Offers
i18n—Localization Offers
CXBus—API Commands & API events Offers
CSS .cx-offers


Screenshots

"Dark" Theme

Configuration

Description

Offers holds the _genesys.widgets.offers configuration namespace, which contains UI options.

Example

<br class="mw_emptyline">window._genesys.widgets.offers = {<br class="mw_emptyline_first">	offers: {<br class="mw_emptyline_first">		mode: 'overlay',<br class="mw_emptyline">		layout: 'leftText',<br class="mw_emptyline">		modal: false,<br class="mw_emptyline">		title: 'Offer Title',<br class="mw_emptyline">		headline: 'This is the offer's headline',<br class="mw_emptyline">		body: 'This is the offer's body',<br class="mw_emptyline">		button: 'Accept Offer',<br class="mw_emptyline">		cta:{<br class="mw_emptyline">			command: 'WebChat.open',<br class="mw_emptyline">			commandOptions: {<br class="mw_emptyline">				'proactive': true,<br class="mw_emptyline">				'userData': {'category': 'shoes'}<br class="mw_emptyline">			},<br class="mw_emptyline">			url: 'http://www.google.com',<br class="mw_emptyline">			target: '_blank'<br class="mw_emptyline">		},<br class="mw_emptyline">		video: 'https://www.youtube.com/watch?v=########',<br class="mw_emptyline">		autoplay: true,<br class="mw_emptyline">		videoOptions:{<br class="mw_emptyline">			autoplay: false,<br class="mw_emptyline">			loop: true<br class="mw_emptyline">		},<br class="mw_emptyline">		timeout: 11000,<br class="mw_emptyline">		styles:{<br class="mw_emptyline">			'.cx-body': {<br class="mw_emptyline">				'background-color': '#FFFFFF',<br class="mw_emptyline">				'color': '#008000'<br class="mw_emptyline">			}<br class="mw_emptyline">		},<br class="mw_emptyline">		position: {<br class="mw_emptyline">			'top': '100px', <br class="mw_emptyline">			'right': '30px', <br class="mw_emptyline">			'bottom': '30px', <br class="mw_emptyline">			'left': '100px'<br class="mw_emptyline">		}<br class="mw_emptyline">	},<br class="mw_emptyline_first">	downloadVideoLib: true<br class="mw_emptyline">};<br class="mw_emptyline">

Options

Name Type Description Default Required Accepted Values
offers.mode string Selects between overlay and toaster display modes. toaster false 'overlay', 'toaster'
offers.modal boolean Controls the smokescreen support for Offers overlay mode. If set to true, the smokescreen is added behind the offers window and blocks the user interaction from other webpage contents. If set to false, the smokescreen is not added. false false n/a
offers.layout string For the 'overlay' display container, sets the text on the right or left side of the image/video. leftText false 'leftText', 'rightText', 'minimal', 'stacked'
offers.title string The title of the widget; sets the title text in the widget header.

Note: Not available for stacked and minimal layouts.

n/a false n/a
offers.headline string A headline string displayed in larger text above the body. n/a false n/a
offers.body string The main text body of the offer. n/a false n/a
offers.button string A short string to be displayed inside the CTA button. n/a false n/a
offers.cta object An object containing the URL and/or CXBus command to open when the user clicks on the image or CTA button. n/a true n/a
offers.cta.command string A CXBus command to execute when the user clicks on the image or CTA button. n/a false n/a
offers.cta.commandOptions object An object containing options related to CXBus command. n/a false n/a
offers.cta.url string The URL to open when the user clicks on the image or CTA button.

Note: The URL must be properly defined with the complete Protocol URL Address. For example, https://www.genesys.com

n/a false n/a
offers.cta.target string The value to specify where to open the cta URL. _self false '_blank', '_parent', '_self', '_top', 'framename'
offers.image string A URL of an image to be displayed in the offer. n/a false n/a
offers.video string A URL of a YouTube or Vimeo video that displays in the offer. If an image URL is present the image replaces the video. Warnings appear in the JavaScript console if the video URL is not valid. n/a false n/a
offers.timeout integer Sets a timeout, in milliseconds, after which offers widget closes if there is no interaction. The minimum value is 10 seconds (10000 ms) to prevent the offer from flashing and disappearing while the user reads it. n/a false positive integers
offers.autoplay boolean Controls the video autoplay feature. If set to true, videos start playing automatically after loading. If set to false (default), videos will not autoplay.

Note: Autoplay feature may need to be enabled in certain IOS mobile devices.

false false true/false
offers.videoOptions object An object containing the adhoc configuration options specific to the player. The JSON definition placed here will enable/disable certain controls in the player.

Note: This must have options specific to the type of player (Youtube/Vimeo)

n/a n/a n/a
offers.position object An object containing the properties for positioning the offers window. The JSON definition placed here overrides the default position of the overlay.

Note: Positioning is disabled when modal option is set to true.

n/a false 'left', 'right', 'top', 'bottom'
offers.countdownText string A countdown text that displays before the countdown timer. If not set, the timer alone is displayed. n/a false n/a
downloadVideoLib boolean An option to enable loading of 3rd party video libraries. Needs to be set to true in order to show videos inside an offer.

Note: this option is only available in the static config, passing this along with the open parameter will not work.

false n/a true/false
styles object An object containing a custom CSS declarations. The JSON definition placed here overrides the CSS of elements visible inside the offers container. n/a n/a n/a

Localization

Important
The Offers plugin is different from other plugins, because all of the strings displayed in the UI are not hard coded and passed in via the Open command. Because of this, you need to learn how localization works under the hood in order to get it to work with offers. For information on how to set up localization, refer to the Localization Guide

Offers localization overview

Localization works by looking for specific query strings containing "@18n:" and replacing them with strings defined in your localization JSON file. You need to set up two things to get offers working:

  • Pass in the appropriate @18n: query strings to the open command
  • Update your JSON internationalization files

Open command usage

There are two ways you can pass an @18n: query string to the open command:

Default way:

'@i18n:offers.title'

Use the plugin name in the string to specify which plugin internationalization file to use.
Advanced and Flexible:

'@i18n:offers.offer1A.title'

The JSON file allows for multiple different nested definitions. This is extremely useful when trying to implement internationalization for multiple different offers. Please note that the offers JSON structure and the examples below are just one way to structure your offers JSON. You can structure your offers section of the i18n JSON however you desire.

Examples:

You must not use localization strings for the "Display Options" parameter section. These control how the content is displayed, but not the content itself.

The strings that need to be localized are under the Strings/Content section. These are the strings that the customer will see in your offer.

You can also localize the video URL (video), and image URL (image) if you want to link to localized content.

oMyPlugin.command('Offers.open', {
	// Display Options
	'mode':'overlay',
	'layout':'leftText',
	'downloadVideoLib' : true,
	'timeout' : 11000,
	'actionID':2,
	'media':'',
	// Strings/Content
	'title':'@i18n:offers.title',
	'headline':'@i18n:offers.headline',
	'body':'@i18n:offers.body',
	'button':'@i18n:offers.button',
	'cta':'@i18n:offers.cta',
	// URL strings
	'video':'@i18n:offers.video',
	'image':'@i18n:offers.image'
});


oMyPlugin.command('Offers.open', {
	// Display Options
	'mode':'overlay',
	'layout':'rightText',
	// Strings/Content
	'title':'@i18n:offers.offer1A.title',
	'headline':'@i18n:offers.offer1A.headline',
	'body':'@i18n:offers.offer1A.body',
	'button':'@i18n:offers.offer1A.button',
	'cta':'@i18n:offers.offer1A.cta',
	// URL strings
	'image':'@i18n:offers.offer1A.image'
});


oMyPlugin.command('Offers.open', {
	// Display Options
	'mode':'overlay',
	'layout':'stacked',
	// Strings/Content
	'headline':'@i18n:offers.offer1A.headline',
	'body':'@i18n:offers.offer1A.body',
	'button':'@i18n:offers.offer1A.button',
	'countdownText':'@i18n:offers.offer1A.countdownText',
	'cta':'@i18n:offers.offer1A.cta',
	// URL strings
	'image':'@i18n:offers.offer1A.image'
});


oMyPlugin.command('Offers.open', {
	// Display Options
	'mode':'overlay',
	'layout':'minimal',
	// Strings/Content
	'headline':'@i18n:offers.offer1A.headline',
	'body':'@i18n:offers.offer1A.body',
	'button':'@i18n:offers.offer1A.button',
	'countdownText':'@i18n:offers.offer1A.countdownText',
	'cta':'@i18n:offers.offer1A.cta',
	// URL strings
	'image':'@i18n:offers.offer1A.image'
});


oMyPlugin.command('Offers.open', {
	// Display Options
	'mode':'toaster',
	// Strings/Content
	'title':'@i18n:offers.offer1B.title',
	'headline':'@i18n:offers.offer1B.headline',
	'body':'@i18n:offers.offer1B.body',
	'button':'@i18n:offers.offer1B.button',
	'cta':'@i18n:offers.offer1B.cta'
});

Example JSON definition

This is an example JSON definition for offers that needs to go into your i18n JSON file. It is compatible with the open command examples above.

{
	"offers": {
		"title": "GenericTitle",
		"headline": "headline",
		"body": "GenericBody",
		"button": "GenericButton",
		"cta": {
			"url": "GenericCtaURL",
			"target": "_blank"
		},
		"offer1A": {
			"title": "title1A",
			"headline": "headline1A",
			"body": "body1A",
			"button": "button1A",
			"cta": {
				"command": "SendMessage.open",
				"commandOptions": {
					"userData": {
						"testing": "ok",
						"hoping": "please"
					}
				}
			},
			"image": "imageURL1A",
			"countdownText": "Offer will close in"
		},
		"offer1B": {
			"title": "title1B",
			"headline": "headline1B",
			"body": "body1B",
			"button": "button1B",
			"cta": {
				"command": "WebChat.open",
				"commandOptions": {
					"proactive": true,
					"userData": {
						"category": "shoes"
					}
				},
				"url": "ctaurl",
				"target": "_blank"
			}
		}
	}
}

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 Widgets Extensions for more information about extending Genesys Widgets.
var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('Offers.open');

configure

Internal use only. The main App plugin shares configuration settings to widgets using each widget’s configure command. The configure command can only be called once at startup. Calling configure again after startup may result in unpredictable behavior.

open

Opens the Offers Widget and renders an offer based on the JSON options provided. If no options are provided, it renders the default offer defined in the configuration.

Example

oMyPlugin.command('Offers.open', {
	mode:'overlay',
	modal:true,
	layout:'leftText',
	title:'Offer Title',
	headline:'This is the headline',
	body:'This is the body',
	button:'Accept Offer',
	cta:{
		command: 'WebChat.open',
		commandOptions: {'proactive': true,'userData': {'category': 'shoes'}},
		url: 'http://www.google.com',
		target: '_blank'
	},
	video:'https://www.youtube.com/watch?v=########',
	timeout: 11000,
	autoplay: true,
	videoOptions:{
		autoplay: false,
		loop: true
	},
	styles:{
		'.cx-body': {
			'background-color': '#FFFFFF',
			'color': '#008000'
		}
	}
});

Options

Option Type Description Accepted Values
mode string Widget display type overlay, toaster
modal boolean Smokescreen support option for overlay n/a
layout string Additional layout options for overlay leftText, rightText, minimal, stacked
title string String for widget title n/a
headline string String for Offer title header n/a
body string String for offer body text n/a
button string String for CTA button text n/a
cta object An object containing the URL and/or CXBus command for call to action n/a
cta.command string A CXBus command to execute n/a
cta.commandOptions object Options related to CXBUs command n/a
cta.url string - URL URL string for call to action.

Note: The URL must be properly defined with the complete Protocol URL Address. For example, https://www.genesys.com

n/a
cta.target string String to specify where to open the cta URL _blank, _parent, _self, _top, framename
image string - URL Image URL string n/a
video string - URL Video URL string, YouTube/Vimeo n/a
autoplay boolean Autoplay option for Video true, false
videoOptions object An object containing player-specific configuration options n/a
timeout number Timeout integer in ms n/a
countdownText string String for offer countdown text n/a
position object An object containing the properties for positioning the offers window left, right, top, bottom
styles object An object containing a custom CSS declarations n/a


Resolutions

Status When Returns
resolved When configuration options are provided, valid and set n/a
rejected When no valid configuration options are provided 'Invalid configuration; detailed CXBus warning'


close

Closes an open offers widget.

Example

oMyPlugin.command('Offers.close');

Resolutions

Status When Returns
resolved When the widget is closed n/a
rejected When the widget is already closed 'CXBus warning.'

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 use the global bus object.

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 Widgets Extensions for more information about extending Genesys Widgets.
var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('Offers.ready', function(e){ /* sample code */ });
Name Description Data
ready Offers is initialized and ready to accept commands n/a
opened The Offers Widget has opened Metadata
hover When the user first hovers over the offer Metadata
CTA When the user clicks on the element in an offer which triggers CTA Metadata
timeout The Offer has timed out Metadata
dismissed When the user closes the offer by clicking the close button Metadata
videoReady The video player has initialized and the video is ready to play in offer n/a
videoStarted The video has started playing in offer n/a
videoPlaying The video player plays the video in offer n/a
videoPaused The video has paused n/a
videoEnded The video has ended n/a
videoPlayed When the video is first played (manually or auto-played) Metadata
videoReady The video player has initialized and the video is ready to play in offer n/a
videoStarted The video has started playing in offer n/a
videoPlaying The video player plays the video in offer n/a
videoPaused The video has paused n/a
videoEnded The video has ended n/a
closed The Offers Widget has closed Metadata

Metadata

Interaction Lifecycle

Every Offers 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 Offers), to the end (closing Offers), and every step in between.

The following events are part of the Interaction Lifecycle:

ready
opened
CTA
videoPlayed
hover
timeout
dismissed
closed

Lifecycle scenarios

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

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

ready -> opened -> dismissed -> closed

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

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

The user opened Offer, and Offers timed out:

ready -> opened -> timeout -> closed

The user opened Offers and clicked on the link/button/image which triggers CTA:

ready -> opened -> CTA -> closed

The user opened Offer, watched the video then closed the Offer:

ready -> opened -> videoReady -> videoStarted -> videoPlayed-> dismissed -> closed
Tip
For a list of all Offers 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 a Offers 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
opened integer (timestamp) Timestamp indicating when the Offer was opened.
closed integer (timestamp) Timestamp indicating when the Offer was closed.
dismissed integer (timestamp) Timestamp indicating when the user dismissed the Offer by clicking the close button.
timedOut integer (timestamp) Timestamp indicating when the Offer timed-out and closed automatically.
triggeredCTA integer (timestamp) Timestamp indicating when the CTA was triggered.
timeBeforeCTA integer (milliseconds) Total time in milliseconds from when the user opened the Offer to when the CTA is triggered.
timeFirstHover integer (timestamp) Timestamp indicating when the user first hovered over Offer.
timeBeforeHover integer (milliseconds) Total time in milliseconds from when the user opened the Offer to when the user first hovered over Offer.
timeElapsedHover integer (milliseconds) Total time in milliseconds when the user hovered over Offer.
videoPlayed integer (timestamp) Timestamp indicating when the video started playing (either automatically or through user action).
videoWatchTime integer (milliseconds) Total time in milliseconds that the video was watched before closing the Offer.
elementClicked string Name of CTA element that was clicked ('image'/'link'/'button').
Retrieved from "https://all.docs.genesys.com/WID/Current/SDK/Offers-combined (2020-01-22 12:47:46)"