Widget Custom Actions
Change, add or remove built-in and custom actions on a per-page / per-website basis
The LiveSite SDK offers different methods to edit the actions that appear on your website. You can even change the LiveSite Invite main action according to the visiting users, time of day, etc'.
Here are some common ways to use custom actions:
For LiveSite built-in actions:
- Hiding \ Showing some of the actions on a per-site \ per page basis
- Passing default parameters into one of the LiveSite built-in actions
- Using the same action type with two different names \ icons on the widget (e.g., "schedule a face-to-face meeting" and "schedule an online meeting")
For external actions:
- Adding an action of your own to the widget design (e.g. link to your Facebook Page, "join my mailing list")
Manipulating the LiveSite actions will take effect everywhere the actions are used: the Actions Menu, the LiveSite Invite inline actions, and the Collapsed Actions Menu beside the LiveSite Invite main action, depending on the LiveSite configuration.
Understanding The Actions Object
The LiveSite actions configuration specifies which actions are to be rendered. The following represents a LiveSite where all the actions are turned on:
actions : [{
name : 'schedule',
action : 'schedule',
text : 'Schedule Now',
icon : 'cal'
}, {
name : 'contact',
action : 'contact',
text : 'Leave Your Details',
icon : 'env'
}, {
name : 'call',
action : 'call',
options : 'number: 1800000000',
text : 'Call 1-800-000-000',
icon : 'phone'
}, {
name : 'pay',
action : 'pay',
text : 'Make a Payment',
icon : 'credit-card'
}, {
name : 'document',
action : 'document',
text : 'Send a Document',
icon : 'doc'
}]
Each action object consists of the following attributes:
Attribute | Description |
---|---|
name | The name of the action, should be a valid css class name, no spaces allowed |
action | Can be one of schedule, contact, call, pay, document or can omitted for custom action |
options | Semi-colon separated options (e.g. option1:value;option2:value). See Embedding Actions for per-action options. (optional) |
text | Caption describing the action |
icon | Name of the icon to show for the action, we have hand-picked relevant icons from the Elusive Webfonts Icons. To see a full list of the icons go here. |
url | URL for custom actions (optional) |
target | For custom actions with a URL, can be blank_, self, __parent, _top, framename (optional) |
lightbox | For custom actions with a URL, whether to use the LiveSite built-in Lightbox, true/false (optional) |
Adjusting Existing Actions
The following JS allows you to customize the actions that appear on your widget on the per-site \ per page basis: show \ hide actions, present their parameters, or change their names.
For example, the following code presets the email, first name, and last name according to GET parameters passed to the page:
window.liveSiteAsyncInit = function() {
LiveSite.on('beforeRender', function() {
console.log(LiveSite);
// Here we are iterating over the actions object and modify it,
for (const action of LiveSite.config.actions) {
console.log(action);
// Now it is possible to modify the widget actions
// Here for instance, we are chaining another query param to the actuin URL
action.url = `${action.url}&custom_param_1=custom_param_value_here`
}
});
// end of actions manipulation
LiveSite.init({
id : 'your-livesite-widget-id_or-business-uid'
});
};
(function(d, s, id){
var js, fjs = d.getElementsByTagName(s)[0],
p = 'https://',
r = Math.floor(new Date().getTime() / 1000000);
if (d.getElementById(id)) {return;}
js = d.createElement(s); js.id = id;
js.src = p + "d2ra6nuwn69ktl.cloudfront.net/assets/livesite.js?" + r;
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'livesite-jssdk'));
// rest of embed code goes here ...
Custom params in action URL
If needed, you can pass additional info to the action URL, by appending value to any of the below query params:
- custom_param_1
- custom_param_2
- custom_param_3
- custom_param_4
- custom_param_5
Customizing Built-in Actions
To customize and add built-in actions to the LiveSite, you can push another action object to the actions array, and it will be rendered.
You manipulate the actions as you like and add them to any location on the widget; the rendering follows the array order.
For example, the following code adds another scheduling type button with a filter to show only services at the office:
window.liveSiteAsyncInit = function() {
// Make changes after configuration has been loaded
// but before the widget is rendered
LiveSite.on('beforeRender', function() {
// The new action can added at any position and the rendering
// will follow the array order
LiveSite.config.actions.push({
name: 'office_appointment',
type: 'schedule',
icon: 'briefcase',
options: 'service_name:office',
text: 'Appointment at the Office'
});
});
LiveSite.init({
id : 'your-livesite-widget-id'
});
};
// rest of embed code goes here ...
Adding Your Own Custom Actions
You can use the look and feel of the LiveSite widget to promote calls to action that do not lead to one of inTandem built-in actions.
For example, the following JS will add an action to your widget that sends site visitors to your book's page on Amazon:
window.liveSiteAsyncInit = function() {
// Make changes after configuration has been loaded
// but before the widget is rendered
LiveSite.on('beforeRender', function() {
// Notice the lightbox:true attribute which uses the LiveSite built-in
// lightbox which gives a slick and consistent look & feel. You may
// as well pass target:_blank instead to open the action in a new tab
LiveSite.config.actions.unshift({
name: 'buy_my_book',
icon: 'book',
url: 'http://www.amazon.com/mybook',
lightbox: true,
text: 'Buy My Book (20% Discount)'
});
});
LiveSite.init({
id : 'your-livesite-widget-id'
});
};
If the action triggers some JavaScript code, you can omit the URL attribute and bind your JavaScript code to the livesite-action-buy_my_book class (where buy_my_book is your action name). In that case, make sure you bind the callback correctly as the LiveSite might render after your document's "ready" code has been called.
Both examples assume jQuery is used:
// Option 1 (preferred) - using the LiveSite render event
window.liveSiteAsyncInit = function() {
// Make changes after configuration has been loaded
// but before the widget is rendered
LiveSite.on('render', function() {
$('.livesite-action-buy_my_book').on('click', function() {
buyMyBook(); // Run the "Buy my Book" code
});
});
// .. rest of embed code
}
// Option 2 - using the document.ready event
$(function() {
$("body").on('.livesite-action-buy_my_book', 'click', function() {
buyMyBook(); // Run the "Buy my Book" code
});
});
Customizing LiveSite Invite Main Action
You can change the main action on the widget per page or per a specific business logic.
For example, the following code will show a Call button during working hours and a Leave Details button off working hours:
window.liveSiteAsyncInit = function() {
// Make changes after configuration has been loaded
// but before the widget is rendered
LiveSite.on('beforeRender', function() {
// any logic can go here
var showCall = (new Date().getHours() > 8 && new Date().getHours() < 18);
// You can switch between any of the actions, whether they are
// built-in or custom actions. You can even adjust on the text or
// options
if (showCall) {
LiveSite.config.activeEngageAction = 'call';
LiveSite.config.activeEngageActionText = 'Call 1-800-800-800'
LiveSite.config.activeEngageActionOptions = 'number:1-800-800-800'
} else {
LiveSite.config.activeEngageAction = 'contact';
LiveSite.config.activeEngageActionText = 'Leave Details'
LiveSite.config.activeEngageActionOptions = ''
}
});
LiveSite.init({
id : 'your-livesite-widget-id'
});
};
Updated 2 months ago