TwentyThree comes with a number of generic actions or call-to-action overlays built in, for example text boxes, images, videos, ads and products. Custom actions allow you to create new action types for video players—which can then be placed on any video by any editor on the site.

This offers a great degree of flexibility. For example, at TwentyThree we have a number of case videos where we want to show a quote in the player during playback—and we have created an action for that. We also want to introduce viewers to TwentyThree and suggest they start a free trial of the product; so we've created a custom Signup action to be easily applied across videos. Other examples include integration with CRM systems or shopping carts; including social media timelines into the player; or creating data-driven video recommendations.

Setting up new custom actions requires a custom player code to handle the new action type. However, when the initial setup is complete, anyone can use the new action type just as easily as the built-in types.

Creating new custom actions

Custom actions are created from Settings → Actions → Configure custom actions. When you have clicked the Add a new custom action button you can configure the new action:

• The Key is used internally to identify the action type and you'll use this when you set up action handlers in the player. The Name and Description though is meant for end-users to understand the nature of your new type.
• Timeline options let you choose when users can select exactly where to place the action on the timeline—or place the action before or after the video.
• Set positioning controls whether your action type has a pre-set position on top of the video, or if users should be able to set the exact width, height and placement.

When you've set up the action type, you can define properties for the action. Each property has a type (for example text, image or video) and users will be asked to fill in input fields for each of these properties. You can also choose to reuse helpful, common property types such as font size, background color, background opacity, pause mode and so on.

Handling custom actions in players

Custom actions are displayed using custom player code. When you've created a new player, open up the actions module and add two handlers—one for showing your new action and one for hiding it. For example for a quote action:

$this.showHandlers['quote'] = function(action){
   // Place custom code for building the action here
   // The action container is created and placed automatically
   action.container.html(action.quote);
}
$this.hideHandlers['quote'] = function(action){
   // Place custom code for handling action hiding here. 
   // The action container itself will be removed after this function returns.
}

This code goes inside the actionsHandlers.js file in the actions folder in the player builder. You will also find the code for how we handle the built-in actions.

Using custom actions

After the custom action type has been created and the player built, the type can be used by any user in the exact same way as built-in actions.

Tracking custom actions within analytics

For built-in actions, we track whenever the user clicks the link, image or other content you place, but for custom actions you have to add your own code to send data to analytics.

To build upon the previous example, we are going to expand our quote handler.

// Quote handler
$this.showHandlers['quote'] = function(action) {
      // Create an element with a clickable link
    var elm = $('<div class="quotebox"> \
                    <a href="http://mysite.com/quotes?quote=' + action.quote + '">' + action.quote + '</a> \
                 </div>');
        // Add code to track the click - simply call the "fire:action:click" event handler with the action object
    $('a', elm).on('click', function(e) {
        Player.fire("player:action:click", action);
    });
    action.container.html(elm);
}

Feel free to track multiple click points, but be aware that we only track a maximum of 1 action click per user per video.