Custom events

In WP Tao you can add custom events and this way track any user behaviour on your site. In this tutorial we will present, step-by-step, how to register a custom event and then start tracking it.

For example, we will register the event. “Displaying an error 404 page”.

Step 1 – Event registration

First, add a new event type to an array that stores information on all registered events.

An array for a new event $actions[ 'error_404' ] takes the following arguments.

  • id string – A unique name of the event
  • category string – Default categories: contact, traffic, commerce, user. You can choose only one.
  • title string – Default title. The title will be displayed on the timeline for the events.
  • style array – You can create your own style of the event that will stand out on the timeline.
    • color string – colour in hex values
    • icon string – the name of the icon dashicons or an absolute path to the picture

Step 2 – Firing an event

In order to save information about all displays of 404, you need to trigger the function do_action( 'wptao_track_event', 'error_404', $args ); at the moment when someone visits a non-existent site. WP Tao will automatically assign the user and a fingerprint to this event.

The function do_action( 'wptao_track_event', 'error_404', $args ); assumes the following parameters:

  • hook name string – it will always be ‘wptao_track_event’
  • action name string – The name of a registered event. In this example it will be ‘error_404’
  • args array – arguments for the event
    • value string – the value of the event. In the case of an error 404, in the value field the full URL of the site visited will be included.
    • tags array – tags are useful when filtering events on the timeline.

As a result, when a user visits a page with an error 404, this event will be marked on the timeline. It should look as on the following picture.

wp-tao-custom-events

User identification

The following information will be useful when recording events associated with forms. It does not apply to this example.
Some events allow for identification of the user. To identify he user it is enough to have his e-mail address he enters while filling in the contact form. By default, in WP Tao the user identification takes place in the following events: order, payment, login, register, contact, which is where information about the identity (name, email, phone) is provided.
The identification of users in custom events requires the acquisition of at least an e-mail address of the user at the time of firing the event.
User information are provided in an additional field user_data

Step 3 – Adding the description of the event on the timeline

WP Tao allows you to customize your own titles and descriptions of events presented on the timeline. Looking back at the example of tracking the visits to an error 404 page, you will notice that there is no URL of the page visited.

To add your own title and description, use the following filters:
1. Titleadd_filter( 'wptao_event_{event_name}_title', 'callback_function_name', 10, 2 );
2. Descriptionadd_filter( 'wptao_event_{event_name}_description', 'callback_function_name', 10, 2 );

In our case, {event_name} is the name of the event, which was registered, i.e. ,error_404 ‘.

After using this code on the timeline in the description of events ‘error_404’ displays the URL of the page visited.

wp-tao-custom-events-2

Similarly, you can use the filter 'wptao_event_{event_name}_title' and overwrite the default title, ‘404 error page’, which was defined during the event registration of ‘error_404’.

Summary

WP Tao allows you to register and track any types of events. This allows you to adjust the plugin to your own sales solutions running on WordPress.

Until now, events were recorded from the PHP level. In the following part of the tutorial you will learn how to register events enabled on the client side (JavaScript) e.g. clicking a specific element on the site. See the entry JavaScript Events

WP Tao allows you to create detailed reports for custom events. Thanks to this, events will be marked on the timeline. In addition, they can be presented in the form of graphs and tables. See the entry Custom reports.