Skip to content

A platform for community discussion. Free, open, simple.

DEV: Add stats for admin onboarding panel progress (#43188)

Keegan George2c020f2b200f
diff --git a/app/controllers/admin/onboarding_events_controller.rb b/app/controllers/admin/onboarding_events_controller.rb
index f3d806cbd38..decebcd0169 100644
--- a/app/controllers/admin/onboarding_events_controller.rb
+++ b/app/controllers/admin/onboarding_events_controller.rb
@@ -1,7 +1,7 @@
# frozen_string_literal: true
class Admin::OnboardingEventsController < Admin::AdminController
- STEPS = %w[select_theme invite_collaborators start_posting].freeze
+ STEPS = UserHistory::ADMIN_ONBOARDING_STEPS
def create
logger = StaffActionLogger.new(current_user)
diff --git a/app/models/stat.rb b/app/models/stat.rb
index d84e8b02d85..bf2eec1b202 100644
--- a/app/models/stat.rb
+++ b/app/models/stat.rb
@@ -62,6 +62,11 @@ class Stat
Stat.new("active_users", expose_via_api: true) { Statistics.active_users },
Stat.new("likes", expose_via_api: true) { Statistics.likes },
Stat.new("participating_users", expose_via_api: true) { Statistics.participating_users },
+ # Deliberately not exposed via the API: these describe how the site's own
+ # admin set the site up, which is of no interest to its members.
+ Stat.new("steps", stat_type: :onboarding) { Statistics.onboarding_steps },
+ Stat.new("panel", stat_type: :onboarding) { Statistics.onboarding_panel },
+ Stat.new("minutes_to", stat_type: :onboarding) { Statistics.onboarding_minutes_to },
]
if SiteSetting.display_eu_visitor_stats
diff --git a/app/models/user_history.rb b/app/models/user_history.rb
index 27a8c23e7fc..77364b9df5c 100644
--- a/app/models/user_history.rb
+++ b/app/models/user_history.rb
@@ -12,6 +12,10 @@ class UserHistory < ActiveRecord::Base
belongs_to :category
belongs_to :reviewable, optional: true
+ # Subjects logged alongside the :admin_onboarding_step_completed action, one
+ # per step of the admin onboarding panel.
+ ADMIN_ONBOARDING_STEPS = %w[select_theme invite_collaborators start_posting].freeze
+
# Each value in the context should be shorter than this
MAX_CONTEXT_LENGTH = 50_000
diff --git a/lib/statistics.rb b/lib/statistics.rb
index 26446f45c44..17d57581134 100644
--- a/lib/statistics.rb
+++ b/lib/statistics.rb
@@ -139,8 +139,73 @@ class Statistics
.to_h
end
+ # The admin onboarding panel is a one-time flow shown only to a site's first
+ # human admin, and only while their account is newer than
+ # `site_owner_onboarding_max_days`. These three stats therefore only ever
+ # climb, and freeze once that window closes.
+
+ def self.onboarding_steps
+ { completed: onboarding_step_events.distinct.count(:subject) }
+ end
+
+ def self.onboarding_panel
+ {
+ completed: onboarding_event_exists?(:admin_onboarding_completed),
+ dismissed: onboarding_event_exists?(:admin_onboarding_dismissed),
+ }
+ end
+
+ # Minutes from the first admin signing up to each step being completed, so
+ # that "completed within N hours" stays derivable after the fact. A step that
+ # never happened is nil rather than 0, to keep it distinct from one completed
+ # instantly.
+ def self.onboarding_minutes_to
+ signed_up_at = first_admin_created_at
+ steps = UserHistory::ADMIN_ONBOARDING_STEPS
+
+ return steps.index_with(nil).symbolize_keys.merge(completed: nil) if signed_up_at.nil?
+
+ completed_at = onboarding_events(:admin_onboarding_completed).minimum(:created_at)
+ first_completed_at = onboarding_step_events.group(:subject).minimum(:created_at)
+
+ steps
+ .index_with { |step| minutes_between(signed_up_at, first_completed_at[step]) }
+ .symbolize_keys
+ .merge(completed: minutes_between(signed_up_at, completed_at))
+ end
+
private
+ def self.onboarding_events(action)
+ UserHistory.where(action: UserHistory.actions[action])
+ end
+
+ def self.onboarding_step_events
+ onboarding_events(:admin_onboarding_step_completed).where(
+ subject: UserHistory::ADMIN_ONBOARDING_STEPS,
+ )
+ end
+
+ # Reported as 1/0 flags rather than booleans, to match the integer shape of
+ # every other stat.
+ def self.onboarding_event_exists?(action)
+ onboarding_events(action).exists? ? 1 : 0
+ end
+
+ # Mirrors the user the onboarding panel is shown to: the lowest-id human admin.
+ def self.first_admin_created_at
+ User.where(admin: true).human_users.order(:id).limit(1).pick(:created_at)
+ end
+
+ # nil rather than a negative number when the event predates the baseline,
+ # which happens when the original first admin has since been deleted or
+ # demoted: the replacement's signup is not the date onboarding started, so the
+ # duration is unknowable rather than zero.
+ def self.minutes_between(from, to)
+ return nil if to.nil? || to < from
+ ((to - from) / 60).round
+ end
+
def self.valid_users
users = User.real.activated.not_suspended.not_silenced
users = users.approved if SiteSetting.must_approve_users
diff --git a/spec/lib/plugin/instance_spec.rb b/spec/lib/plugin/instance_spec.rb
index 5942f46d29f..dac663352d4 100644
--- a/spec/lib/plugin/instance_spec.rb
+++ b/spec/lib/plugin/instance_spec.rb
@@ -113,6 +113,9 @@ TEXT
:participating_users_last_day,
:participating_users_7_days,
:participating_users_30_days,
+ # onboarding stats are grouped under their stat type rather than being
+ # flat top-level keys
+ :onboarding,
)
end
diff --git a/spec/lib/statistics_spec.rb b/spec/lib/statistics_spec.rb
index 9f64ee563ba..1ddf493036c 100644
--- a/spec/lib/statistics_spec.rb
+++ b/spec/lib/statistics_spec.rb
@@ -337,4 +337,132 @@ RSpec.describe Statistics do
end
end
end
+
+ describe "admin onboarding" do
+ fab!(:first_admin) { Fabricate(:admin, created_at: 10.days.ago) }
+
+ def complete_step(step, at:, acting_user: first_admin)
+ Fabricate(
+ :user_history,
+ action: UserHistory.actions[:admin_onboarding_step_completed],
+ acting_user: acting_user,
+ subject: step,
+ created_at: at,
+ )
+ end
+
+ def log_event(action, at:)
+ Fabricate(
+ :user_history,
+ action: UserHistory.actions[action],
+ acting_user: first_admin,
+ created_at: at,
+ )
+ end
+
+ describe ".onboarding_steps" do
+ it "counts each distinct step once" do
+ complete_step("select_theme", at: 9.days.ago)
+ complete_step("invite_collaborators", at: 8.days.ago)
+
+ expect(described_class.onboarding_steps).to eq(completed: 2)
+ end
+
+ it "does not double count a step completed more than once" do
+ complete_step("select_theme", at: 9.days.ago)
+ complete_step("select_theme", at: 8.days.ago)
+
+ expect(described_class.onboarding_steps).to eq(completed: 1)
+ end
+
+ it "ignores subjects that are not onboarding steps" do
+ complete_step("not_a_step", at: 9.days.ago)
+
+ expect(described_class.onboarding_steps).to eq(completed: 0)
+ end
+
+ it "is zero when nothing has been completed" do
+ expect(described_class.onboarding_steps).to eq(completed: 0)
+ end
+ end
+
+ describe ".onboarding_panel" do
+ it "flags completion and dismissal separately" do
+ log_event(:admin_onboarding_completed, at: 9.days.ago)
+
+ expect(described_class.onboarding_panel).to eq(completed: 1, dismissed: 0)
+ end
+
+ it "can flag both when an admin dismisses the panel and finishes later" do
+ log_event(:admin_onboarding_dismissed, at: 9.days.ago)
+ log_event(:admin_onboarding_completed, at: 8.days.ago)
+
+ expect(described_class.onboarding_panel).to eq(completed: 1, dismissed: 1)
+ end
+
+ it "is zero for both when the panel was never touched" do
+ expect(described_class.onboarding_panel).to eq(completed: 0, dismissed: 0)
+ end
+ end
+
+ describe ".onboarding_minutes_to" do
+ it "measures each step from the first admin signing up, across several days" do
+ complete_step("select_theme", at: first_admin.created_at + 30.minutes)
+ complete_step("invite_collaborators", at: first_admin.created_at + 2.days)
+ complete_step("start_posting", at: first_admin.created_at + 4.days)
+ log_event(:admin_onboarding_completed, at: first_admin.created_at + 4.days + 1.minute)
+
+ expect(described_class.onboarding_minutes_to).to eq(
+ select_theme: 30,
+ invite_collaborators: 2880,
+ start_posting: 5760,
+ completed: 5761,
+ )
+ end
+
+ it "measures from the first completion when a step is repeated" do
+ complete_step("select_theme", at: first_admin.created_at + 30.minutes)
+ complete_step("select_theme", at: first_admin.created_at + 3.days)
+
+ expect(described_class.onboarding_minutes_to[:select_theme]).to eq(30)
+ end
+
+ it "reports nil for steps that never happened" do
+ complete_step("select_theme", at: first_admin.created_at + 30.minutes)
+
+ expect(described_class.onboarding_minutes_to).to eq(
+ select_theme: 30,
+ invite_collaborators: nil,
+ start_posting: nil,
+ completed: nil,
+ )
+ end
+
+ it "measures from the lowest-id human admin, not a later one" do
+ later_admin = Fabricate(:admin, created_at: 2.days.ago)
+ complete_step("select_theme", at: first_admin.created_at + 1.hour, acting_user: later_admin)
+
+ expect(described_class.onboarding_minutes_to[:select_theme]).to eq(60)
+ end
+
+ it "reports nil when a step predates the current first admin" do
+ # The admin who did the onboarding has since been deleted, leaving a
+ # replacement whose signup date says nothing about when onboarding began.
+ complete_step("select_theme", at: first_admin.created_at - 2.days)
+
+ expect(described_class.onboarding_minutes_to[:select_theme]).to be_nil
+ end
+
+ it "reports nil throughout when the site has no human admin" do
+ User.where(admin: true).human_users.update_all(admin: false)
+
+ expect(described_class.onboarding_minutes_to).to eq(
+ select_theme: nil,
+ invite_collaborators: nil,
+ start_posting: nil,
+ completed: nil,
+ )
+ end
+ end
+ end
end
diff --git a/spec/models/stat_spec.rb b/spec/models/stat_spec.rb
index e3b18e2fc74..d9d25cee6c0 100644
--- a/spec/models/stat_spec.rb
+++ b/spec/models/stat_spec.rb
@@ -6,6 +6,19 @@ RSpec.describe Stat do
expect(Stat.all_stats.keys).to include(:topics_30_days, :likes_30_days)
end
+ it "groups the onboarding stats under their stat type" do
+ expect(Stat.all_stats[:onboarding].keys).to include(
+ :steps_completed,
+ :panel_completed,
+ :panel_dismissed,
+ :minutes_to_select_theme,
+ )
+ end
+
+ it "keeps the onboarding stats out of the public API stats" do
+ expect(Stat.api_stats.keys).not_to include(:onboarding)
+ end
+
context "when display_eu_visitor_stats is enabled" do
before { SiteSetting.display_eu_visitor_stats = true }