Matey
📈 User Engagement Tracking ViewComponents for Ahoy data 🏴☠️
This gem provides a suite of prebuilt ViewComponents to observe user engagement in an Ahoy-powered Ruby on Rails application.
Installation
matey
depends on:
- Ahoy installed, configured and tracking user visit and event data
- Bootstrap 5.1 available for styling
Add this line to the Gemfile:
# latest from rubygems
gem 'matey'
# or latest from github
gem 'matey', github: 'harled/matey', branch: 'main'
And then execute:
$ bundle install
Usage
Once matey
is installed, the next step is to render a component. The data required varies by component.
Below is an example of how the Matey::ActiveUsersComponent
would be
called in an application. This component reports on the number of active users within the past two weeks.
Below the component is called with two named parameters which include events
(ahoy event data) and
the time_window
, which is the period to report on.
# dashboard.html.erb
<%= render Matey::ActiveUsersComponent.new(events: Ahoy::Event.all, time_window: 1.week) %>
It is that simple! There should now be a card displaying the number of active users within the past week.
View the available component color schemes here.
View the list of available components here.
Note: The more data, 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.
Development
After checking out the repository, run the following commands to get started:
# install required packages
bin/setup
# install spec/sample packages
bundle install --gemfile spec/sample/Gemfile
# run test cases and ensure everything is passing
rake spec
# an interactive prompt that will allow you to experiment with matey
bin/console
To install matey
and make it available as a regular rubygem, run the following command: bundle exec rake install
Sample Application
ViewComponents are pretty hard to test without a Ruby on Rails application. This repository includes a sample application that makes it easy to see how a component renders and make quick adjustments.
To use the sample application:
cd spec/sample
bundle
bundle exec rails s
- Open a browser to
localhost:3000
Testing
To run the test cases:
rails db:test:prepare
bundle exec rake
Releasing a New Version
To release a new version:
- Update the version number in
version.rb
- Run
bundle exec rake release
The rake task will create a git tag for the version, push git commits and the created tag, and push the .gem
file to rubygems.org.
Contributing
Please take a look at our Contribution Guidelines.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Matey project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.