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 (currently broken!)
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
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.

johnmal-dev/matey