📈 User Engagement Tracking Components for your Ahoy data 🏴☠️
This gem provides a suite of ViewComponents to observe user engagement in your Ahoy-powered Ruby on Rails application.
In order to use this gem you must:
- Have Ahoy installed, configured and actively tracking user visit and event data
- Have Bootstrap 5.1 available for styling
Add this line to your application's Gemfile:
# latest from rubygems
gem 'matey'
# latest from github
gem 'matey', github: 'harled/matey', branch: 'main'And then execute:
$ bundle install
You now have the latest version of Matey. Checkout the Usage section to see what components this gem includes and how to use them in your application.
This section outlines the components Matey offers and how to use them 🛠️
Below are some common flows that will help you recognize how the named parameters work for Matey's components.
All of the Matey components follow the same pattern. The following is an example of calling the ActiveUsersComponent to report on the last week of data based on all Ahoy events.
This is what rendering a Matey view component would look like in your view file:
# dashboard.html.erb
<%= render Matey::ActiveUsersComponent.new(events: Ahoy::Event.all, time_window: 1.week) %>All components begin with Matey:: followed by the name of the component. The data parameter varies but will always expect the parameter to be an ActiveRecordRelation collection.
The time_window parameter is the time range that you want your data filtered based on. This is an optional parameter. The default is a 1.week time window.
Note: The more data you have, the more interesting the components will be. A common and helpful pattern is to capture events on all controller actions. Details on doing this can be found here.
If you have a lot of visit/event data, you can always control the load time of components by reducing the time_window parameter (i.e. using a range of a year could be a lot of data!).
The following components are available;
- NewUsersComponent
- ActiveUsersComponent
- NewActivityComponent
- TopVisitedLandingPagesComponent
- TopEventsComponent
- BounceRateComponent
- CustomCardComponent
- CustomTableComponent
The NewUsersComponent displays the number of new users that have been created within the time window parameter. It also displays the number and percentage change from the previous time period.
<%= render Matey::NewUsersComponent.new(users: User.all, time_window: 2.month) %>Here we are passing in all of our User model data for the component to find the new users that were made in the last 2 months, but we can filter this data to only include a specific subset of users and/or a specific time period. The component finds new users created in the past month and shows us the increase/decrease since the last period based on the created_at attribute.
The ActiveUsersComponent displays the number of active users that have been created within the time window parameter. It also displays the number and percentage change from the previous time period. This component counts active users as those who have been involved in an Ahoy event in the given time window.
<%= render Matey::ActiveUsersComponent.new(events: Ahoy::Event.all, time_window: 1.month) %>Here we are passing in all of our Ahoy::Event model data which is used to determine what users triggered an event in the parameter time period. The component finds the active users created in the past month and shows us the increase/decrease since the last period.
The NewActivityComponent component displays the number of Ahoy events that have been created within the time window parameter. It also displays the number and percentage change from the previous time period.
<%= render (Matey::NewActivityComponent.new(events: Ahoy::Event.all, time_window: 1.month)) %>Here we are passing in all of our Ahoy::Event model data for the component to count all Ahoy Events, but we can filter this data to only include a specific subset of Ahoy Events or from a specific time period. The component finds the Ahoy events created in the past month and shows us the increase/decrease since the last period.
The TopVisitedPagesTableComponent component uses Ahoy::Visit data and displays a list of the top visited paths. Pass in Ahoy::Visit.all and the component displays the top landing pages based on the visits that have been created within the time window parameter. The limit parameter limits the number of results and is 10 by default.
<%= render Matey::TopVisitedPagesTableComponent.new(events: Ahoy::Visit.all, time_window: 1.month, limit: 10) %>
The TopEventsComponent displays a list of the top Ahoy::Events. Pass in the Ahoy::Event.all and the component calculates the top events that have been triggered in the given time window. The limit parameter limits the number of results and is 10 by default.
<%= render(Matey::TopEventsComponent.new(events: Ahoy::Event.all, time_window: 1.month, limit: 10)) %>
The BounceRateComponent displays the total bounce rate percentage of your application. That is the number of visits to your application in which the user visited only one page and left the site, compared to the total number of visits to your application. It additionally shows a list of the pages with the highest bounces. Pass in the Ahoy::Event.all & Ahoy::Visit.all parameters and the component calculates the bounce rate of your application and the top 5 pages with the highest bounces. The limit parameter limits the number of results and is 5 by default.
<%= render(Matey::BounceRateComponent.new(events: Ahoy::Event.all, visits: Ahoy::Visit.all, limit: 5)) %>Coming Soon...
Coming Soon...
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install.
A sample application is included in this repository to help with exploring the components and testing. To use the sample application:
cd spec/samplebundlerails s- Open a browser to
localhost:3000
To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Use the following steps to run the test cases:
rails db:test:preparebundle exec rake
Please take a look at our Contribution Guidelines.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Matey project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Project Lead: Caitlin Henry
(caitmich | caitlin@harled.ca)