Skip to content

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

Put journey exploration under a single API call (#6268)

Adam Rutkowskibfa095d44207
diff --git a/assets/js/dashboard/stats/exploration.js b/assets/js/dashboard/stats/exploration.js
index 83ad58273a..b483ea6c2e 100644
--- a/assets/js/dashboard/stats/exploration.js
+++ b/assets/js/dashboard/stats/exploration.js
@@ -29,26 +29,27 @@ function toJourney(steps) {
return steps.map((s) => ({ name: s.name, pathname: s.pathname }))
}
-function fetchColumnData(site, dashboardState, steps, filter, direction) {
- // Page filters only apply to the first step — strip them for subsequent columns
- const stateToUse = stateWithApplicableFilters(dashboardState, steps)
- const journey = toJourney(steps)
-
- return api.post(url.apiPath(site, '/exploration/next'), stateToUse, {
- journey: JSON.stringify(journey),
- search_term: filter,
- direction
- })
-}
-
-function fetchFunnelData(site, dashboardState, steps, direction) {
+function fetchNextWithFunnel(
+ site,
+ dashboardState,
+ steps,
+ filter,
+ direction,
+ includeFunnel
+) {
const stateToUse = stateWithApplicableFilters(dashboardState, steps)
const journey = toJourney(steps)
- return api.post(url.apiPath(site, '/exploration/funnel'), stateToUse, {
- journey: JSON.stringify(journey),
- direction
- })
+ return api.post(
+ url.apiPath(site, '/exploration/next-with-funnel'),
+ stateToUse,
+ {
+ journey: JSON.stringify(journey),
+ search_term: filter,
+ direction,
+ include_funnel: includeFunnel
+ }
+ )
}
function fetchSuggestedJourney(site, dashboardState) {
@@ -65,71 +66,22 @@ function isSameStep(step, otherStep) {
function ExplorationColumn({
header,
- steps,
+ // null means column should not be rendered (no preceding step selected)
+ active,
+ results,
+ loading,
maxVisitors,
selected,
selectedVisitors,
selectedConversionRate,
onSelect,
- dashboardState,
- direction
+ onFilterChange,
+ filter
}) {
- const site = useSiteContext()
- const [loading, setLoading] = useState(steps !== null && !selected)
- const [results, setResults] = useState([])
- const [filter, setFilter] = useState('')
- const stepsFingerprint =
- steps === null
- ? null
- : steps.map((step) => `${step.name}:${step.pathname}`).join(';')
-
- const debouncedOnSearchInputChange = useDebounce((event) =>
- setFilter(event.target.value)
+ const debouncedOnFilterChange = useDebounce((event) =>
+ onFilterChange(event.target.value)
)
- useEffect(() => {
- if (steps === null) {
- setFilter('')
- setResults([])
- setLoading(false)
- return
- }
-
- if (selected) {
- // When a step is already selected (pre-populated by "Suggest a journey"),
- // fetch is unnecessary
- setLoading(false)
- return
- }
-
- setLoading(true)
- setResults([])
-
- let cancelled = false
-
- fetchColumnData(site, dashboardState, steps, filter, direction)
- .then((response) => {
- if (!cancelled) {
- setResults(response || [])
- }
- })
- .catch(() => {
- if (!cancelled) {
- setResults([])
- }
- })
- .finally(() => {
- if (!cancelled) {
- setLoading(false)
- }
- })
-
- return () => {
- cancelled = true
- }
- // eslint-disable-next-line react-hooks/exhaustive-deps
- }, [dashboardState, stepsFingerprint, filter, direction, site, selected])
-
const stepMaxVisitors = maxVisitors || results[0]?.visitors
// When a step is selected we show only that one item.
@@ -154,13 +106,13 @@ function ExplorationColumn({
<span className="shrink-0 text-xs font-medium text-gray-500 dark:text-gray-400">
{header}
</span>
- {!selected && steps !== null && (
+ {!selected && active && (
<input
data-testid="search-input"
type="text"
defaultValue={filter}
placeholder="Search"
- onChange={debouncedOnSearchInputChange}
+ onChange={debouncedOnFilterChange}
className="peer max-w-48 w-full text-xs dark:text-gray-100 block border-gray-300 dark:border-gray-750 rounded-md dark:bg-gray-750 dark:placeholder:text-gray-400 focus:outline-none focus:ring-3 focus:ring-indigo-500/20 dark:focus:ring-indigo-500/25 focus:border-indigo-500"
/>
)}
@@ -182,7 +134,7 @@ function ExplorationColumn({
</div>
) : results.length === 0 && !selected ? (
<div className="h-108 flex items-center justify-center text-sm text-gray-400 dark:text-gray-500">
- {steps === null ? 'Select an event to continue' : 'No data'}
+ {!active ? 'Select an event to continue' : 'No data'}
</div>
) : (
<ul className="flex flex-col gap-y-0.5 px-1.5 pb-1.5 h-108 overflow-y-auto">
@@ -259,10 +211,24 @@ export function FunnelExploration() {
const [steps, setSteps] = useState([])
const [direction, setDirection] = useState(EXPLORATION_DIRECTIONS.FORWARD)
const [funnel, setFunnel] = useState([])
+ // Results for the active (last, unselected) column
+ const [activeColumnResults, setActiveColumnResults] = useState([])
+ const [activeColumnFilter, setActiveColumnFilter] = useState('')
+ const [activeColumnLoading, setActiveColumnLoading] = useState(false)
+ // Initial visitor/bar data for a newly selected step, held until
+ // real funnel response arrives. Prevents from flashing "0 visitors"
+ // during the loading window.
+ const [provisionalFunnelEntries, setProvisionalFunnelEntries] = useState({})
// track in flight "Suggest a journey" request
const [isSuggestingJourney, setIsSuggestingJourney] = useState(false)
// counter to detect and discard stale suggestion responses
const suggestionRequestIdRef = useRef(0)
+ // Tracks the steps/direction/dashboardState values from the previous effect
+ // run so we can tell whether the journey changed (needs funnel) or only the
+ // search filter changed (next steps only, no funnel).
+ const prevStepsRef = useRef(steps)
+ const prevDirectionRef = useRef(direction)
+ const prevDashboardStateRef = useRef(dashboardState)
function cancelPendingSuggestion() {
suggestionRequestIdRef.current += 1
@@ -302,9 +268,38 @@ export function FunnelExploration() {
cancelPendingSuggestion()
}
+ // Reset the active-column filter whenever the journey changes
+ setActiveColumnFilter('')
+
if (selected === null) {
+ setProvisionalFunnelEntries({})
+ setActiveColumnResults([])
+ setActiveColumnLoading(true)
setSteps(steps.slice(0, columnIndex))
} else {
+ // Snapshot the clicked step's visitor count from the current results so
+ // the column can display a sensible value immediately, before the funnel
+ // API response arrives. The bar width is computed relative to the first
+ // step's visitor count (same baseline the real funnel uses).
+ const match = activeColumnResults.find(({ step }) =>
+ isSameStep(step, selected)
+ )
+ if (match) {
+ const firstStepVisitors = funnel[0]?.visitors ?? match.visitors
+ const conversionRate = Math.round(
+ (match.visitors / firstStepVisitors) * 100
+ )
+ setProvisionalFunnelEntries({
+ [columnIndex]: {
+ visitors: match.visitors,
+ conversion_rate: conversionRate
+ }
+ })
+ } else {
+ setProvisionalFunnelEntries({})
+ }
+ setActiveColumnResults([])
+ setActiveColumnLoading(true)
setSteps([...steps.slice(0, columnIndex), selected])
}
}
@@ -319,34 +314,68 @@ export function FunnelExploration() {
setDirection(nextDirection)
setSteps(steps.toReversed())
setFunnel([])
+ setActiveColumnResults([])
+ setActiveColumnFilter('')
+ setProvisionalFunnelEntries({})
}
+ // Fetch next step suggestions (and funnel, if the journey changed) whenever
+ // the journey, direction, dashboard filters, or search term change.
+ // Funnel is only re-fetched when steps or direction/dashboardState change,
+ // search doesn't affect it.
useEffect(() => {
- if (steps.length === 0) {
+ setActiveColumnLoading(true)
+ setActiveColumnResults([])
+
+ const journeyChanged =
+ prevStepsRef.current !== steps ||
+ prevDirectionRef.current !== direction ||
+ prevDashboardStateRef.current !== dashboardState
+
+ prevStepsRef.current = steps
+ prevDirectionRef.current = direction
+ prevDashboardStateRef.current = dashboardState
+
+ const includeFunnel = journeyChanged && steps.length > 0
+
+ if (journeyChanged && steps.length === 0) {
setFunnel([])
- return
}
let cancelled = false
- fetchFunnelData(site, dashboardState, steps, direction)
+ fetchNextWithFunnel(
+ site,
+ dashboardState,
+ steps,
+ activeColumnFilter,
+ direction,
+ includeFunnel
+ )
.then((response) => {
- if (!cancelled) {
- setFunnel(response || [])
+ if (cancelled) return
+ setActiveColumnResults(response?.next || [])
+ if (includeFunnel) {
+ setFunnel(response?.funnel || [])
+ setProvisionalFunnelEntries({})
}
})
.catch(() => {
- if (!cancelled) {
- setFunnel([])
- }
+ if (cancelled) return
+ setActiveColumnResults([])
+ if (includeFunnel) setFunnel([])
+ })
+ .finally(() => {
+ if (!cancelled) setActiveColumnLoading(false)
})
return () => {
cancelled = true
}
- }, [site, dashboardState, steps, direction])
+ }, [site, dashboardState, steps, direction, activeColumnFilter])
const numColumns = Math.max(steps.length + 1, 3)
+ const activeColumnIndex = steps.length
const scrollRef = useRef(null)
useEffect(() => {
@@ -407,20 +436,39 @@ export function FunnelExploration() {
ref={scrollRef}
className="flex gap-4 overflow-x-auto -mx-5 px-5 -mb-3 pb-3"
>
- {Array.from({ length: numColumns }, (_, i) => (
- <ExplorationColumn
- key={i}
- header={columnHeader(i, direction)}
- steps={steps.length >= i ? steps.slice(0, i) : null}
- selected={steps[i] || null}
- selectedVisitors={funnel[i]?.visitors ?? null}
- selectedConversionRate={funnel[i]?.conversion_rate ?? null}
- maxVisitors={funnel[0]?.visitors ?? null}
- onSelect={(selected) => handleSelect(i, selected)}
- dashboardState={dashboardState}
- direction={direction}
- />
- ))}
+ {Array.from({ length: numColumns }, (_, i) => {
+ const isActive = i === activeColumnIndex
+ const isReachable = steps.length >= i
+
+ return (
+ <ExplorationColumn
+ key={i}
+ header={columnHeader(i, direction)}
+ active={isReachable}
+ // Active column gets live results; selected columns show a single
+ // item sourced from funnel data (passed as selectedVisitors /
+ // selectedConversionRate) so they need no results of their own.
+ results={isActive ? activeColumnResults : []}
+ loading={isActive ? activeColumnLoading : false}
+ selected={steps[i] || null}
+ selectedVisitors={
+ funnel[i]?.visitors ??
+ provisionalFunnelEntries[i]?.visitors ??
+ null
+ }
+ selectedConversionRate={
+ funnel[i]?.conversion_rate ??
+ provisionalFunnelEntries[i]?.conversion_rate ??
+ null
+ }
+ maxVisitors={funnel[0]?.visitors ?? null}
+ onSelect={(selected) => handleSelect(i, selected)}
+ onFilterChange={isActive ? setActiveColumnFilter : () => {}}
+ filter={isActive ? activeColumnFilter : ''}
+ direction={direction}
+ />
+ )
+ })}
</div>
</div>
)
diff --git a/lib/plausible_web/controllers/api/stats_controller.ex b/lib/plausible_web/controllers/api/stats_controller.ex
index 9a41faff14..7db32d2f8f 100644
--- a/lib/plausible_web/controllers/api/stats_controller.ex
+++ b/lib/plausible_web/controllers/api/stats_controller.ex
@@ -29,6 +29,7 @@ defmodule PlausibleWeb.Api.StatsController do
when action in [
:exploration_next,
:exploration_funnel,
+ :exploration_next_with_funnel,
:exploration_interesting_funnel
]
@@ -179,6 +180,32 @@ defmodule PlausibleWeb.Api.StatsController do
end
end
+ def exploration_next_with_funnel(conn, %{"journey" => steps} = params) do
+ site = conn.assigns.site
+ search_term = params["search_term"] || ""
+ include_funnel? = params["include_funnel"] == true
+
+ with {:ok, journey} <- parse_journey(steps),
+ {:ok, direction} <- parse_exploration_direction(params["direction"]),
+ query = Query.from(site, params, debug_metadata: debug_metadata(conn)),
+ {:ok, next_steps} <- Exploration.next_steps(query, journey, search_term, direction),
+ funnel <- maybe_include_funnel(include_funnel?, query, journey, direction) do
+ json(conn, %{next: next_steps, funnel: funnel})
+ else
+ _ ->
+ bad_request(conn, "There was an error with your request")
+ end
+ end
+
+ defp maybe_include_funnel(true, query, journey, direction) do
+ case Exploration.journey_funnel(query, journey, direction) do
+ {:ok, funnel_data} -> funnel_data
+ {:error, :empty_journey} -> []
+ end
+ end
+
+ defp maybe_include_funnel(false, _, _, _), do: []
+
defp parse_journey(input) when is_binary(input) do
input
|> Jason.decode!()
diff --git a/lib/plausible_web/router.ex b/lib/plausible_web/router.ex
index d78f0b7dc4..1a47c3acce 100644
--- a/lib/plausible_web/router.ex
+++ b/lib/plausible_web/router.ex
@@ -284,6 +284,7 @@ defmodule PlausibleWeb.Router do
post "/:domain/exploration/next", StatsController, :exploration_next
post "/:domain/exploration/funnel", StatsController, :exploration_funnel
+ post "/:domain/exploration/next-with-funnel", StatsController, :exploration_next_with_funnel
post "/:domain/exploration/interesting-funnel",
StatsController,
diff --git a/test/plausible_web/controllers/api/stats_controller/exploration_test.exs b/test/plausible_web/controllers/api/stats_controller/exploration_test.exs
index 19b49f6dd3..12e561fa23 100644
--- a/test/plausible_web/controllers/api/stats_controller/exploration_test.exs
+++ b/test/plausible_web/controllers/api/stats_controller/exploration_test.exs
@@ -211,5 +211,184 @@ defmodule PlausibleWeb.Api.StatsController.ExplorationTest do
assert step3["conversion_rate_step"] == "100"
end
end
+
+ describe "exploration_next_with_funnel/2" do
+ test "returns next steps without funnel by default", %{conn: conn, site: site} do
+ journey =
+ Jason.encode!([
+ %{name: "pageview", pathname: "/home"},
+ %{name: "pageview", pathname: "/login"}
+ ])
+
+ resp =
+ conn
+ |> post("/api/stats/#{site.domain}/exploration/next-with-funnel", %{
+ "journey" => journey,
+ "period" => "24h"
+ })
+ |> json_response(200)
+
+ assert [next_step1, next_step2, next_step3] = resp["next"]
+ assert next_step1["step"]["label"] == "Visit /docs"
+ assert next_step1["step"]["pathname"] == "/docs"
+ assert next_step1["visitors"] == 1
+ assert next_step2["step"]["label"] == "Visit /home"
+ assert next_step2["step"]["pathname"] == "/home"
+ assert next_step2["visitors"] == 1
+ assert next_step3["step"]["label"] == "Visit /logout"
+ assert next_step3["step"]["pathname"] == "/logout"
+ assert next_step3["visitors"] == 1
+
+ assert resp["funnel"] == []
+ end
+
+ test "filters next steps by search_term", %{conn: conn, site: site} do
+ journey =
+ Jason.encode!([
+ %{name: "pageview", pathname: "/home"},
+ %{name: "pageview", pathname: "/login"}
+ ])
+
+ resp =
+ conn
+ |> post("/api/stats/#{site.domain}/exploration/next-with-funnel", %{
+ "journey" => journey,
+ "search_term" => "doc",
+ "period" => "24h"
+ })
+ |> json_response(200)
+
+ assert [next_step] = resp["next"]
+ assert next_step["step"]["pathname"] == "/docs"
+ assert next_step["visitors"] == 1
+ assert resp["funnel"] == []
+ end
+
+ test "supports backward direction for next steps", %{conn: conn, site: site} do
+ journey = Jason.encode!([%{name: "pageview", pathname: "/logout"}])
+
+ resp =
+ conn
+ |> post("/api/stats/#{site.domain}/exploration/next-with-funnel", %{
+ "journey" => journey,
+ "direction" => "backward",
+ "period" => "24h"
+ })
+ |> json_response(200)
+
+ assert [next_step1, next_step2] = resp["next"]
+ assert next_step1["step"]["pathname"] == "/docs"
+ assert next_step1["visitors"] == 1
+ assert next_step2["step"]["pathname"] == "/login"
+ assert next_step2["visitors"] == 1
+ assert resp["funnel"] == []
+ end
+
+ test "includes funnel when include_funnel is true", %{conn: conn, site: site} do
+ journey =
+ Jason.encode!([
+ %{name: "pageview", pathname: "/home"},
+ %{name: "pageview", pathname: "/login"},
+ %{name: "pageview", pathname: "/logout"}
+ ])
+
+ resp =
+ conn
+ |> post("/api/stats/#{site.domain}/exploration/next-with-funnel", %{
+ "journey" => journey,
+ "include_funnel" => true,
+ "period" => "24h"
+ })
+ |> json_response(200)
+
+ assert [step1, step2, step3] = resp["funnel"]
+
+ assert step1["step"]["label"] == "Visit /home"
+ assert step1["step"]["pathname"] == "/home"
+ assert step1["visitors"] == 2
+ assert step1["dropoff"] == 0
+ assert step1["dropoff_percentage"] == "0"
+ assert step1["conversion_rate"] == "100"
+ assert step1["conversion_rate_step"] == "0"
+ assert step2["step"]["label"] == "Visit /login"
+ assert step2["step"]["pathname"] == "/login"
+ assert step2["visitors"] == 2
+ assert step2["dropoff"] == 0
+ assert step2["dropoff_percentage"] == "0"
+ assert step2["conversion_rate"] == "100"
+ assert step2["conversion_rate_step"] == "100"
+ assert step3["step"]["label"] == "Visit /logout"
+ assert step3["step"]["pathname"] == "/logout"
+ assert step3["visitors"] == 1
+ assert step3["dropoff"] == 1
+ assert step3["dropoff_percentage"] == "50"
+ assert step3["conversion_rate"] == "50"
+ assert step3["conversion_rate_step"] == "50"
+ end
+
+ test "includes funnel with backward direction when include_funnel is true", %{
+ conn: conn,
+ site: site
+ } do
+ journey =
+ Jason.encode!([
+ %{name: "pageview", pathname: "/logout"},
+ %{name: "pageview", pathname: "/login"},
+ %{name: "pageview", pathname: "/home"}
+ ])
+
+ resp =
+ conn
+ |> post("/api/stats/#{site.domain}/exploration/next-with-funnel", %{
+ "journey" => journey,
+ "include_funnel" => true,
+ "direction" => "backward",
+ "period" => "24h"
+ })
+ |> json_response(200)
+
+ assert [step1, step2, step3] = resp["funnel"]
+
+ assert step1["step"]["pathname"] == "/logout"
+ assert step1["visitors"] == 2
+ assert step1["dropoff"] == 0
+ assert step1["dropoff_percentage"] == "0"
+ assert step1["conversion_rate"] == "100"
+ assert step1["conversion_rate_step"] == "0"
+ assert step2["step"]["pathname"] == "/login"
+ assert step2["visitors"] == 1
+ assert step2["dropoff"] == 1
+ assert step2["dropoff_percentage"] == "50"
+ assert step2["conversion_rate"] == "50"
+ assert step2["conversion_rate_step"] == "50"
+ assert step3["step"]["pathname"] == "/home"
+ assert step3["visitors"] == 1
+ assert step3["dropoff"] == 0
+ assert step3["dropoff_percentage"] == "0"
+ assert step3["conversion_rate"] == "50"
+ assert step3["conversion_rate_step"] == "100"
+ end
+
+ test "returns empty funnel when include_funnel is true but journey is empty", %{
+ conn: conn,
+ site: site
+ } do
+ journey = Jason.encode!([])
+
+ resp =
+ conn
+ |> post("/api/stats/#{site.domain}/exploration/next-with-funnel", %{
+ "journey" => journey,
+ "include_funnel" => true,
+ "period" => "24h"
+ })
+ |> json_response(200)
+
+ # An empty journey still returns starting-point candidates for `next`
+ assert is_list(resp["next"])
+ # Funnel requires at least one step; empty journey yields empty funnel
+ assert resp["funnel"] == []
+ end
+ end
end
end