jQuery client plugin v1.1.4

Introduction

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

PushCall offers 4 different services:

  • WebToPhone
  • CallMeNow/CallMeLater
  • Chat
  • Mail

Each service has its own client. Each of these clients can be embedded using the PushCall embed library provided. The library comes as extension to the popular javascript framework jQuery. In the following documentation the PushCall library will be referenced as PushCall jQuery plugin.

Loading the PushCall 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.

(warning) All versions of the jQuery plugin prior to v1.1.3 are not fully compatible with the jQuery versions 1.9.x and higher unless the the jQuery migrate library is used. Please see the jQuery migrate documentation for usage.

(warning) The default styling of the PushCall client has changed slightly. To support the tooltip for CallMeNow and CallMeLater clients we've added some additional HTML. See the styling documentation for details. 

A typical use of jQuery and the PushCall plugin looks as described in Example code 1.

 

 

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

 

 

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

 

 

(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: $.pcclient([settings])

A call to pcclient renders the PushCall client in the specified element in the DOM tree.

Parameters

This method has several required and optional parameters.

Required parameter(s)

Parameter name

Type

Value

targetname

String

Name of the PushCall target. This value is communicated to you or created by you using the Self Service Portal at http://login.pushcall.com

Optional parameters

Parameter name

Type

Value

Default

clientType

String

  • “cmn” for CallMeNow
  • “cml” for CallMeLater
  • “wtp” for WebToPhone
  • “mail” for Mail
  • “chat” for Chat

“cmn”

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

forceHTML

boolean

Force the use of an HTML version of the client[1] instead of the regular Flash version

false

locale

String

Locale ID used for localization of the text messages

Leave empty for auto detection based on browser language.

Example: “de” for German

empty

skin

String or Array

URL of the css document to load containing the skin for the HTML clients. Leave empty for default PushCall skin. By specifying an Array, multiple css can be used. This is useful for a combination of the HTML Chat and Mail client. See Example 4 – chat client with custom skin

(warning) This value is not relevant for any of the Flash clients.

empty

minuteInterval

introduced in v1.0.3

Integer

The interval used for the timeslots offered in the CallMeLater view (in minutes).

(warning) This value only applies to the HTML version of the CallMeLater client. Use with “forceHTML: true” to prevent unintended results.

5

defaultPhonenumber
introduced in v1.0.4

String

A predefined phone number that will be filled in the phone number input field. When used in conjunction with an autoCall value of true this number will be called automatically.

empty

autoCall[2]
introduced in v1.0.4

boolean

When set to true, the client will automatically start a call for the number specified in with the defaultPhonenumber parameter.

False

customData[3]

introduced in v1.1.2

String

When setting this value it will be displayed on top of the chat for a chat operator. This allows passing on additional customer information from the website.

empty



[1] Not available for the WebToPhone client

[2] Only available for CallMeNow clients

[3] Only available for the HTML Chat client

 

Example 1

This example describes embedding a PushCall CallMeLater client in an HTML page.  It uses a German locale and it’s forced to show the HTML version of the client.

Example 2 – defaultPhonenumber and autoCall

This example demonstrates embedding a PushCall CallMeLater client in an HTML page.  When the client is initialized it will automatically start dialing the number specified in the defaultPhonenumber parameter.

Example 3 – chat client

This example demonstrates embedding a PushCall Chat client in an HTML page. 

 

 

 

Example 4 – chat client with custom skin

This example demonstrates embedding a PushCall Chat client in an HTML page and specifying a custom skin. In this example we’re specifying an Array. The plugin will load both skins. This ensures displaying the Mail client correctly when it is loaded as a fallback for the Chat service.

 

Example 5 – chat client with customData parameter

This example demonstrates embedding a PushCall Chat client in an HTML page and specifying the customData parameter.

 

 

 

See in action: http://jsfiddle.net/pushcall/fSJ4f/embedded/result,html,js,css

Open PushCall client in popup: $.pcpopup([settings])

Opens the PushCall client in a popup or ‘popup-style’ window. This is convenient when you don’t want to show the client directly in your web page.

This function binds to a click event on the selected DOM element and opens the specified PushCall client.

Parameters

This method has several required and optional parameters.

Required parameter(s)

Parameter name

Type

Value

targetname

String

Name of the PushCall target. This value is communicated to you or created by you using the Self Service Portal at http://login.pushcall.com

Optional parameters

Parameter name

Type

Value

Default

clientType

String

  • “cmn” for CallMeNow
  • “cml” for CallMeLater
  • “wtp” for WebToPhone
  • “mail” for Mail
  • “chat” for Chat

“cmn”

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

forceHTML

boolean

Force the use of an HTML version of the client[1] instead of the regular Flash version

false

locale

String

Locale ID used for localization of the text messages

Leave empty for auto detection based on browser language.

Example: “de” for German

empty

skin

String or Array

URL of the css document to load containing the skin for the HTML clients. Leave empty for default PushCall skin. By specifying an Array, multiple css can be used. This is useful for a combination of the HTML Chat and Mail client. See Example 4 – chat client with custom skin

(warning) This value is not relevant for any of the Flash clients.

empty

windowHeight

String

Height of the window to open in CSS style.

Depending on clientType

windowType

String

  • “popup” for a browser popup
  • “popover” for a ‘lightbox’[2]
  • “new” for opening a new browser window/tab
  • “auto” will automatically choose between “popup” or “popover” based on browser capabilities

“auto”

windowWidth

String

Width of the window to open in CSS style.

Depending on clientType

minuteInterval

introduced in v1.0.3

Integer

The interval used for the timeslots offered in the CallMeLater view (in minutes).

(warning) This value only applies to the HTML version of the CallMeLater client. Use with “forceHTML: true” to prevent unintended results.

5

defaultPhonenumber
introduced in v1.0.4

String

A predefined phone number that will be filled in the phone number input field. When used in conjunction with the an autoCall value of true this number will be called automatically.

empty

autoCall[3]
introduced in v1.0.4

boolean

When set to true, the client will automatically start a call for the number specified in with the defaultPhonenumber parameter.

False

customData[4]

introduced in v1.1.2

String

When setting this value it will be displayed on top of the chat for a chat operator. This allows passing on additional customer information from the website.

empty



[1] Not available for the WebToPhone client

[2] Make sure to define a stylesheet for the lightbox. See popup.css for an example

[3] Only available for CallMeNow clients

[4] Only available for the HTML Chat client

Example

 

 

 

 

 

Checking availability: $.pcavailability([settings])

This method will help to present the PushCall tools based on their availability.

It will search for the pcServiceType attribute on DOM child nodes of the selected DOM element. Based on the availability of the service either the class “disable” will be added or removed from  the child node. The title attribute of this element will also be set.

Parameters

This method has several required and optional parameters.

Required parameter(s)

Parameter name

Type

Value

targetname

String

Name of the PushCall target. This value is communicated to you or created by you using the Self Service Portal at http://login.pushcall.com

Optional parameters

Parameter name

Type

Value

Default

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

forceHTML

boolean

Force the use of an HTML version of the client[1] instead of the regular Flash version

false

locale

String

Locale ID used for localization of the text messages

Leave empty for auto detection based on browser language.

Example: “de” for German

empty

popupEvent

String

A string containing one or more DOM event types, such as "click" or "submit," or custom event names. The popup will open when this event is fired.

“click”

skin

String or Array

URL of the css document to load containing the skin for the HTML clients. Leave empty for default PushCall skin. By specifying an Array, multiple css can be used. This is useful for a combination of the HTML Chat and Mail client. See Example 4 – chat client with custom skin

(warning) This value is not relevant for any of the Flash clients.

empty

windowHeight

String

Height of the window to open in CSS style.

Depending on clientType

windowType

String

  • “popup” for a browser popup
  • “popover” for a ‘lightbox’[2]
  • “new” for opening a new browser window/tab
  • “auto” will automatically choose between “popup” or “popover” based on browser capabilities

“auto”

windowWidth

String

Width of the window to open in CSS style.

Depending on clientType

minuteInterval

introduced in v1.0.3

Integer

The interval used for the timeslots offered in the CallMeLater view (in minutes).

(warning) This value only applies to the HTML version of the CallMeLater client. Use with “forceHTML: true” to prevent unintended results.

5

defaultPhonenumber
introduced in v1.0.4

String

A predefined phone number that will be filled in the phone number input field. When used in conjunction with the an autoCall value of true this number will be called automatically.

empty

autoCall[3]
introduced in v1.0.4

boolean

When set to true, the client will automatically start a call for the number specified in with the defaultPhonenumber parameter.

false

customData[4]

introduced in v1.1.2

String

When setting this value it will be displayed on top of the chat for a chat operator. This allows passing on additional customer information from the website.

empty


[1] Currently only available for the CallMeNow, CallMeLater and Chat clients

[2] Make sure to define a stylesheet for the lightbox. See popup.css for an example

[3] Only available for CallMeNow clients

[4] Only available for the HTML Chat client

Notes

There is no pcServiceType=”cml” for CallMeLater, but the availability of CallMeLater is combined with CallMeNow.
When the CallMeLater service is enabled for the specified target CallMeNow will always be shown as “available”. To be able to differentiate between CallMeNow and CallMeLater an additional class “pccml” is set on the DOM element with pcServiceType=”cmn”.

Example

 

 

 

 

 

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)

(warning) This functionality is currently only supported in the audio clients (CallMeNow, CallMeLater and WebToPhone) and HTML version of the chat client.

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.

 

 

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 “readytocall” or “callcreated” – it’s possible to track shows/usage of the PushCall tools with your tracker service of choice. E.g. Google Analytics.

 

 

 

(warning)Note the calls to _gaq.push which trigger the Google Analytics code to track the events.

Possible values for event parameter for Audio clients

event

eventData

description

initializing

target, callType

This event is fired when the client starts to load the library, skin and target information.

initialized

target, loadTime, callType

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

readytocall

target, callType

This event is fired when the AudioClient is initialized, the target is OK and the client is ready.

creatingcall

target, callType, (phoneNumber)1, (date) 2

This event is fired when the user starts a call and the request is send to the PushCall server.

callcreated

target, callType, (phoneNumber) 1, (date) 2

This event is fired when the PushCall server has accepted the the request to setup the call.

callfailed

target, callType, reason, (phoneNumber) 1

This event is fired when an error occurred during the creation of a call

callqueued

target, callType, queuePosition

This event is fired when the call was placed in the queue (the max. number of simultaneous channels has been reached).

ocstartingaudiotest 3

target

This event is fired when the audio test(speakers and microphone) is started.

ocaudiotestsuccess 3

target

This event is fired when the audio test has been completed successfully.

ocaudiotestfailed 3

target, audioTestStep

This event is fired when the audio test failed at any step in the test.

unknowntarget

target

This event is fired when the specified target is unknown.

closed

target, callType

This event is fired when the client is diaplyed outside the specified office hours.

notavailable

target, callType

This event is fired when the service is not available for this target.

error

target, reason

This event is fired when an error occurred. See the reason in the data object for more details.

1 Only with CallMeNow and CallMeLater
2 Only with CallMeLater
3 Only with WebToPhone 

Data in the eventData parameter

Name

Type

Description

target

String

The target name used by the client.

loadTime

Number

The time in milliseconds that it took to load all the required data.

callType

Int (ePCCallType)

Specifies the type of call for the event. See table below

phoneNumber

String

The phone number that is being used for the call.

date

Date

The requested date for the CallMeLater call.

reason

String

This contains more information why a call failed or an error occurred.

queuePosition

Numer

The position in the queue at the time of the call request.

audioTestStep

Int (ePCAudioTestStep)

Indicates at which point the audio test failed. See table below

 

Event sequence for Audio Clients

­

Possible values for event parameter for HTML Chat clients

event

eventData

description

initializing

target, clientType

This event is fired when the client starts to load the library, skin and target information.

initialized

target, clientType

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

requestchat

target, clientType

This event is fired when a new chat request was submitted.

chatanswered

target, clientType

This event is fired when the chat request was answered by an operator.

chatended

target, clientType

This event is fired when the PushCall server has accepted the the request to setup the call.

chattimeout

target, clientType

This event is fired when a chat request timed out

chatcanceled

target, clientType

This event is fired when the chat request was canceled

unknowntarget

target, clientType

This event is fired when the specified target is unknown.

closed

target, clientType

This event is fired when the client is opened when no chat operator is available

 

Data in the eventData parameter

Name

Type

Description

target

String

The target name used by the client.

clientType

String

The type of the client. For the HMTL chat client the value is “chat”.

Event sequence for HTML Chat client

Possible values for event parameter for HTML Mail clients

event

eventData

description

initializing

target, clientType

This event is fired when the client starts to load the library, skin and target information.

initialized

target, clientType

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

mailsent

target, clientType

This event is fired when the mail is sent successfully.

unknowntarget

target, clientType

This event is fired when the specified target is unknown.

notavailable

target, clientType

This event is fired when the service is not enabled for the specified targetname

error

target, clientType

This event is fired when mail sending failed

 

Data in the eventData parameter

Name

Type

Description

target

String

The target name used by the client.

clientType

String

The type of the client. For the HMTL chat client the value is “mail”.

Event sequence for HTML Mail client

Example

 

Styling HTML audio clients

The CallMeNow and CallMeLater HTML client comes with a default “PushCall” style design. By defining a custom CSS file it’s possible to apply custom styling.

The CallMeNow and CallMeLater client are build around an HTML structure consisting of several HTML elements, like DIVs, SPANs and SELECTs. Each of these elements has a class attribute defined. Depending on which of the clients is active an additional class ‘cmn’ or ‘cml’ will be applied to each element in the HTML structure.

 

 

(info) Tooltip support was added in v1.1.4. Use the following css for default tooltip styling. Feel free to customise.

(info) Addtional form-labels were added to comply to the Accessibility Standards. The default skin moves them out of sight.

 

 

 

 

Notes

With the introduction of v1.0.3 an additional (dynamic) class value is added to each element of the HTML client representing the state of the client. This allows designers/CSS implementers to differentiate the designs based on the state of the client. E.g. different backgrounds and even different sizes of the client are possible. See below for a table of all possible states and their respective class value:

class value

description

idle

The client is in the idle state and is ready for user input

cmn_success

A successful request for a CallMeNow call has been made

cml_success

A successful request for a CallMeLater call has been made

queued

The call had been placed in a queue. The HTML client is showing the number in the queue.

notification

The client is showing a notification message. E.g. the client is displayed outside opening hours or is temporarily not available

error

An error is displayed by the client

Only one of these values will be active at a time.

Table of Contents