Skip to content

Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.

Stats api time on page (#3858)

RobertJoonas7641c66a2bf3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d202ff7cf1..118826f0a1 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 e356c189d5..56ded33f86 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 074cdcb6a6..ae33e4e737 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 d234d9aad2..aa03c3961c 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 ff87237edb..10078ff6a3 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 b2a82e5019..1825dbbd0b 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 11d8b838be..acc5a56e83 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 e6d8a0dd17..325987defc 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 312034b40a..4fa89a078d 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 380a932ee5..97f8b91353 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: "/"),