From 7641c66a2bf3c7e9f8f25c9a501c76dbff5cf26a Mon Sep 17 00:00:00 2001 From: RobertJoonas <56999674+RobertJoonas@users.noreply.github.com> Date: Tue, 12 Mar 2024 10:00:32 +0000 Subject: [PATCH] Stats api time on page (#3858) * add metric validation + support in aggregate * add a test ensuring comparison works * disallow time_on_page with a goal filter * Return time_on_page as `nil` from aggregate API In case time_on_page cannot be calculated, we'll return it as `nil` from the Stats API. This is to make the behaviour consistent between breakdown and aggregate endpoints. As for the UI, we'll still continue to report time_on_page as 0 - not changing any UI behaviour as discussed with Marko. * add tests for time_on_page in event:page breakdown * update changelog * invalidate time_on_page with event:name filter * add the ability to only query time_on_page in page breakdown We'll need the visitors metric to get the list of pages to calculate the time_on_page for. --- CHANGELOG.md | 1 + lib/plausible/stats/aggregate.ex | 2 +- lib/plausible/stats/breakdown.ex | 17 +- lib/plausible/stats/compare.ex | 1 + lib/plausible/stats/util.ex | 17 +- .../api/external_stats_controller.ex | 27 +++- .../controllers/api/stats_controller.ex | 5 +- .../aggregate_test.exs | 152 ++++++++++++++++++ .../breakdown_test.exs | 138 ++++++++++++++++ .../api/stats_controller/top_stats_test.exs | 36 +++++ 10 files changed, 379 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d202ff7cf..118826f0a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ All notable changes to this project will be documented in this file. ### Added +- Add `time_on_page` metric into the Stats API - County Block List in Site Settings - Query the `views_per_visit` metric based on imported data as well if possible - Group `operating_system_versions` by `operating_system` in Stats API breakdown diff --git a/lib/plausible/stats/aggregate.ex b/lib/plausible/stats/aggregate.ex index e356c189d..56ded33f8 100644 --- a/lib/plausible/stats/aggregate.ex +++ b/lib/plausible/stats/aggregate.ex @@ -230,7 +230,7 @@ defmodule Plausible.Stats.Aggregate do @metrics_to_round [:bounce_rate, :time_on_page, :visit_duration, :sample_percent] - defp maybe_round_value({metric, nil}), do: {metric, 0} + defp maybe_round_value({metric, nil}), do: {metric, nil} defp maybe_round_value({metric, value}) when metric in @metrics_to_round do {metric, round(value)} diff --git a/lib/plausible/stats/breakdown.ex b/lib/plausible/stats/breakdown.ex index 074cdcb6a..ae33e4e73 100644 --- a/lib/plausible/stats/breakdown.ex +++ b/lib/plausible/stats/breakdown.ex @@ -112,7 +112,7 @@ defmodule Plausible.Stats.Breakdown do breakdown_events(site, query, "event:props:" <> custom_prop, metrics_to_select, pagination) |> Enum.map(&cast_revenue_metrics_to_money(&1, currency)) - |> Enum.sort_by(& &1[sorting_key(metrics_to_select)], :desc) + |> sort_results(metrics_to_select) |> maybe_add_cr(site, query, nil, metrics) |> Util.keep_requested_metrics(metrics) end @@ -194,7 +194,7 @@ defmodule Plausible.Stats.Breakdown do |> Map.merge(event_row) |> Map.merge(session_row) end) - |> Enum.sort_by(& &1[sorting_key(metrics)], :desc) + |> sort_results(metrics) end defp breakdown_sessions(_, _, _, [], _), do: [] @@ -777,6 +777,19 @@ defmodule Plausible.Stats.Breakdown do end) end + defp sort_results(results, metrics) do + Enum.sort_by( + results, + fn entry -> + case entry[sorting_key(metrics)] do + nil -> 0 + n -> n + end + end, + :desc + ) + end + defp sorting_key(metrics) do if Enum.member?(metrics, :visitors), do: :visitors, else: List.first(metrics) end diff --git a/lib/plausible/stats/compare.ex b/lib/plausible/stats/compare.ex index d234d9aad..aa03c3961 100644 --- a/lib/plausible/stats/compare.ex +++ b/lib/plausible/stats/compare.ex @@ -12,6 +12,7 @@ defmodule Plausible.Stats.Compare do end def percent_change(nil, _new_count), do: nil + def percent_change(_old_count, nil), do: nil def percent_change(%Money{} = old_count, %Money{} = new_count) do old_count = old_count |> Money.to_decimal() |> Decimal.to_float() diff --git a/lib/plausible/stats/util.ex b/lib/plausible/stats/util.ex index ff87237ed..10078ff6a 100644 --- a/lib/plausible/stats/util.ex +++ b/lib/plausible/stats/util.ex @@ -36,20 +36,13 @@ defmodule Plausible.Stats.Util do @doc """ This function adds the `visitors` metric into the list of - given metrics if it's not already there and if there is a - `conversion_rate` metric in the list. - - Currently, the conversion rate cannot be queried from the - database with a simple select clause - instead, we need to - fetch the database result first, and then manually add it - into the aggregate map or every entry of thebreakdown list. - - In order for us to be able to calculate it based on the - results returned by the database query, the visitors metric - needs to be queried. + given metrics if it's not already there and if it is needed + for any of the other metrics to be calculated. """ def maybe_add_visitors_metric(metrics) do - if :conversion_rate in metrics and :visitors not in metrics do + needed? = Enum.any?([:conversion_rate, :time_on_page], &(&1 in metrics)) + + if needed? and :visitors not in metrics do metrics ++ [:visitors] else metrics diff --git a/lib/plausible_web/controllers/api/external_stats_controller.ex b/lib/plausible_web/controllers/api/external_stats_controller.ex index b2a82e501..1825dbbd0 100644 --- a/lib/plausible_web/controllers/api/external_stats_controller.ex +++ b/lib/plausible_web/controllers/api/external_stats_controller.ex @@ -12,7 +12,8 @@ defmodule PlausibleWeb.Api.ExternalStatsController do :bounce_rate, :visit_duration, :events, - :conversion_rate + :conversion_rate, + :time_on_page ] @metric_mappings Enum.into(@metrics, %{}, fn metric -> {to_string(metric), metric} end) @@ -166,6 +167,30 @@ defmodule PlausibleWeb.Api.ExternalStatsController do end) end + defp validate_metric("time_on_page" = metric, property, query) do + cond do + query.filters["event:goal"] -> + {:error, "Metric `#{metric}` cannot be queried when filtering by `event:goal`"} + + query.filters["event:name"] -> + {:error, "Metric `#{metric}` cannot be queried when filtering by `event:name`"} + + property == "event:page" -> + {:ok, metric} + + not is_nil(property) -> + {:error, + "Metric `#{metric}` is not supported in breakdown queries (except `event:page` breakdown)"} + + query.filters["event:page"] -> + {:ok, metric} + + true -> + {:error, + "Metric `#{metric}` can only be queried in a page breakdown or with a page filter."} + end + end + defp validate_metric("conversion_rate" = metric, property, query) do cond do property == "event:goal" -> diff --git a/lib/plausible_web/controllers/api/stats_controller.ex b/lib/plausible_web/controllers/api/stats_controller.ex index 11d8b838b..acc5a56e8 100644 --- a/lib/plausible_web/controllers/api/stats_controller.ex +++ b/lib/plausible_web/controllers/api/stats_controller.ex @@ -402,7 +402,10 @@ defmodule PlausibleWeb.Api.StatsController do top_stats_entry(current_results, prev_results, "Views per visit", :views_per_visit), top_stats_entry(current_results, prev_results, "Bounce rate", :bounce_rate), top_stats_entry(current_results, prev_results, "Visit duration", :visit_duration), - top_stats_entry(current_results, prev_results, "Time on page", :time_on_page) + top_stats_entry(current_results, prev_results, "Time on page", :time_on_page, fn + nil -> 0 + value -> value + end) ] |> Enum.filter(& &1) diff --git a/test/plausible_web/controllers/api/external_stats_controller/aggregate_test.exs b/test/plausible_web/controllers/api/external_stats_controller/aggregate_test.exs index e6d8a0dd1..325987def 100644 --- a/test/plausible_web/controllers/api/external_stats_controller/aggregate_test.exs +++ b/test/plausible_web/controllers/api/external_stats_controller/aggregate_test.exs @@ -204,6 +204,56 @@ defmodule PlausibleWeb.Api.ExternalStatsController.AggregateTest do "error" => "Metrics cannot be queried multiple times." } end + + test "validates that time_on_page cannot be queried without a page filter", %{ + conn: conn, + site: site + } do + conn = + get(conn, "/api/v1/stats/aggregate", %{ + "site_id" => site.domain, + "metrics" => "time_on_page" + }) + + assert json_response(conn, 400) == %{ + "error" => + "Metric `time_on_page` can only be queried in a page breakdown or with a page filter." + } + end + + test "validates that time_on_page cannot be queried with a goal filter", %{ + conn: conn, + site: site + } do + insert(:goal, %{site: site, event_name: "Signup"}) + + conn = + get(conn, "/api/v1/stats/aggregate", %{ + "site_id" => site.domain, + "metrics" => "time_on_page", + "filters" => "event:page==/A;event:goal==Signup" + }) + + assert json_response(conn, 400) == %{ + "error" => "Metric `time_on_page` cannot be queried when filtering by `event:goal`" + } + end + + test "validates that time_on_page cannot be queried with an event:name filter", %{ + conn: conn, + site: site + } do + conn = + get(conn, "/api/v1/stats/aggregate", %{ + "site_id" => site.domain, + "metrics" => "time_on_page", + "filters" => "event:page==/A;event:name==Signup" + }) + + assert json_response(conn, 400) == %{ + "error" => "Metric `time_on_page` cannot be queried when filtering by `event:name`" + } + end end test "aggregates a single metric", %{conn: conn, site: site} do @@ -370,6 +420,56 @@ defmodule PlausibleWeb.Api.ExternalStatsController.AggregateTest do "conversion_rate" => %{"value" => 50.0, "change" => 16.7} } end + + test "can compare time_on_page with previous period", %{conn: conn, site: site} do + populate_stats(site, [ + build(:pageview, pathname: "/A", user_id: 111, timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/B", user_id: 111, timestamp: ~N[2021-01-01 00:01:00]), + build(:pageview, pathname: "/A", user_id: 999, timestamp: ~N[2021-01-02 00:00:00]), + build(:pageview, pathname: "/B", user_id: 999, timestamp: ~N[2021-01-02 00:01:30]) + ]) + + insert(:goal, %{site: site, event_name: "Signup"}) + + conn = + get(conn, "/api/v1/stats/aggregate", %{ + "site_id" => site.domain, + "period" => "day", + "date" => "2021-01-02", + "metrics" => "time_on_page", + "filters" => "event:page==/A", + "compare" => "previous_period" + }) + + assert json_response(conn, 200)["results"] == %{ + "time_on_page" => %{"value" => 90, "change" => 50.0} + } + end + + test "time_on_page change is nil if previous period returns a number but current period is nil", + %{conn: conn, site: site} do + populate_stats(site, [ + build(:pageview, pathname: "/A", user_id: 123, timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/B", user_id: 123, timestamp: ~N[2021-01-01 00:01:00]), + build(:pageview, pathname: "/A", timestamp: ~N[2021-01-02 00:00:00]) + ]) + + insert(:goal, %{site: site, event_name: "Signup"}) + + conn = + get(conn, "/api/v1/stats/aggregate", %{ + "site_id" => site.domain, + "period" => "day", + "date" => "2021-01-02", + "metrics" => "time_on_page", + "filters" => "event:page==/A", + "compare" => "previous_period" + }) + + assert json_response(conn, 200)["results"] == %{ + "time_on_page" => %{"value" => nil, "change" => nil} + } + end end describe "with imported data" do @@ -1313,6 +1413,58 @@ defmodule PlausibleWeb.Api.ExternalStatsController.AggregateTest do end describe "metrics" do + test "time_on_page with a page filter", %{conn: conn, site: site} do + populate_stats(site, [ + build(:pageview, + pathname: "/A", + user_id: 123, + timestamp: ~N[2021-01-01 00:00:00] + ), + build(:pageview, + pathname: "/another", + user_id: 123, + timestamp: ~N[2021-01-01 00:01:00] + ), + build(:pageview, + pathname: "/A", + user_id: 321, + timestamp: ~N[2021-01-01 00:00:00] + ), + build(:pageview, + pathname: "/another", + user_id: 321, + timestamp: ~N[2021-01-01 00:01:20] + ), + build(:pageview, pathname: "/A", timestamp: ~N[2021-01-01 00:00:00]) + ]) + + conn = + get(conn, "/api/v1/stats/aggregate", %{ + "site_id" => site.domain, + "period" => "day", + "date" => "2021-01-01", + "metrics" => "time_on_page", + "filters" => "event:page==/A" + }) + + assert json_response(conn, 200)["results"] == %{"time_on_page" => %{"value" => 70}} + end + + test "time_on_page is returned as `nil` if it cannot be calculated", %{conn: conn, site: site} do + populate_stats(site, [ + build(:pageview, pathname: "/A") + ]) + + conn = + get(conn, "/api/v1/stats/aggregate", %{ + "site_id" => site.domain, + "metrics" => "time_on_page", + "filters" => "event:page==/A" + }) + + assert json_response(conn, 200)["results"] == %{"time_on_page" => %{"value" => nil}} + end + test "conversion_rate when goal filter is applied", %{conn: conn, site: site} do populate_stats(site, [ build(:event, name: "Signup"), diff --git a/test/plausible_web/controllers/api/external_stats_controller/breakdown_test.exs b/test/plausible_web/controllers/api/external_stats_controller/breakdown_test.exs index 312034b40..4fa89a078 100644 --- a/test/plausible_web/controllers/api/external_stats_controller/breakdown_test.exs +++ b/test/plausible_web/controllers/api/external_stats_controller/breakdown_test.exs @@ -83,6 +83,24 @@ defmodule PlausibleWeb.Api.ExternalStatsController.BreakdownTest do end describe "param validation" do + test "time_on_page is not supported in breakdown queries other than by event:page", %{ + conn: conn, + site: site + } do + conn = + get(conn, "/api/v1/stats/breakdown", %{ + "site_id" => site.domain, + "property" => "visit:source", + "filters" => "event:page==/A", + "metrics" => "time_on_page" + }) + + assert json_response(conn, 400) == %{ + "error" => + "Metric `time_on_page` is not supported in breakdown queries (except `event:page` breakdown)" + } + end + test "does not allow querying conversion_rate without a goal filter", %{ conn: conn, site: site @@ -2018,6 +2036,126 @@ defmodule PlausibleWeb.Api.ExternalStatsController.BreakdownTest do end describe "metrics" do + test "returns time_on_page with imported data", %{conn: conn, site: site} do + site = + site + |> Plausible.Site.start_import(~D[2005-01-01], Timex.today(), "Google Analytics", "ok") + |> Plausible.Repo.update!() + + populate_stats(site, [ + build(:imported_pages, page: "/A", time_on_page: 40, date: ~D[2021-01-01]), + build(:imported_pages, page: "/A", time_on_page: 110, date: ~D[2021-01-01]), + build(:imported_pages, page: "/B", time_on_page: 499, date: ~D[2021-01-01]), + build(:pageview, pathname: "/A", user_id: 4, timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/B", user_id: 4, timestamp: ~N[2021-01-01 00:01:00]) + ]) + + conn = + get(conn, "/api/v1/stats/breakdown", %{ + "site_id" => site.domain, + "period" => "day", + "date" => "2021-01-01", + "property" => "event:page", + "metrics" => "visitors,time_on_page", + "with_imported" => "true" + }) + + assert json_response(conn, 200) == %{ + "results" => [ + %{ + "page" => "/A", + "visitors" => 3, + "time_on_page" => 70.0 + }, + %{ + "page" => "/B", + "visitors" => 2, + "time_on_page" => 499 + } + ] + } + end + + test "returns time_on_page in an event:page breakdown", %{conn: conn, site: site} do + populate_stats(site, [ + build(:pageview, pathname: "/A", timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/A", timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/B", timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/A", user_id: 4, timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/B", user_id: 4, timestamp: ~N[2021-01-01 00:01:00]), + build(:pageview, pathname: "/C", user_id: 4, timestamp: ~N[2021-01-01 00:02:30]) + ]) + + conn = + get(conn, "/api/v1/stats/breakdown", %{ + "site_id" => site.domain, + "period" => "day", + "date" => "2021-01-01", + "property" => "event:page", + "metrics" => "visitors,time_on_page" + }) + + assert json_response(conn, 200) == %{ + "results" => [ + %{ + "page" => "/A", + "visitors" => 3, + "time_on_page" => 60.0 + }, + %{ + "page" => "/B", + "visitors" => 2, + "time_on_page" => 90.0 + }, + %{ + "page" => "/C", + "visitors" => 1, + "time_on_page" => nil + } + ] + } + end + + test "returns time_on_page as the only metric in an event:page breakdown", %{ + conn: conn, + site: site + } do + populate_stats(site, [ + build(:pageview, pathname: "/A", timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/A", timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/B", timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/A", user_id: 4, timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/B", user_id: 4, timestamp: ~N[2021-01-01 00:01:00]), + build(:pageview, pathname: "/C", user_id: 4, timestamp: ~N[2021-01-01 00:02:30]) + ]) + + conn = + get(conn, "/api/v1/stats/breakdown", %{ + "site_id" => site.domain, + "period" => "day", + "date" => "2021-01-01", + "property" => "event:page", + "metrics" => "time_on_page" + }) + + assert json_response(conn, 200) == %{ + "results" => [ + %{ + "page" => "/B", + "time_on_page" => 90.0 + }, + %{ + "page" => "/A", + "time_on_page" => 60.0 + }, + %{ + "page" => "/C", + "time_on_page" => nil + } + ] + } + end + test "returns conversion_rate in an event:goal breakdown", %{conn: conn, site: site} do populate_stats(site, [ build(:event, name: "Signup", user_id: 1), diff --git a/test/plausible_web/controllers/api/stats_controller/top_stats_test.exs b/test/plausible_web/controllers/api/stats_controller/top_stats_test.exs index 380a932ee..97f8b9135 100644 --- a/test/plausible_web/controllers/api/stats_controller/top_stats_test.exs +++ b/test/plausible_web/controllers/api/stats_controller/top_stats_test.exs @@ -327,6 +327,42 @@ defmodule PlausibleWeb.Api.StatsController.TopStatsTest do |> Enum.find(&(&1["name"] == "Time on page")) end + test "bounce_rate is 0 when the page in filter was never a landing page", %{ + conn: conn, + site: site + } do + populate_stats(site, [ + build(:pageview, pathname: "/A", user_id: @user_id, timestamp: ~N[2021-01-01 00:00:00]), + build(:pageview, pathname: "/", user_id: @user_id, timestamp: ~N[2021-01-01 00:10:00]) + ]) + + filters = Jason.encode!(%{page: "/"}) + path = "/api/stats/#{site.domain}/top-stats?period=day&date=2021-01-01&filters=#{filters}" + + assert %{"name" => "Bounce rate", "value" => 0} == + conn + |> get(path) + |> json_response(200) + |> Map.fetch!("top_stats") + |> Enum.find(&(&1["name"] == "Bounce rate")) + end + + test "time_on_page is 0 when it can't be calculated", %{conn: conn, site: site} do + populate_stats(site, [ + build(:pageview, pathname: "/") + ]) + + filters = Jason.encode!(%{page: "/"}) + path = "/api/stats/#{site.domain}/top-stats?&filters=#{filters}" + + assert %{"name" => "Time on page", "value" => 0} == + conn + |> get(path) + |> json_response(200) + |> Map.fetch!("top_stats") + |> Enum.find(&(&1["name"] == "Time on page")) + end + test "ignores page refresh when calculating time on page", %{conn: conn, site: site} do populate_stats(site, [ build(:pageview, user_id: @user_id, timestamp: ~N[2021-01-01 00:00:00], pathname: "/"),