2023-07-12 11:28:07 +03:00
<!DOCTYPE html>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< meta http-equiv = "x-ua-compatible" content = "ie=edge" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
2023-07-25 10:58:48 +03:00
< meta name = "generator" content = "ExDoc v0.30.3" >
2023-07-12 11:28:07 +03:00
< meta name = "project" content = "Plausible v0.0.1" >
< title > PlausibleWeb.StatsController — Plausible v0.0.1< / title >
2023-07-25 10:58:48 +03:00
< link rel = "stylesheet" href = "dist/html-elixir-P5GXSCHE.css" / >
2023-07-12 11:28:07 +03:00
< script src = "dist/handlebars.runtime-NWIB6V2M.js" > < / script >
2023-07-25 10:58:48 +03:00
< script src = "dist/handlebars.templates-NBND3S2D.js" > < / script >
2023-09-04 15:56:06 +03:00
< script src = "dist/sidebar_items-AC4564C4.js" > < / script >
2023-07-12 11:28:07 +03:00
< script src = "docs_config.js" > < / script >
2023-07-25 10:58:48 +03:00
< script async src = "dist/html-CGDDOCMI.js" > < / script >
2023-07-12 11:28:07 +03:00
< / head >
< body data-type = "modules" class = "page-module" >
< script >
try {
var settings = JSON.parse(localStorage.getItem('ex_doc:settings') || '{}');
if (settings.theme === 'dark' ||
((settings.theme === 'system' || settings.theme == null) & &
window.matchMedia('(prefers-color-scheme: dark)').matches)
) {
document.body.classList.add('dark')
}
} catch (error) { }
< / script >
< div class = "main" >
< button class = "sidebar-button sidebar-toggle" aria-label = "toggle sidebar" >
< i class = "ri-menu-line ri-lg" title = "Collapse/expand sidebar" > < / i >
< / button >
< section class = "sidebar" >
< form class = "sidebar-search" action = "search.html" >
< button type = "submit" class = "search-button" aria-label = "Submit Search" >
< i class = "ri-search-2-line" aria-hidden = "true" title = "Submit search" > < / i >
< / button >
< button type = "button" tabindex = "-1" class = "search-close-button" aria-label = "Cancel Search" >
< i class = "ri-close-line ri-lg" aria-hidden = "true" title = "Cancel search" > < / i >
< / button >
< label class = "search-label" >
< p class = "sr-only" > Search< / p >
< input name = "q" type = "text" class = "search-input" placeholder = "Search..." aria-label = "Input your search terms" autocomplete = "off" autocorrect = "off" autocapitalize = "off" spellcheck = "false" / >
< / label >
< / form >
< div class = "autocomplete" >
< div class = "autocomplete-results" >
< / div >
< / div >
< div class = "sidebar-header" >
< a href = "readme.html" >
< img src = "assets/logo.png" alt = "Plausible" class = "sidebar-projectImage" >
< / a >
< div class = "sidebar-projectDetails" >
< a href = "readme.html" class = "sidebar-projectName" translate = "no" >
Plausible
< / a >
< div class = "sidebar-projectVersion" translate = "no" >
v0.0.1
< / div >
< / div >
< ul class = "sidebar-listNav" >
< li > < a id = "extras-list-link" href = "#full-list" > Pages< / a > < / li >
< li > < a id = "modules-list-link" href = "#full-list" > Modules< / a > < / li >
< li > < a id = "tasks-list-link" href = "#full-list" > < span translate = "no" > Mix< / span > Tasks< / a > < / li >
< / ul >
< / div >
< div class = "gradient" > < / div >
< ul id = "full-list" > < / ul >
< / section >
< section class = "content" >
< output role = "status" id = "toast" > < / output >
< div class = "content-outer" >
< div id = "content" class = "content-inner" >
< h1 >
< button class = "icon-action display-settings" >
< i class = "ri-settings-3-line" > < / i >
< span class = "sr-only" > Settings< / span >
< / button >
< a href = "https://github.com/plausible/analytics/blob/main/lib/plausible_web/controllers/stats_controller.ex#L1" title = "View Source" class = "icon-action" rel = "help" >
< i class = "ri-code-s-slash-line" aria-hidden = "true" > < / i >
< span class = "sr-only" > View Source< / span >
< / a >
< span translate = "no" > PlausibleWeb.StatsController< / span >
< small class = "app-vsn" translate = "no" > (Plausible v0.0.1)< / small >
< / h1 >
< section id = "moduledoc" >
< p > This controller is responsible for rendering stats dashboards.< / p > < p > The stats dashboards are currently the only part of the app that uses client-side
rendering. Since the dashboards are heavily interactive, they are built with React
which is an appropriate choice for highly interactive browser UIs.< / p > < div class = "mermaid" > sequenceDiagram
Browser->>StatsController: GET /mydomain.com
StatsController-->>Browser: StatsView.render("stats.html")
Note left of Browser: ReactDom.render(Dashboard)
Browser -) Api.StatsController: GET /api/stats/mydomain.com/top-stats
Api.StatsController --) Browser: {"top_stats": [...]}
Note left of Browser: TopStats.render()
Browser -) Api.StatsController: GET /api/stats/mydomain.com/main-graph
Api.StatsController --) Browser: [{"plot": [...], "labels": [...]}, ...]
Note left of Browser: VisitorGraph.render()
Browser -) Api.StatsController: GET /api/stats/mydomain.com/sources
Api.StatsController --) Browser: [{"name": "Google", "visitors": 292150}, ...]
Note left of Browser: Sources.render()
Note over Browser,StatsController: And so on, for all reports in the viewport< / div > < p > This reasoning for this sequence is as follows:< / p > < ol > < li > First paint is fast because it doesn't do any data aggregation yet - good UX< / li > < li > The basic structure of the dashboard is rendered with spinners before reports are ready - good UX< / li > < li > Rendering on the frontend allows for maximum interactivity. Re-rendering and re-fetching can be as granular as needed.< / li > < li > Routing on the frontend allows the user to navigate the dashboard without reloading the page and losing context< / li > < li > Rendering on the frontend allows caching results in the browser to reduce pressure on backends and storage
3.1 No client-side caching has been implemented yet. This is still theoretical. See < a href = "https://github.com/plausible/analytics/discussions/1278" > https://github.com/plausible/analytics/discussions/1278< / a >
3.2 This is a big potential opportunity, because analytics data is mostly immutable. Clients can cache all historical data.< / li > < li > Since frontend rendering & navigation is harder to build and maintain than regular server-rendered HTML, we don't use SPA-style rendering anywhere else
.The only place currently where the benefits outweigh the costs is the dashboard.< / li > < / ol >
< / section >
< section id = "summary" class = "details-list" >
< h1 class = "section-heading" >
< a class = "hover-link" href = "#summary" >
< i class = "ri-link-m" aria-hidden = "true" > < / i >
2023-07-25 10:58:48 +03:00
Summary
2023-07-12 11:28:07 +03:00
< / a >
< / h1 >
< div class = "summary-functions summary" >
< h2 >
< a href = "#functions" > Functions< / a >
< / h2 >
< div class = "summary-row" >
< div class = "summary-signature" >
< a href = "#authenticate_shared_link/2" translate = "no" > authenticate_shared_link(conn, map)< / a >
< / div >
< / div >
< div class = "summary-row" >
< div class = "summary-signature" >
< a href = "#csv_export/2" translate = "no" > csv_export(conn, params)< / a >
< / div >
< div class = "summary-synopsis" > < p > The export is limited to 300 entries for other reports and 100 entries for pages because bigger result sets
start causing failures. Since we request data like time on page or bounce_rate for pages in a separate query
using the IN filter, it causes the requests to balloon in payload size.< / p > < / div >
< / div >
< div class = "summary-row" >
< div class = "summary-signature" >
< a href = "#shared_link/2" translate = "no" > shared_link(conn, arg2)< / a >
< / div >
< div class = "summary-synopsis" > < p > Authorizes and renders a shared link< / p > < / div >
< / div >
< div class = "summary-row" >
< div class = "summary-signature" >
< a href = "#stats/2" translate = "no" > stats(conn, params)< / a >
< / div >
< / div >
< / div >
< / section >
< section id = "functions" class = "details-list" >
< h1 class = "section-heading" >
< a class = "hover-link" href = "#functions" >
< i class = "ri-link-m" aria-hidden = "true" > < / i >
Functions
2023-07-25 10:58:48 +03:00
< / a >
2023-07-12 11:28:07 +03:00
< / h1 >
< div class = "functions-list" >
< section class = "detail" id = "authenticate_shared_link/2" >
< div class = "detail-header" >
< a href = "#authenticate_shared_link/2" class = "detail-link" title = "Link to this function" >
< i class = "ri-link-m" aria-hidden = "true" > < / i >
< span class = "sr-only" > Link to this function< / span >
< / a >
< h1 class = "signature" translate = "no" > authenticate_shared_link(conn, map)< / h1 >
2023-08-31 17:16:01 +03:00
< a href = "https://github.com/plausible/analytics/blob/main/lib/plausible_web/controllers/stats_controller.ex#L267" class = "icon-action" rel = "help" title = "View Source" >
2023-07-12 11:28:07 +03:00
< i class = "ri-code-s-slash-line" aria-hidden = "true" > < / i >
< span class = "sr-only" > View Source< / span >
< / a >
< / div >
< section class = "docstring" >
< / section >
< / section >
< section class = "detail" id = "csv_export/2" >
< div class = "detail-header" >
< a href = "#csv_export/2" class = "detail-link" title = "Link to this function" >
< i class = "ri-link-m" aria-hidden = "true" > < / i >
< span class = "sr-only" > Link to this function< / span >
< / a >
< h1 class = "signature" translate = "no" > csv_export(conn, params)< / h1 >
2023-07-21 11:19:59 +03:00
< a href = "https://github.com/plausible/analytics/blob/main/lib/plausible_web/controllers/stats_controller.ex#L97" class = "icon-action" rel = "help" title = "View Source" >
2023-07-12 11:28:07 +03:00
< i class = "ri-code-s-slash-line" aria-hidden = "true" > < / i >
< span class = "sr-only" > View Source< / span >
< / a >
< / div >
< section class = "docstring" >
< p > The export is limited to 300 entries for other reports and 100 entries for pages because bigger result sets
start causing failures. Since we request data like time on page or bounce_rate for pages in a separate query
using the IN filter, it causes the requests to balloon in payload size.< / p >
< / section >
< / section >
< section class = "detail" id = "shared_link/2" >
< div class = "detail-header" >
< a href = "#shared_link/2" class = "detail-link" title = "Link to this function" >
< i class = "ri-link-m" aria-hidden = "true" > < / i >
< span class = "sr-only" > Link to this function< / span >
< / a >
< h1 class = "signature" translate = "no" > shared_link(conn, arg2)< / h1 >
2023-08-31 17:16:01 +03:00
< a href = "https://github.com/plausible/analytics/blob/main/lib/plausible_web/controllers/stats_controller.ex#L193" class = "icon-action" rel = "help" title = "View Source" >
2023-07-12 11:28:07 +03:00
< i class = "ri-code-s-slash-line" aria-hidden = "true" > < / i >
< span class = "sr-only" > View Source< / span >
< / a >
< / div >
< section class = "docstring" >
< p > Authorizes and renders a shared link:< / p > < ol > < li > < p > Shared link with no password protection: needs to just make sure the shared link entry is still
in our database. This check makes sure shared link access can be revoked by the site admins. If the
shared link exists, render it directly.< / p > < / li > < li > < p > Shared link with password protection: Same checks as without the password, but an extra step is taken to
protect the page with a password. When the user passes the password challenge, a cookie is set with Plausible.Auth.Token.sign_shared_link().
The cookie allows the user to access the dashboard for 24 hours without entering the password again.< / p > < / li > < / ol > < p > ### Backwards compatibility< / p > < p > The URL format for shared links was changed in < a href = "https://github.com/plausible/analytics/pull/752" > this pull request< / a > in order
to make the URLs easier to bookmark. The old format is supported along with the new in order to not break old links.< / p > < p > See: < a href = "https://plausible.io/docs/shared-links" > https://plausible.io/docs/shared-links< / a > < / p >
< / section >
< / section >
< section class = "detail" id = "stats/2" >
< div class = "detail-header" >
< a href = "#stats/2" class = "detail-link" title = "Link to this function" >
< i class = "ri-link-m" aria-hidden = "true" > < / i >
< span class = "sr-only" > Link to this function< / span >
< / a >
< h1 class = "signature" translate = "no" > stats(conn, params)< / h1 >
< a href = "https://github.com/plausible/analytics/blob/main/lib/plausible_web/controllers/stats_controller.ex#L51" class = "icon-action" rel = "help" title = "View Source" >
< i class = "ri-code-s-slash-line" aria-hidden = "true" > < / i >
< span class = "sr-only" > View Source< / span >
< / a >
< / div >
< section class = "docstring" >
< / section >
< / section >
< / div >
< / section >
< footer class = "footer" >
< p >
< span class = "line" >
< button class = "a-main footer-button display-quick-switch" title = "Search HexDocs packages" >
Search HexDocs
< / button >
< a href = "Plausible.epub" title = "ePub version" >
Download ePub version
< / a >
< / span >
< / p >
< p class = "built-using" >
Built using
2023-07-25 10:58:48 +03:00
< a href = "https://github.com/elixir-lang/ex_doc" title = "ExDoc" target = "_blank" rel = "help noopener" translate = "no" > ExDoc< / a > (v0.30.3) for the
2023-07-12 11:28:07 +03:00
< a href = "https://elixir-lang.org" title = "Elixir" target = "_blank" translate = "no" > Elixir programming language< / a >
< / p >
< / footer >
< / div >
< / div >
< / section >
< / div >
< script src = "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js" > < / script >
< script > mermaid . initialize ( { startOnLoad : true } ) < / script >
< / body >
< / html >
