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.
pull/3886/head r2024.03.12-390
RobertJoonas 3 years ago committed by GitHub
parent dea9287d74
commit 7641c66a2b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

@ -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

@ -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)}

@ -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

@ -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()

@ -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

@ -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" ->

@ -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)

@ -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"),

@ -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),

@ -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: "/"),

Loading…
Cancel
Save