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:

AttributeDescription
nameThe name of the action, should be a valid css class name, no spaces allowed
actionCan be one of schedule, contact, call, pay, document or can omitted for custom action
optionsSemi-colon separated options (e.g. option1:value;option2:value). See Embedding Actions for per-action options. (optional)
textCaption describing the action
iconName 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.
urlURL for custom actions (optional)
targetFor custom actions with a URL, can be blank_, self, __parent, _top, framename (optional)
lightboxFor 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() {
    
  // Make changes after configuration has been loaded 
  // but before the widget is rendered
  LiveSite.on('beforeRender', function() {
    var i, query_params = LiveSite.fn.getQueryParams();           

    // Here we are iterating over the actions object and modify it,
     // any modification that follows the attributes table above can
     // be made
     for (i=0; i<LiveSite.config.actions.length; i++) {
        if (LiveSite.config.actions[i].name == "schedule") {
   				LiveSite.config.actions[i].options = 
            "email:"       + query_params["email"] + 			 
            ";first_name:" + query_params["first_name"] +
            ";last_name:"  + query_params["last_name"];
        }
     }
  });

  LiveSite.init({
    id : 'your-livesite-widget-id'
  });
};

// rest of embed code goes here ...

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'
  });
};