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
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.
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.
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
Remember to use the pc$ variable in conjunction with calls to PushCall functionality when using the no-conflict mode
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” |
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
| empty |
minuteInterval introduced in v1.0.3 | Integer | The interval used for the timeslots offered in the CallMeLater view (in minutes).
| 5 |
defaultPhonenumber | 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] | 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” |
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
| empty |
windowHeight | String | Height of the window to open in CSS style. | Depending on clientType |
windowType | String |
| “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).
| 5 |
defaultPhonenumber | 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] | 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
| empty |
windowHeight | String | Height of the window to open in CSS style. | Depending on clientType |
windowType | String |
| “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).
| 5 |
defaultPhonenumber | 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] | 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)
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.
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.
Tooltip support was added in v1.1.4. Use the following css for default tooltip styling. Feel free to customise.
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