Class: Engagement

Overview

Events:

END

Triggered when this engagement has ended.

MEDIA_UPGRADE_OFFER

Triggered when the Operator offers to the Visitor the choice of upgrading the engagement to a higher media. Until the offer has not been responded to, neither the Operator nor Visitor media will change.

The event listener will be called with an MediaUpgradeOffer instance. See MediaUpgradeOffer documentation for examples on how to implement a listener for this event.

FOCUS

Triggered when Operator wants Visitor to focus on certain part of the application. The event listener will be called with one of Engagement.FOCUS_TARGETS:

  • CHAT is used when Operator wants Visitor to focus on chat area;
  • COBROWSER is used when Operator wants Visitor to focus on cobrowsing area.

MEDIA_STATE_CHANGE

Triggered when operator or visitor media state changes. The event listener will be called with a MediaState instance.

STATE_CHANGE

Triggered when state of the engagement changes. The event listener will be called with an EngagementState instance.

Triggered when an Operator requests to CoBrowse with the Visitor. Accepting this request means that the Operator can fill inputs, click links etc in the Visitor's stead. This event might be triggered multiple times. Declining one request does not prevent further requests from being sent by the Operator. The event listener will be called with a CobrowsingRequest instance.

MEDIA_PERMISSION_REQUEST

Triggered when SaleMove platform requests access to Visitor's media device. For example, browser's default media permission prompt can sometimes be hard to notice, so this event can be used to draw Visitor's attention to browser's media permission prompt. The event listener will be called with a MediaPermission instance.

WIDGET_MEDIA_UPGRADE_REQUEST

Triggered when the Visitor requests a media upgrade from the sm-engaged-visitor widget. As explained in the example below, additional information may be asked from the Visitor before continuing with the upgrade.

For example, during a 'text' engagement the microphone button is often used to allow upgrades to both 'phone' and 'audio' media. When the Visitor presses the microphone button this event will be triggered with 'audio' media and the application usually prompts the user to decide whether they would like to use their phone or their computer's microphone. If they select the phone option they are usually further prompted to provide their phone number. Depending on the design of the application, these prompts could come in the form of modal windows or simple text fields and buttons next to the widget. Because of the large number of interaction options the widget avoids forcing a specific approach and instead allows the application to use any approach that makes most sense in its context.

The event listener will be called with an WidgetMediaUpgradeRequest instance. See its documentation for examples on how to implement a listener for this event.

CUSTOM_COMMAND

Triggered when custom command is triggered when OmniGuide receives custom command response type or when send custom command endpoint is called. The event listener will be called with an instance of CustomCommand.

Examples:

Add custom command event listener and access custom command properties

sm.getApi({ version: 'v1' }).then(function (salemove) {
   var customCommandEventListener = function (engagement) {
     engagement.addEventListener(engagement.EVENTS.CUSTOM_COMMAND, function (customCommand) {
       console.log('custom command properties', customCommand.properties);
     })
  }

  salemove.addEventListener(salemove.EVENTS.ENGAGEMENT_START, customCommandEventListener);
 });

Property Summary

(number) engagementId

A unique identifier for the engagement

(Chat) chat

Chat instance connected to this engagement

(Operator) operator

(MediaState) mediaState

The current media used by the Operator and the Visitor.

(Cobrowser) cobrowser

An object with Cobrowser specific functionality.

(boolean) isReestablishing

True if the Engagement has been reestablished false otherwise.

Variables Summary

EVENTS =
{
  END: 'end',
  STATE_CHANGE: 'state_change',
  MEDIA_UPGRADE_OFFER: 'media_upgrade_offer',
  FOCUS: 'focus',
  MEDIA_STATE_CHANGE: 'media_state_change',
  COBROWSING_REQUEST: 'cobrowsing_request',
  MEDIA_PERMISSION_REQUEST: 'media_permission_request',
  WIDGET_MEDIA_UPGRADE_REQUEST: 'widget_media_upgrade_request',
  CUSTOM_COMMAND: 'custom_command'
}
FOCUS_TARGETS =
{
  CHAT: 'chat',
  COBROWSER: 'cobrowse'
}
MEDIA_TYPES =
{
  TEXT: 'text',
  AUDIO: 'audio',
  PHONE: 'phone',
  VIDEO: 'video'
}

Instance Method Summary

Instance Method Details

# (Promise) upgrade(media, options)

Upgrades the engagement to a higher media.

Parameters:

  • media ( string ) The media to upgrade to. Must be one of the following: 'phone', 'audio', 'video'.
  • options ( Object )

Options Hash: (options):

  • phoneNumber ( ?string ) The Visitor's phone number in E.164 format to use when media to upgrade to is 'phone'.
  • oneWay ( ?boolean ) When set to true, only the Operator will be upgraded to the requested media, while the Visitor's media will remain unchanged. This option is invalid if the specified media is 'phone'. See also: One-Way.

Returns:

  • ( Promise ) — Fulfilled with an empty object or rejected with an Error if the process fails for any reason. The Error may have one of the following causes: INVALID_INPUT, INTERNAL_ERROR, NOT_SUPPORTED.

# (Promise) iframePage(options)

Reloads the current page in an iframe.

The page must allow iFraming on the same origin with the X-Frame-Options: https://tools.ietf.org/html/rfc7034.

Examples:

var engagementRequest = salemove.requestEngagement('text');

engagementRequest.engagementPromise.then(function(engagement) {
  engagement.iframePage({
    keptElementSelectors: [
      ".important",
      "div#my-sidebar",
      "script[src*='my-javascript']",
      "link[href*='my-css']"
    ]
  }).then(function(iframedPage) {
    engagement.addEventListener(engagement.EVENTS.END, function() {
      iframedPage.deframe();
    });
  });
});

Parameters:

  • options ( Object )

Options Hash: (options):

  • keptElementSelectors ( Array<string> ) An array of element selectors as defined for document.querySelector to keep attached to the page. All the specified elements, their child elements and parents will be kept in the DOM. All other elements will be removed. All CSS and SCRIPT elements that are required for the engagement widgets must be specified.

Returns:

  • ( Promise ) — Fulfilled with IframedPage or rejected with an Error. The Error may have one of the following causes: INTERNAL_ERROR.

# (Promise) getSurvey()

Get engagement Survey

Examples:

var engagementRequest = salemove.requestEngagement('text');

engagementRequest.engagementPromise.then(function(engagement) {
  engagement.addEventListener(engagement.EVENTS.END, function() {
    var gotSurvey = function(survey) {
      var questions = survey.questions;
      // show questions to the visitor
    };

    engagement.getSurvey().then(gotSurvey);
  });
});

Returns:

  • ( Promise ) — Fulfilled with a Survey or rejected with an Error

# (Promise) end()

Ends the engagement.

Returns:

  • ( Promise ) — Fulfilled with an empty object or rejected with an Error if the process fails for any reason. The Error may have one of the following causes: INTERNAL_ERROR.

# (Promise) notifyOfFocusChange()

Notifies Operator about the part of the application that the Visitor is currently focused on.

Some applications may choose to de-emphasize or minimize its chat views at times to avoid obstructing the user from browsing the rest of the application. This is particularly relevant on mobile devices where screen space is scarce and chat views often cover the entire screen. (Chat views in this case refer to views that enable both text and audio-visual communication.)

Applications that do adopt this behavior should use this endpoint whenever its chat views are either emphasized or de-emphasized. Calling this endpoint with CHAT lets the Operator know that the Visitor is focused on the chat views of the application and will likely immediately see any messages sent by the Operator. Calling it with COBROWSER, however, lets the Operator know that the visitor is NOT actively looking at the chat views and may not immediately notice new messages.

Applications using this endpoint should also use the FOCUS event to allow the Operator to request on the Visitor's behalf that the application change focus.

Parameters:

  • focusTarget ( string ) The part of the application the Visitor is currently focused on or which is currently emphasized. Must be one of Engagement.FOCUS_TARGETS.

Returns:

  • ( Promise ) — Fulfilled with an empty object or rejected with an Error if the process fails for any reason. The Error may have one of the following causes: INVALID_INPUT, TIMEOUT, INTERNAL_ERROR.

# (void) addEventListener(type, listener)

This method allows registration of event listeners on the Engagement.

If a listener is added while the Engagement is processing an event, it will be not triggered with the current event.

If multiple identical listeners are registered on the same event type the duplicate instances are discarded. They do not cause the listener to be called twice and do not need to be removed with the removeEventListener method.

Parameters:

  • type ( string ) The event type for which the user is registering. Must be one of Engagement.EVENTS.
  • listener ( function ) The listener function that will be called when the event occurs.

# (void) removeEventListener(type, listener)

This method allows the removal of event listeners from the Engagement.

If an event listener is removed while the Engagement is processing an event, it will not be triggered with the current event.

An event listener is never invoked after being removed.

Calling removeEventListener with arguments which do not identify any currently registered listener has no effect.

Parameters:

  • type ( string ) The event type for the listener being removed.
  • listener ( function ) The event listener to be removed.

    Quickly fuzzy find classes, mixins, methods, file:

    Control the navigation frame:

    You can focus and blur the search input: