jQuery Smart Engage plugin v1.0.1

Introduction

PushCall offers a jQuery plugin for easy integration of the PushCall SmartEngage functionality in your existing HTML document.

Figure 1 - SmartEngage panel in default PushCall skin. Locale in English.

Figure 1 - SmartEngage panel in default PushCall skin. Locale in English.

Loading the PushCall SmartEngage jQuery plugin

The PushCall jQuery plugin is loaded in conjunction with the jQuery library. It requires v1.6.4 of jQuery or higher to function properly. A typical use of jQuery and the PushCall plugin looks as described in Example code 1.

 

Example code 1 - Loading jQuery + PushCall Smart Engage plugin
<script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js'></script><!--Hosted on CDN-->
<script type='text/javascript' src='http://smartcontactbutton.pushcall.com/jquery.pushcall.smartengage-1.0.1.min.js'></script>

 

See Example code 2 for a very basic example of adding the PushCall CallMeNow client to an HTML page.

 

Example code 2 - Basic example of embedding the PushCall SmartEngage functionality in an HTML document
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
   <script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js'></script><!--Hosted on CDN-->
   <script type='text/javascript' src=jquery.pushcall.smartengage-1.0.1.min.js'></script>
</head>
<body>
   <div id='dcmn'></div>
   <script type="text/javascript">
    $(document).ready(function(){
      $.smartengage({
          popup: {
          url: 'http://yourwebsite.com/contactoptions.html',
          width: 300,
          height: 200
          }
 
      });
   });
   </script>
</body>
</html>

 

 

If you are using an older version of jQuery and are not able to upgrade to v1.6.4 or higher you can use jQuery’s “noConflict” mode as described in Example code 3

 

Example code 3 - Embedding the PushCall SmartEngage functionality in an HTML document using jQuery’s noConflict mode
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
   <script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js'></script><!--Hosted on CDN-->
   <script type="text/javascript">
    pc$ = $.noConflict(true);
   </script>
   <script type='text/javascript' src=jquery.pushcall.smartengage-1.0.1.min.js'></script>
</head>
<body>
   <div id='dcmn'></div>
   <script type="text/javascript">
    pc$(document).ready(function(){
      pc$. smartengage({
          popup: {
          url: 'http://yourwebsite.com/contactoptions.html',
          width: 300,
          height: 200
          }
      });
   });
   </script>
</body>
</html>

(warning)  Remember to use the pc$ variable in conjunction with calls to PushCall functionality when using the no-conflict mode

(warning) If your site requires the use of assets (scripts, images, etc.) that are hosted on a location with SSL support , use the https equivalent of above URL’s. The PushCall jQuery plugin is hosted on a CDN that supports both http and https requests.

 

Embedding the PushCall client: $.smartengage([settings])

Adds the SmartEngage  panel to the HTML page.

Parameters

Optional parameters

Parameter name

Type

Value

Default

animation

String

  • “slide” for slide up/down effect
  • “fade” for fade in/out effect

“slide”

context

object

This object will be made the context of the event callbacks.

undefined

eventCallback

function

Method to call when an event occurs. Also see chapter Events.

undefined

popup

object

Structure with the settings for the popup that will be displayed when user accepts. Possible settings are:

  • “url”. URL of the page to show in popup
  • “width”. The width of the popover in pixels
  • “height”. The height of the popover in pixels
  • “bindOn”[1]. A jQuery object which to bind the click event on. When a click event is triggered on this object the overlay is opened.

{ url: ‘about:blank’,

width: 800,

height:400}

position

String

Position of the engage popup window. Possible values:

  • bottomright
  • bottomleft

bottomright

margin

Integer

Margin in pixels to the nearest page border

20

locale

String

Locale ID used for localization of the text messages

Leave empty for auto detection based on browser language.

Example: “nl” for Dutch

empty

skin

String

URL of the css document to load containing the skin for the smart engage popup and the popover

Default skin location

engageDelay

Integer

The time in seconds before the engage popup is displayed .

0

cooldownPeriod

Integer

The time in seconds the popup will not be displayed to the page vistor once the visitor has closed or declined.

0

userMessages

Object

Structure with additional or alternative texts to use in the engage popup. By default Enlish, German and Dutch translations are available. See example below for available labels.

 


[1] Available since v1.0.1

Example 1

 

 

Javascript:
$(document).ready(function(){
$.smartengage({
      animation      : 'slide',              
      position       : 'bottomright',        
      margin         : 100,                 
      popup : {
          url          : 'http://buttons.pushcall.com/cmn/pushcall',
          width        : 360,       
          height       : 260  
      },
      skin           : 'http://smartcontactbutton.pushcall.com/css/smartengage.css',
      locale         : 'no',    
      engageDelay    : 3,     
      cooldownPeriod : 10,   
      userMessages:             
      {
        "no" : {
          "CAPTION"        : 'Kan vi hjelpe deg?',
          "BUTTON_ACCEPT"  : 'Ja, takk!',
          "BUTTON_DECLINE" : 'Nei takk'
        }
      },
      context       : this,                       
      eventCallback : function(event, eventData){ 
        console.log("eventCallback: %o %o", event, eventData);
      }
    });
});

 

Example 2 – using bindOn

Available since v1.0.1

 

 

HTML:
<a href="#" class='openLink'>open the overlay</a>

 

 

Javascript:
$(document).ready(function(){
$.smartengage({
      animation      : 'slide',              
      position       : 'bottomright',        
      margin         : 100,                 
      popup : {
          url          : 'http://buttons.pushcall.com/cmn/pushcall',
          width        : 360,       
          height       : 260,  
          bindOn       : $('.openLink')  

      },
      skin           : 'http://smartcontactbutton.pushcall.com/css/smartengage.css',
      locale         : 'no',    
      engageDelay    : 3,     
      cooldownPeriod : 10,   
      userMessages:              
      {
        "no" : {
          "CAPTION"        : 'Kan vi hjelpe deg?',
          "BUTTON_ACCEPT"  : 'Ja, takk!',
          "BUTTON_DECLINE" : 'Nei takk'
        }
      },
      context       : this,                       
      eventCallback : function(event, eventData){ 
        console.log("eventCallback: %o %o", event, eventData);
      }
    });
});

 

Events

The events thrown by the eventCallback mechanism can e.g. be used to notify trackers – like Google Analytics – to track the use of the PushCall services. By using this functionality you can use your online tracking service of choice (as long as it can be used in javascript)

Defining a listener

By defining a callback function (aka event listener) in javascript and passing this function in the settings, it will receive event notifications of any of the relevant state changes.

First step is to define the eventCallback function.

 

Javascript:
function eventHandler( event, eventData ){
//Place your event handling code here.
}

 

The event parameter is a string. The eventData is an object containing relevant data based on the event thrown. See tables below for more information on the possible states and data passed in the eventData object.

Using a tracker

By listening to a specific state – like “show” or “click” – it’s possible to track shows/usage of the PushCall SmartEngage functionality with your tracker service of choice. E.g. Google Analytics.

Example:

 

<script type="text/javascript">
  // Start standard Google Analytics code
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', '<PUT_YOUR_GOOGLE_ANALYTICS_ID_HERE>']);
  _gaq.push(['_setDomainName', '<PUT_YOUR_DOMAINNAME_HERE>']);    
  _gaq.push(['_trackPageview']);
 
  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
  // End standard Google Analytics code
</script>
<script type="text/javascript">
  // Start PushCall event listener declaration
  function pcEventListener( event, eventData ){
    switch (event){
      case 'show':
         _gaq.push(['_trackEvent', 'SmartEngage displayed']);
         break;
      case 'click':
         _gaq.push(['_trackEvent', 'SmartEngage action by user: ' + eventData.action]);
         break;
    }
  }
</script>

 NB. Note the calls to _gaq.push which trigger the Google Analytics code to track the events.

Possible values for event parameter

Event

eventData

description

show

language, delay

This event is fired when the SmartEngage panel is shown to the user.

click

action

This event is fired when the initializing is complete and the required data is loaded.

 

Data in the eventData parameter

Name

Type

Description

language

String

The locale used

delay

integer

The time in seconds before the SmartEngae panel was shown after document completed loading

action

String

The action took by the user (accept, decline, close_overlay, open). See Actions table below

Actions

Name

Description

accept

The user clicked the “accept” button in the SmartEngage popup

decline

The user clicked the “decline” button in the SmartEngage popup

close_overlay

The user closed the overlay by clicking on the close button or outside the overlay area

open[1]

The user clicked a link that was bind to which triggers opening the overlay.



[1] Available since v1.0.1 

 

Skinning

The plugin features the option to skin it according to your needs. First of all there’s an option to change the text in de labels through the “userMessages” parameter. If you want to change the colors or other elements of the graphic appearance you can provide an alternate CSS file.

UserMessages

By defining  your custom texts through the userMessages parameter you can change the default text labels or add an extra language. By default the SmartEngage plugin comes in English and Dutch.

There are 3 labels:

  • CAPTION
  • BUTTON_ACCEPT
  • BUTTON_DECLINE

The current value of the labels is:

Label

Englilsh

Dutch

CAPTION

Can we help you?

Kunnen we u helpen?

BUTTON_ACCEPT

Yes, please.

Ja, graag.

BUTTON_DECLINE

No, thank you.

Nee, bedankt.

Example - Creating custom button values

Javascript:
$(document).ready(function(){
$.smartengage({
      locale         : 'en',   
      userMessages:             
      {
        "en" : {
          "CAPTION"        : 'May I help you?',
          "BUTTON_ACCEPT"  : 'Oh yes!',
          "BUTTON_DECLINE" : 'Go away!'
        }
      }
    });
});

CSS Skin

The SmartEngage plugin loads a default stylesheet (CSS) b y default. To change it you can use the skin parameter to provide a URL to a location of a CSS file.

 

 

Current CSS file:
/* SMART ENGAGEMENT */
.pc_smrt_eng { display:none;  z-index:10;}
.pc_smrt_eng { position:fixed; bottom:0px; width:233px; height:167px; background:url(img/pc_smrt_eng.png); font-family:"open sans", arial, helvetica; }
 
.pc_smrt_eng .title { position:absolute; left:25px; top:15px; width:100px; font-size:17px; line-height:20px; font-weight:600; color:#ff6600; }
 
.pc_smrt_eng button { border:none; cursor:pointer; }
.pc_smrt_eng button::-moz-focus-inner { border:0px; padding:0px; }
 
.pc_smrt_eng button.close { position:absolute; right:11px; top:11px; width:11px; height:11px; background:url(img/buttonclose.png) top; text-indent:-999em; }
.pc_smrt_eng button.yes { position:absolute; left:17px; top:88px; width:110px; height:27px; line-height:27px; background:url(img/buttonyes.png) top; color:white; }
.pc_smrt_eng button.no { position:absolute; left:17px; top:120px; width:110px; height:27px; line-height:27px; background:url(img/buttonno.png) top; color:#8c8c8c; }
.pc_smrt_eng button:hover { background-position:bottom; }
 
.pc_overlay { display:none; position:relative;  z-index:10;}
.pc_overlay .overlay { position:fixed; top:0; left:0; width:100%; height:100%; background:black; zoom:1; filter:alpha(opacity=70); opacity:0.7; }
.pc_overlay .dialog { position:fixed; top:50%; left:50%; background:white; }
.pc_overlay .dialog .close-overlay { position:absolute; top:-15px; right:-15px; width:30px; height:30px; background:url(img/close-overlay.png); }
.pc_overlay .dialog iframe { width:100%; height:100%; }