Skip to content

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

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.ex
index 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.Result
defmodule 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 do
def 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 do
domain == 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] and
domain != 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 do
message: "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 do
message: "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 do
message:
"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 and
plausible_is_initialized != true do
attempted_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) do
Sentry.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)
+ end
end
defp shorten_url(url) do
diff --git a/test/plausible/installation_support/verification/diagnostics_test.exs b/test/plausible/installation_support/verification/diagnostics_test.exs
index 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 do
describe "interpreting diagnostics" do
for 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" 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" => "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 do
end
end
- test "error when it 'succeeds', but only after cache bust" do
+ test "returns error when it 'succeeds', but only after cache bust" 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" => "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)
+ end
end
- test "error when proxy network error occurs" do
+ test "returns error when proxy network error occurs" do
expected_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" do
expected_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" do
expected_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 do
end
for 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})" do
expected_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 do
end
end
- 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" do
expected_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" do
expected_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)
+ end
end
end
end
diff --git a/tracker/test/support/types.ts b/tracker/test/support/types.ts
index 128c64fce8..825858afcf 100644
--- a/tracker/test/support/types.ts
+++ b/tracker/test/support/types.ts
@@ -52,7 +52,6 @@ export type VerifyV2Result = {
plausibleVersion: number
plausibleVariant?: string
disallowedByCsp: boolean
- cookieBannerLikely: boolean
cookiesConsentResult: ConsentResult
testEvent: {
/**