Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.
TypeScript analyticsanalytics-dashboardclickhouseelixirgoogle-analyticsmarketingopen-source-analyticsphoenixplausible-analyticspostgresqlprivacyprivacy-friendlyself-hostedsimple-analyticsstatisticstailwindcssweb-analyticswebsite-analyticswebsite-statswebsite-tracking
Script v2: Show "Plausible not detected" errors with installation type specific recommendations (#5693)
Artur Pata88fccb697250
diff --git a/lib/plausible/installation_support/verification/diagnostics.ex b/lib/plausible/installation_support/verification/diagnostics.exindex ea19a03e1d..77b63221d0 100644--- a/lib/plausible/installation_support/verification/diagnostics.ex+++ b/lib/plausible/installation_support/verification/diagnostics.ex@@ -20,6 +20,8 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do@type t :: %__MODULE__{}+ @verify_manually_url "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"+alias Plausible.InstallationSupport.Resultdefmodule Error do@@ -62,8 +64,6 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do@spec interpret(t(), String.t(), String.t()) :: Result.t()def interpret(%__MODULE__{- plausible_is_on_window: true,- plausible_is_initialized: true,test_event: %{"normalizedBody" => %{"domain" => domain@@ -82,8 +82,6 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics dodef interpret(%__MODULE__{- plausible_is_on_window: true,- plausible_is_initialized: true,test_event: %{"normalizedBody" => %{"domain" => domain@@ -99,31 +97,23 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics dodomain == expected_domain,do: success()- @error_unexpected_domain Error.new!(%{- message: "Plausible test event is not for this site",- recommendation:- "Please check that the snippet on your site matches the installation instructions exactly",- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"- })def interpret(%__MODULE__{- plausible_is_on_window: true,- plausible_is_initialized: true,test_event: %{"normalizedBody" => %{"domain" => domain},"responseStatus" => response_status},- service_error: nil+ service_error: nil,+ selected_installation_type: selected_installation_type},expected_domain,_url)when response_status in [200, 202] anddomain != expected_domain,- do: error(@error_unexpected_domain)+ do: error_unexpected_domain(selected_installation_type)@error_proxy_network_error Error.new!(%{message:@@ -136,14 +126,11 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics domessage: "We couldn't verify your website",recommendation:"Please try verifying again in a few minutes, or verify your installation manually",- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"+ url: @verify_manually_url})def interpret(%__MODULE__{- plausible_is_on_window: true,- plausible_is_initialized: true,test_event: %{"requestUrl" => request_url,"responseStatus" => response_status@@ -185,8 +172,7 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics domessage: "We couldn't find your website at <%= @attempted_url %>",recommendation:"Please check that the domain you entered is correct and reachable publicly. If it's intentionally private, you'll need to verify that Plausible works manually",- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"+ url: @verify_manually_url})def interpret(%__MODULE__{service_error: service_error}, expected_domain, url)@@ -202,9 +188,8 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics domessage:"We couldn't verify your website at <%= @attempted_url %>",recommendation:- "Our verification tool encountered a network error while trying to verify your website. Please verify your integration manually",- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"+ "Accessing the website resulted in a network error. Please verify your installation manually",+ url: @verify_manually_url})def interpret(%__MODULE__{service_error: "net::" <> _}, _expected_domain, url)@@ -216,14 +201,13 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do|> struct!(data: %{offer_custom_url_input: true})end- @error_non_200_page_response Error.new!(%{- message:- "We couldn't verify your website at <%= @attempted_url %>",- recommendation:- "Our verification tool encountered a <%= @page_response_status %> error. Please check for anything that might be blocking it from reaching your site, like a firewall, authentication requirements, or CDN rules. If you'd prefer, you can skip this and verify your integration manually",- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"- })+ @error_unexpected_page_response Error.new!(%{+ message:+ "We couldn't verify your website at <%= @attempted_url %>",+ recommendation:+ "Accessing the website resulted in an unexpected status code <%= @page_response_status %>. Please check for anything that might be blocking us from reaching your site, like a firewall, authentication requirements, or CDN rules. If you'd prefer, you can skip this and verify your installation manually",+ url: @verify_manually_url+ })def interpret(%__MODULE__{@@ -234,22 +218,27 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do_expected_domain,url)- when is_binary(url) and page_response_status != 200 and plausible_is_on_window != true and+ when is_binary(url) and not is_nil(page_response_status) and+ (page_response_status < 200 or page_response_status >= 300) and+ plausible_is_on_window != true andplausible_is_initialized != true doattempted_url = shorten_url(url)- @error_non_200_page_response+ @error_unexpected_page_response|> error(attempted_url: attempted_url, page_response_status: page_response_status)|> struct!(data: %{offer_custom_url_input: true})end- @unknown_error Error.new!(%{- message: "Your Plausible integration is not working",- recommendation:- "Please manually check your integration to make sure that the Plausible snippet has been inserted correctly",- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"- })+ def interpret(+ %__MODULE__{+ selected_installation_type: selected_installation_type,+ plausible_is_on_window: false,+ service_error: nil+ },+ _expected_domain,+ _url+ ),+ do: error_plausible_not_found(selected_installation_type)def interpret(%__MODULE__{} = diagnostics, _expected_domain, url) doSentry.capture_message("Unhandled case for site verification (v2)",@@ -260,7 +249,78 @@ defmodule Plausible.InstallationSupport.Verification.Diagnostics do})- error(@unknown_error)+ error_plausible_not_found(diagnostics.selected_installation_type)+ end++ @message_plausible_not_found "We couldn't detect Plausible on your site"+ @error_plausible_not_found_for_manual Error.new!(%{+ message: @message_plausible_not_found,+ recommendation:+ "Please make sure you've copied snippet to the head of your site, or verify your installation manually",+ url: @verify_manually_url+ })+ @error_plausible_not_found_for_npm Error.new!(%{+ message: @message_plausible_not_found,+ recommendation:+ "Please make sure you've initialized Plausible on your site, or verify your installation manually",+ url: @verify_manually_url+ })+ @error_plausible_not_found_for_gtm Error.new!(%{+ message: @message_plausible_not_found,+ recommendation:+ "Please make sure you've configured the GTM template correctly, or verify your installation manually",+ url: @verify_manually_url+ })+ @error_plausible_not_found_for_wordpress Error.new!(%{+ message: @message_plausible_not_found,+ recommendation:+ "Please make sure you've enabled the plugin, or verify your installation manually",+ url: @verify_manually_url+ })+ defp error_plausible_not_found(selected_installation_type) do+ case selected_installation_type do+ "npm" -> error(@error_plausible_not_found_for_npm)+ "gtm" -> error(@error_plausible_not_found_for_gtm)+ "wordpress" -> error(@error_plausible_not_found_for_wordpress)+ _ -> error(@error_plausible_not_found_for_manual)+ end+ end++ @unexpected_domain_message "Plausible test event is not for this site"+ @error_unexpected_domain_for_manual Error.new!(%{+ message: @unexpected_domain_message,+ recommendation:+ "Please check that the snippet on your site matches the installation instructions exactly, or verify your installation manually",+ url: @verify_manually_url+ })++ @error_unexpected_domain_for_npm Error.new!(%{+ message: @unexpected_domain_message,+ recommendation:+ "Please check that you've initialized Plausible with the correct domain, or verify your installation manually",+ url: @verify_manually_url+ })++ @error_unexpected_domain_for_gtm Error.new!(%{+ message: @unexpected_domain_message,+ recommendation:+ "Please check that you've entered the ID in the GTM template correctly, or verify your installation manually",+ url: @verify_manually_url+ })++ @error_unexpected_domain_for_wordpress Error.new!(%{+ message: @unexpected_domain_message,+ recommendation:+ "Please check that you've installed the WordPress plugin correctly, or verify your installation manually",+ url: @verify_manually_url+ })+ defp error_unexpected_domain(selected_installation_type) do+ case selected_installation_type do+ "npm" -> error(@error_unexpected_domain_for_npm)+ "gtm" -> error(@error_unexpected_domain_for_gtm)+ "wordpress" -> error(@error_unexpected_domain_for_wordpress)+ _ -> error(@error_unexpected_domain_for_manual)+ endenddefp shorten_url(url) dodiff --git a/test/plausible/installation_support/verification/diagnostics_test.exs b/test/plausible/installation_support/verification/diagnostics_test.exsindex 5fd7599c19..040ccf9ac3 100644--- a/test/plausible/installation_support/verification/diagnostics_test.exs+++ b/test/plausible/installation_support/verification/diagnostics_test.exs@@ -6,21 +6,23 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest dodescribe "interpreting diagnostics" dofor status <- [200, 202] do- test "success with response status #{status}" do+ test "returns success if test event response status is #{status} and domain is as expected" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- plausible_is_on_window: true,- plausible_is_initialized: true,- test_event: %{- "normalizedBody" => %{- "domain" => "example.com"+ diagnostics =+ %Diagnostics{+ plausible_is_on_window: true,+ plausible_is_initialized: true,+ test_event: %{+ "normalizedBody" => %{+ "domain" => "example.com"+ },+ "responseStatus" => unquote(status)},- "responseStatus" => unquote(status)- },- service_error: nil- }+ service_error: nil,+ diagnostics_are_from_cache_bust: nil+ }assert Diagnostics.interpret(diagnostics, expected_domain, url_to_verify) == %Result{ok?: true@@ -28,22 +30,23 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest doendend- test "error when it 'succeeds', but only after cache bust" do+ test "returns error when it 'succeeds', but only after cache bust" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- plausible_is_on_window: true,- plausible_is_initialized: true,- test_event: %{- "normalizedBody" => %{- "domain" => "example.com"+ diagnostics =+ %Diagnostics{+ plausible_is_on_window: true,+ plausible_is_initialized: true,+ test_event: %{+ "normalizedBody" => %{+ "domain" => "example.com"+ },+ "responseStatus" => 200},- "responseStatus" => 200- },- diagnostics_are_from_cache_bust: true,- service_error: nil- }+ diagnostics_are_from_cache_bust: true,+ service_error: nil+ }assert_matches %Result{ok?: false,@@ -58,48 +61,62 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest do} = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)end- test "error when test event domain doesn't match expected domain" do- expected_domain = "example.com"- url_to_verify = "https://#{expected_domain}"+ for {installation_type, expected_recommendation} <- [+ {"wordpress",+ "Please check that you've installed the WordPress plugin correctly, or verify your installation manually"},+ {"gtm",+ "Please check that you've entered the ID in the GTM template correctly, or verify your installation manually"},+ {"npm",+ "Please check that you've initialized Plausible with the correct domain, or verify your installation manually"},+ {"manual",+ "Please check that the snippet on your site matches the installation instructions exactly, or verify your installation manually"}+ ] do+ test "returns error when test event domain doesn't match the expected domain, with recommendation for installation type: #{installation_type}" do+ expected_domain = "example.com"+ url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- plausible_is_on_window: true,- plausible_is_initialized: true,- test_event: %{- "normalizedBody" => %{- "domain" => "wrong-domain.com"- },- "responseStatus" => 200- },- service_error: nil- }+ diagnostics =+ %Diagnostics{+ selected_installation_type: unquote(installation_type),+ plausible_is_on_window: true,+ plausible_is_initialized: true,+ test_event: %{+ "normalizedBody" => %{+ "domain" => "wrong-domain.com"+ },+ "responseStatus" => 200+ },+ service_error: nil+ }- assert_matches %Result{- ok?: false,- errors: [^any(:string, ~r/.*not for this site.*/)],- recommendations: [- %{- text: ^any(:string, ~r/.*snippet.*/),- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"- }- ]- } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)+ assert_matches %Result{+ ok?: false,+ errors: ["Plausible test event is not for this site"],+ recommendations: [+ %{+ text: unquote(expected_recommendation),+ url:+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"+ }+ ]+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)+ endend- test "error when proxy network error occurs" do+ test "returns error when proxy network error occurs" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- plausible_is_on_window: true,- plausible_is_initialized: true,- test_event: %{- "requestUrl" => "https://proxy.example.com/event",- "responseStatus" => 500- },- service_error: nil- }+ diagnostics =+ %Diagnostics{+ plausible_is_on_window: true,+ plausible_is_initialized: true,+ test_event: %{+ "requestUrl" => "https://proxy.example.com/event",+ "responseStatus" => 500+ },+ service_error: nil+ }assert_matches %Result{ok?: false,@@ -113,19 +130,20 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest do} = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)end- test "error when plausible network error occurs" do+ test "returns error when Plausible network error occurs" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- plausible_is_on_window: true,- plausible_is_initialized: true,- test_event: %{- "requestUrl" => PlausibleWeb.Endpoint.url() <> "/api/event",- "responseStatus" => 500- },- service_error: nil- }+ diagnostics =+ %Diagnostics{+ plausible_is_on_window: true,+ plausible_is_initialized: true,+ test_event: %{+ "requestUrl" => PlausibleWeb.Endpoint.url() <> "/api/event",+ "responseStatus" => 500+ },+ service_error: nil+ }assert_matches %Result{ok?: false,@@ -140,14 +158,16 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest do} = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)end- test "error when disallowed by CSP" do+ test "returns error when Plausible domain is disallowed by CSP" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- disallowed_by_csp: true,- service_error: nil- }+ diagnostics =+ %Diagnostics{+ disallowed_by_csp: true,+ test_event: nil,+ service_error: nil+ }assert_matches %Result{ok?: false,@@ -163,15 +183,16 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest doendfor error_code <- [:domain_not_found, :invalid_url] do- test "error when DNS check fails (#{error_code})" do+ test "returns error when DNS check fails (with error code: #{error_code})" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- plausible_is_on_window: nil,- plausible_is_initialized: nil,- service_error: unquote(error_code)- }+ diagnostics =+ %Diagnostics{+ plausible_is_on_window: nil,+ plausible_is_initialized: nil,+ service_error: unquote(error_code)+ }assert_matches %Result{ok?: false,@@ -190,28 +211,27 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest doendend- test "error when Browserless encounters a network error during verification" do+ test "returns error when there's a network error during verification, offers custom URL input" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}?plausible_verification=123123123"- diagnostics = %Diagnostics{- plausible_is_on_window: nil,- plausible_is_initialized: nil,- service_error: "net::ERR_CONNECTION_CLOSED at https://example.com"- }+ diagnostics =+ %Diagnostics{+ plausible_is_on_window: nil,+ plausible_is_initialized: nil,+ service_error: "net::ERR_CONNECTION_CLOSED at https://example.com"+ }assert_matches %Result{ok?: false,data: %{offer_custom_url_input: true},errors: [- ^any(- :string,- ~r/.*couldn't verify your website at https:\/\/#{expected_domain}$/- )+ "We couldn't verify your website at https://example.com"],recommendations: [%{- text: ^any(:string, ~r/.*verify your integration manually.*/),+ text:+ "Accessing the website resulted in a network error. Please verify your installation manually",url:"https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"}@@ -219,32 +239,30 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest do} = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)end- test "error when plausible not installed and page.goto(url) response is not 200" do+ test "returns error when Plausible not installed and website response status is not 200, offers custom URL input" doexpected_domain = "example.com"url_to_verify = "https://#{expected_domain}?plausible_verification=123123123"- diagnostics = %Diagnostics{- plausible_is_on_window: false,- plausible_is_initialized: nil,- response_status: 403- }+ diagnostics =+ %Diagnostics{+ disallowed_by_csp: false,+ plausible_is_on_window: false,+ plausible_is_initialized: false,+ test_event: %{"error" => "Timed out"},+ response_status: 403,+ service_error: nil+ }assert_matches %Result{ok?: false,data: %{offer_custom_url_input: true},errors: [- ^any(- :string,- ~r/.*couldn't verify your website at https:\/\/#{expected_domain}.*/- )+ "We couldn't verify your website at https://example.com"],recommendations: [%{text:- ^any(- :string,- ~r/403 error.*firewall.*authentication.*CDN.*verify your integration manually/- ),+ "Accessing the website resulted in an unexpected status code 403. Please check for anything that might be blocking us from reaching your site, like a firewall, authentication requirements, or CDN rules. If you'd prefer, you can skip this and verify your installation manually",url:"https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"}@@ -252,28 +270,68 @@ defmodule Plausible.InstallationSupport.Verification.DiagnosticsTest do} = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)end- test "unknown error when no specific case matches" do- expected_domain = "example.com"- url_to_verify = "https://#{expected_domain}"+ for {installation_type, expected_recommendation} <- [+ {"wordpress",+ "Please make sure you've enabled the plugin, or verify your installation manually"},+ {"gtm",+ "Please make sure you've configured the GTM template correctly, or verify your installation manually"},+ {"npm",+ "Please make sure you've initialized Plausible on your site, or verify your installation manually"},+ {"manual",+ "Please make sure you've copied snippet to the head of your site, or verify your installation manually"}+ ] do+ test "returns error \"We couldn't detect Plausible on your site\" when plausible_is_on_window is false (with best guess recommendation for installation type: #{installation_type})" do+ expected_domain = "example.com"+ url_to_verify = "https://#{expected_domain}"- diagnostics = %Diagnostics{- plausible_is_on_window: false,- plausible_is_initialized: false,- response_status: 200,- service_error: nil- }+ diagnostics =+ %Diagnostics{+ response_status: 200,+ disallowed_by_csp: false,+ plausible_is_on_window: false,+ service_error: nil,+ test_event: %{"error" => "Timed out"},+ selected_installation_type: unquote(installation_type)+ }- assert_matches %Result{- ok?: false,- errors: [^any(:string, ~r/.*integration is not working.*/)],- recommendations: [- %{- text: ^any(:string, ~r/.*manually check.*/),- url:- "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"- }- ]- } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)+ assert_matches %Result{+ ok?: false,+ errors: ["We couldn't detect Plausible on your site"],+ recommendations: [+ %{+ text: unquote(expected_recommendation),+ url:+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"+ }+ ]+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)+ end++ test "falls back to error \"We couldn't detect Plausible on your site\" when no other case matches (with best guess recommendation for installation type: #{installation_type}), sends diagnostics to Sentry" do+ expected_domain = "example.com"+ url_to_verify = "https://#{expected_domain}"++ diagnostics =+ %Diagnostics{+ selected_installation_type: unquote(installation_type),+ disallowed_by_csp: nil,+ response_status: nil,+ service_error: nil,+ test_event: nil+ }++ assert_matches %Result{+ ok?: false,+ errors: ["We couldn't detect Plausible on your site"],+ recommendations: [+ %{+ text: unquote(expected_recommendation),+ url:+ "https://plausible.io/docs/troubleshoot-integration#how-to-manually-check-your-integration"+ }+ ]+ } = Diagnostics.interpret(diagnostics, expected_domain, url_to_verify)+ endendendenddiff --git a/tracker/test/support/types.ts b/tracker/test/support/types.tsindex 128c64fce8..825858afcf 100644--- a/tracker/test/support/types.ts+++ b/tracker/test/support/types.ts@@ -52,7 +52,6 @@ export type VerifyV2Result = {plausibleVersion: numberplausibleVariant?: stringdisallowedByCsp: boolean- cookieBannerLikely: booleancookiesConsentResult: ConsentResulttestEvent: {/**