Users Insights Hooks

This is a developer’s reference of some of the hooks you can use with Users Insights. They are used to reprocess the output (filters) or to fire your own functions (actions). You can read more about using hooks in the WordPress Plugin API.

Disclaimer: Please note that the hooks listed on this page may be subject to change or removal in future updates of the plugin. Additionally, the improper use of some of the hooks might lead to inaccurate results. This document is for reference only and should be used at your own responsibility.

User data filters
User profile filters
Database query filters
Privacy filters
3rd party plugin filters
Additional filters
Users Insights actions

User data filters

usin_users_raw_data

Type: filter

Allows filtering the raw database results that are loaded in the user table, before the rows are converted to user objects. The filter passes an array of the database records that the main Users Insights table query returns. Each element in the array represents the corresponding database record for each user.

apply_filters('usin_users_raw_data',  (array) $original_data );

usin_user_db_data

Type: filter

Allows filtering the single user raw database data – works for both the user table and user profile section. This is useful if you need to format user data in a different format. Passes one argument with the entire data object.

apply_filters('usin_user_db_data',  (object) $original_data );

The registered fields can be accessed as properties of the object (e.g. $data->my_newfield ). Please note that the field data might not be always set due to the way the Users Insights query is designed to load only the fields that are needed. For example, if a particular field is hidden on the table and not being used in the current filters, the data for this field will not be loaded for performance reasons. That’s why when using this filter, make sure to first check that the corresponding field is set on the data object.

Example:

add_filter('usin_user_db_data', 'my_format_newfield');

function my_format_newfield($user_data){ 
  if(!empty($user_data->my_newfield)){ 
    //format the data in the way you need
    $formatted = implode(', ', unserialize($user_data->my_newfield));
 
    //apply the new format
    $user_data->my_newfield = $formatted; 
  }
 
  return $user_data;
}

usin_single_user_db_data

Type: filter

Similar to the previous filter, it allows filtering the single user raw database data. But this time it works only in the user profile. The filter passes one argument with the entire user data object.

apply_filters('usin_single_user_db_data',  (object) $user_data );

Example:

add_filter('usin_single_user_db_data', 'my_format_status');

function my_format_status($user_data){
  //change user newsletter status from boolean (1/0) to Yes/No
  //if it isn't empty, then we have the user consent
  if(!empty($user_data->newsletter_status)){    
    //format the data in the way you need
    $user_data->newsletter_status = "Yes";
  } else {    
    //It's empty, so we have no consent
    $user_data->newsletter_status = "No";
  }

  return $user_data;
}

User profile filters

usin_user_profile_data

Type: filter

Allows modifying the user object data on the user profile page. This filter is similar to the usin_single_user_db_data filter, the only difference is that this one passes the actual user object with all the default field formatting already applied.

apply_filters('usin_user_profile_data',  (object) $user );

usin_user_activity

Type: filter

Allows adding custom elements to activity section and filtering the ones you have. Passes two arguments, first the activity array and the user ID.

apply_filters('usin_user_activity', (array) $activity, (int) $user_id );

Each element in the activity array represents a separate activity (as an array). Allowed values in the activity array are:

type – unique identifier of the activity
label – the name/label of the activity
count – the number of activities that exist from this type
link – indicates the URL of the “View all” link. This link is displayed when there are more activities from this type than the ones that are currently shown
list – a list of activity items. Each item should be an array that should contain a title and a link. In the case of a high number of activity items, we recommend only loading the last few and setting a “View all” link in the link option where all of the items can be previewed.

Example:

add_filter('usin_user_activity', 'my_custom_activity_panel', 10, 2);

function my_custom_activity_panel($activity, $user_id){
  
  $activity[] = array(
    'type' => 'my_new_panel',
    'label' => 'New Panel',
    'count' => 10,
    'link' => '#',
    'list' => array(
      array(
        'title' => "First Title",
        'link' => "http://firstlink.com"
      ),
      array(
        'title' => "Second Title",
        'link' => "http://secondlink.com"
      )
    )
  );

  return $activity;
}

usin_user_actions

Type: filter

Allows adding new buttons at the top of the user profile section. Useful for quick user actions, such as checking their profile in one of your plugins.

Users insights profile actions

Passes two arguments – an array with the default actions and the user id.

apply_filters('usin_user_actions',  (array) $actions, (int) $user_id );

Example:

add_filter('usin_user_actions', 'my_add_user_action', 10, 2);

function my_add_user_action($actions, $user_id){
  $actions[]=array(
    'id'=>'action-id-goes-here',
    'name' => 'View custom profile',
    'link' => 'https://link-goes-here.com'
  );

  return $actions;
}

usin_notes_list

Type: filter

Allows filtering the notes list for a user. Passes an array of the notes list and since version 3.7, it also passes the ID of the user.

apply_filters('usin_notes_list',  (array) $notes, (int) $user_id );

Database query filters

The following section describes some of the main database query filters that you might need to modify the user query of Users Insights. These can be useful if you need to restrict the results of the users displayed.

usin_user_query_select

Type: filter

Allows you to modify the SELECT statement of the final user query, after it is built. Passes a string with the original query select. This filter is applied to the SELECT statement of both the user table and user profile.

apply_filters('usin_user_query_select',  (string) $original_query_select);

usin_query_where

Type: filter

Allows setting a custom WHERE statement of the main query, after it is built. Passes a string of the original where argument. This filter is applied to the WHERE statement of both the user table and user profile query.

apply_filters('usin_query_where',  (string) $original_where );

This field should not be used for applying a WHERE clause to your custom registered fields, but rather to apply a default filter to the main query.

usin_query_having

Type: filter

Allows setting a custom “having” statement of the main query. Passes a string of the original having argument. This filter is applied to the HAVING statement of both the user table and user profile query.

apply_filters('usin_query_having',  (string) $original_having );

usin_query_joins

Type: filter

Modifies the main query JOIN clause. Passes a string with the original JOINS. Similarly to the above-mentioned filters, this one is also applied to both the user table and profile queries.

apply_filters('usin_query_joins',  (string) $original_joins );

If you want to register a JOIN statement for your custom field, use the usin_query_join_table filter instead, which is only applied when the field is visible on the table or used in the filters.

Privacy filters

usin_personal_data_erase_exclude_custom_fields

Type: filter

This filter allows you to exclude the Users Insights custom fields to erase upon a Personal Data Erase request. The filter passes an array with the default field keys that will not be erased (by default it’s an empty array).

apply_filters('usin_personal_data_erase_exclude_custom_fields', 
    (array) $original_exclude_fields );

In this way, if you use custom fields with Users Insights that do not store personal data, but you need to keep when the user sends a Personal Data Erase request, you can use this filter to make sure these fields are not erased.

usin_detect_user

Type: filter

This filter allows skipping user detection. If you want to disable the geolocation detection, last seen/sessions detection or device detection for a particular user, you can use this filter to do that.

Note: It is recommended to use this filter in a plugin rather than a theme. If the filter is used in a theme and certain plugins like WooCommerce Memberships are active, the hooks that this filter relies on, may be activated before the theme files are loaded. This can cause the filter to be called before the callback function has been registered in the theme.

This filter passes two arguments – a boolean that indicates whether the user information should be detected and the user ID as an integer:

apply_filters('usin_detect_user',  (boolean) $should_detect, (int) $user_id );

Example:

add_filter('usin_detect_user', 'my_filter_user_detect', 10, 2);

function my_filter_user_detect($should_detect, $user_id){
  $agreed = get_user_meta($user_id, 'agreed_to_privacy_policy', true);
  if(empty($agreed)){
    return false;
  }
  
  return $should_detect;
}

usin_should_track_visit

Type: filter

This filter allows controlling page visit tracking. This filter is applied after Users Insights has determined whether to track or not the visit, based on the Visit Tracking module settings. By modifying the $should_track parameter, you can override the tracking decision. The second parameter is the ID of the current user and the third parameter is the ID of the current post. By returning true the visit will be recorded and by returning false the visit will not be recorded.

apply_filters('usin_should_track_visit',  
    (boolean) $should_track, (int) $user_id, (int) $post_id );

Example:

add_filter('usin_should_track_visit', 'my_filter_user_detect', 10, 3);

function my_filter_user_detect($should_track, $user_id, $post_id){
  $agreed = get_user_meta($user_id, 'agreed_to_page_view_tracking', true);
  if(empty($agreed)){
    return false;
  }
  
  return $should_track;
}

3rd party plugin filters

Ultimate Member

usin_ignore_um_types

Type: filter

Allows changing the default Ultimate Member field types that are ignored by Users Insights (such as “row” or “divider”). Passes the array with the types that Users Insights ignores by default.

apply_filters('usin_ignore_um_types',  (array) $ignore_types );

WooCommerce

usin_add_profile_link_to_order

Type: filter

Allows removing the Users Insights profile link from the WooCommerce order page. Passes a boolean which defaults to true . If you’d like to remove the link, just return false from the filter callback.

apply_filters('usin_add_profile_link_to_order',  (boolean) $should_add_link );

usin_wc_successful_order_statuses

Type: filter

Allows changing the order statuses used in to count “Successful orders” and compute “Lifetime value” fields.

apply_filters('usin_wc_successful_order_statuses', (array) $statuses);

Default value: array( ‘wc-completed’, ‘wc-processing’ )

usin_wc_sale_order_statuses

Allows changing the order statuses used to detect sale orders in reports (Sales, Sales Total, Product Sales, Product Sales Total, Product Items Sold).

apply_filters('usin_wc_sale_order_statuses', $statuses);

Default value: array(‘wc-completed’, ‘wc-processing’, ‘wc-on-hold’)

Additional filters

usin_fields

Type: filter

Modifies the available Users Insights fields. By default, this array contains the default Users Insights fields and the fields you have mapped under Users Insights > Custom fields. You can use this filter to remove or edit the existing fields.

Passes an array of the default fields, containing an array of each field’s attributes.

apply_filters('usin_fields', array $default_fields);

Each field is represented as an array of options, for example:

array(
  'name' => __('Display Name', 'usin'),
  'id' => 'name',
  'order' => 'ASC',
  'show' => false,
  'filter' => array(
    'type' => 'text'
  )
)

Some of the most common field options are:

name – the name of the field (the label that is displayed in the user table, filters and profile)
id – unique identifier of the field
order – default order when sorting the table by this field – allowed options are 'ASC' (ascending), 'DESC' (descending) and false (disable sorting by this field)
show – boolean setting whether the field will be visible by default when first opening the Users Insights table. Please note that this option is ignored after the user changes the visibility settings of the field from the eye-icon menu.
filter – sets the filtering options that will be available for this field. It is not recommended to modify this option, as this could lead to errors or incorrect results returned
module – the ID of the module to which the field belongs to. When this option is set, the field will be available only when the corresponding module is active

Example – removing the email field:

add_filter('usin_fields', 'my_remove_email_field', 1000);

function my_remove_email_field($fields){

  foreach ($fields as $i => $field) {
    if(isset($field['id']) && $field['id'] == 'email'){
      unset($fields[$i]);
    }
  }

  return $fields;
}

usin_wp_user_meta_core_keys

Type: filter

By default Users Insights doesn’t allow registering a custom field with a meta key that is used by WordPress core. With this filter you can modify the list of core keys that Users Insights checks against. This filter passes an array with the default WordPress core keys.

apply_filters('usin_wp_user_meta_core_keys', (array) $core_keys);

usin_group_colors

Type: filter

This filter allows you to customize the Users Insights group colors. Passes an array with the default options.

apply_filters(' usin_group_colors', (array) $colors);

Here is an example of how to add new colors:

add_filter('usin_group_colors', 'custom_ui_group_colors');

function custom_ui_group_colors($colors){  
  //add new colors as items of an array
  $colors[] = 'ff0000';
  $colors[] = '00ff00';

  return $colors;
}

usin_exclude_comment_types

Type: filter

This filter allows you to modify the default comment types are ignored in the Users Insights table (number of comments field) and in the user profile (comments listed in the Activity section). Passes an array with the comment type names.

apply_filters('usin_exclude_comment_types', (array) $comment_types);

usin_exclude_post_types

Type: filter

This filter allows you to modify the default post types are ignored in the Users Insights table (number of posts field) and in the user profile (posts listed in the Activity section). Passes an array with the custom post type names.

apply_filters('usin_exclude_post_types', (array) $custom_post_types);

usin_module_options

Type: filter

Allows to modify the list of the Users Insights modiules. Passes an array with all the registered modules – each item in the array is another array containing the module options.

apply_filters('usin_module_options', (array) $default_modules );

This is an example of how the module options array looks like:

array(
  'id' => 'moduleid',
  'name' => 'Module Name',
  'desc' => 'Module Description',
  'allow_deactivate' => true,
  'buttons' => array(
    array('text'=> __('Learn More', 'usin'), 'link'=>'#', 'target'=>'_blank')
  ),
  'active' => false
);

usin_client_ip

Type: filter

This filter allows changing the method used to collect the user’s IP address for the GeoLocation module. Passes the user’s IP address that was collected by the default Users Insights method.

apply_filters('usin_client_ip', (string) $ip );

usin_user_list_options

Type: filter

This filter contains a lot of JavaScript initialization options for the main Users Insights page, and it can be used for a lot of interface tweaks. Passes an array with the default options.

apply_filters('usin_module_options', (array) $options );

Here is an example of adding another option for the number of users to show per page:

add_filter('usin_user_list_options', 'customize_user_options');

function customize_user_options($options){  
  //define the pagination options
  $options['pageOptions'] = array(10, 20, 50, 100, 200);
  
  return $options;
}

usin_max_report_items

Type: filter

This filter can be used to edit the number of bars or pie chart elements shown before being grouped in an “Other” section. Passes an integer with the value we have.

apply_filters('usin_max_report_items',  (int) $max );

usin_events_max_items_to_store

Type: filter

apply_filters('usin_events_max_items_to_store', (int) $max_items, (string) $event_type);

Allows changing the number of tracked events per user, the default number is 300. For example, if you are using the page visit tracking module, you can change the number of recorded page visits by using this filter. We don’t recommend setting a number higher than 300.

usin_include_bom_export

Type: filter

apply_filters('usin_include_bom_export', (boolean) $include);

Allows including UTF-8 BOM in the exported CSV file. Defaults to false , when set to true , BOM will be included in the exported file. This should be used when opening a CSV file with Excel, in case Excel doesn’t recognize the character encoding.

The following code enables UTF-8 BOM:

add_filter('usin_include_bom_export', '__return_true');

Users Insights actions

usin_files_loaded

Type: Action

This action is fired after the Users Insights files/classes are loaded.

do_action('usin_files_loaded');

usin_loaded

Type: Action

This action is fired after Users Insights is initialized.

do_action('usin_loaded');

usin_module_options_loaded

Type: Action

This action is fired after the module options are loaded.

do_action('usin_module_options_loaded');

usin_module_activated

Type: Action

This action is fired when a module is activated. It passes the ID of the module activated.

do_action('usin_module_activated', (string) $module_id);

usin_module_deactivated

Type: Action

This action is fired when a module is deactivated. It passes the ID of the module activated.

do_action('usin_module_deactivated', $module_id);

Table of contents

User data filters

usin_users_raw_data

usin_user_db_data

usin_single_user_db_data

User profile filters

usin_user_profile_data

usin_user_activity

usin_user_actions

usin_notes_list

Database query filters

usin_user_query_select

usin_query_where

usin_query_having

usin_query_joins

Privacy filters

usin_personal_data_erase_exclude_custom_fields

usin_detect_user

usin_should_track_visit

3rd party plugin filters

Ultimate Member

usin_ignore_um_types

WooCommerce

usin_add_profile_link_to_order

usin_wc_successful_order_statuses

usin_wc_sale_order_statuses

Additional filters

usin_fields

usin_wp_user_meta_core_keys

usin_group_colors

usin_exclude_comment_types

usin_exclude_post_types

usin_module_options

usin_client_ip

usin_user_list_options

usin_max_report_items

usin_events_max_items_to_store

usin_include_bom_export

Users Insights actions

usin_files_loaded

usin_loaded

usin_module_options_loaded

usin_module_activated

usin_module_deactivated