From 5834a3f99880d1e6ba6b1ae62e53ec0619134a73 Mon Sep 17 00:00:00 2001
From: Paul Bertrand <paulbertrand.nl@gmail.com>
Date: Thu, 18 Jun 2026 14:14:05 +0200
Subject: [PATCH 1/2] Improve General tab guidance and move custom domain to
 Advanced.

This reduces setup confusion by keeping custom domain under Advanced, adds clearer onboarding copy and dashboard links in General, hides Save Changes on that informational tab, and updates browser tests for the revised tab behavior.
---
 simple-analytics.php                 |  9 ++--
 src/UI/PageLayoutComponent.php       | 71 ++++++++++++++++++++++++----
 tests/Browser/pluginSettings.spec.ts | 26 ++++++++--
 3 files changed, 89 insertions(+), 17 deletions(-)

diff --git a/simple-analytics.php b/simple-analytics.php
index 2e2660b..5a22b62 100644
--- a/simple-analytics.php
+++ b/simple-analytics.php
@@ -77,10 +77,6 @@
 $adminPage = SimpleAnalytics\Settings\AdminPage::title('Simple Analytics')
     ->slug('simpleanalytics')
     ->tab('General', function (Tab $tab) {
-        $tab->input(SettingName::CUSTOM_DOMAIN, 'Custom Domain')
-            ->placeholder('Enter your custom domain or leave it empty.')
-            ->description('E.g. api.example.com. Leave empty to use the default domain (most users).')
-            ->docs('https://docs.simpleanalytics.com/bypass-ad-blockers');
     })
     ->tab('Ignore Rules', function (Tab $tab) {
         $tab->icon(get_icon('eye-slash'));
@@ -105,6 +101,11 @@
     ->tab('Advanced', function (Tab $tab) {
         $tab->icon(get_icon('cog'));
 
+        $tab->input(SettingName::CUSTOM_DOMAIN, 'Custom Domain')
+            ->placeholder('Enter your custom domain or leave it empty.')
+            ->description('E.g. api.example.com. Leave empty to use the default domain (most users).')
+            ->docs('https://docs.simpleanalytics.com/bypass-ad-blockers');
+
         $tab->checkbox(SettingName::COLLECT_DNT, 'Collect Do Not Track')
             ->description('If you want to collect visitors with Do Not Track enabled, turn this on.')
             ->docs('https://docs.simpleanalytics.com/dnt');
diff --git a/src/UI/PageLayoutComponent.php b/src/UI/PageLayoutComponent.php
index 0a8d81c..7fe3aa5 100644
--- a/src/UI/PageLayoutComponent.php
+++ b/src/UI/PageLayoutComponent.php
@@ -8,6 +8,9 @@
 
 class PageLayoutComponent
 {
+    private const DASHBOARD_URL = 'https://dashboard.simpleanalytics.com/?utm_source=wordpress&utm_medium=plugin&utm_content=go_to_dashboard_button';
+    private const SIGNUP_URL = 'https://www.simpleanalytics.com/signup?utm_source=wordpress&utm_medium=plugin&utm_content=signup_link';
+
     /**
      * @readonly
      * @var \SimpleAnalytics\Settings\AdminPage
@@ -44,7 +47,7 @@ public function __invoke(): void
                         <div class="flex items-center">
                             <!-- Logo -->
                             <a
-                                href="https://dashboard.simpleanalytics.com/websites"
+                                href="<?php echo esc_url(self::DASHBOARD_URL); ?>"
                                 target="_blank"
                                 class="text-base font-semibold leading-6 text-gray-900"
                             >
@@ -56,7 +59,7 @@ class="mr-2 inline-block h-10 w-auto text-primary"
                             </a>
                             <!-- "Open Dashboard" link -->
                             <a
-                                href="https://dashboard.simpleanalytics.com/websites"
+                                href="<?php echo esc_url(self::DASHBOARD_URL); ?>"
                                 target="_blank"
                                 class="inline-flex items-center rounded bg-white px-2 py-1 text-xs font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-50"
                             >
@@ -75,17 +78,22 @@ class="inline-flex items-center rounded bg-white px-2 py-1 text-xs font-semibold
                 <!-- Fields / Layout -->
                 <div class="mx-auto max-w-3xl bg-white px-4 py-6 sm:px-4 lg:px-0">
                     <div class="border-b border-gray-900/10 pb-7">
+                        <?php if ($currentTab->getSlug() === 'general'): ?>
+                            <?php $this->renderGeneralTabIntro(); ?>
+                        <?php endif; ?>
                         <?php $currentTab->render(); ?>
                     </div>
 
-                    <div class="mt-6 flex items-center justify-start gap-x-6">
-                        <button
-                            type="submit"
-                            class="rounded-md px-3 py-2 text-sm font-semibold text-white shadow-sm bg-primary hover:bg-red-500 focus-visible:outline-primary focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2"
-                        >
-                            Save Changes
-                        </button>
-                    </div>
+                    <?php if ($currentTab->getSlug() !== 'general'): ?>
+                        <div class="mt-6 flex items-center justify-start gap-x-6">
+                            <button
+                                type="submit"
+                                class="rounded-md px-3 py-2 text-sm font-semibold text-white shadow-sm bg-primary hover:bg-red-500 focus-visible:outline-primary focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2"
+                            >
+                                Save Changes
+                            </button>
+                        </div>
+                    <?php endif; ?>
                 </div>
             </form>
             <script>
@@ -140,4 +148,47 @@ protected function findTabBySlug(array $tabs, string $slug): ?Tab
 
         return null;
     }
+
+    protected function renderGeneralTabIntro(): void
+    {
+        ?>
+        <div class="mb-7" style="max-width: 64ch;">
+            <p class="text-sm text-gray-700">
+                Thanks for choosing Simple Analytics.
+            </p>
+            <p class="mt-4 text-sm text-gray-700">
+                This plugin adds Simple Analytics to your WordPress site and collects pageviews in a privacy-first way.
+                Your stats appear in
+                <a class="text-primary hover:underline" target="_blank" href="<?php echo esc_url(self::DASHBOARD_URL); ?>">
+                    your dashboard
+                </a>
+                within minutes.
+            </p>
+            <p class="mt-4 text-sm text-gray-700">
+                To exclude your own visits, open the "Ignore Rules" tab and enable the option for logged-in admins.
+                You can also add your own IP there.
+            </p>
+            <p class="mt-4 text-sm text-gray-700">
+                Want automated events, like downloads, outbound link clicks, and email clicks, collected for you,
+                check "Collect automated events" in the "Events" tab.
+            </p>
+            <p class="mt-4 text-sm text-gray-700">
+                No account yet? Sign up at
+                <a class="text-primary hover:underline" target="_blank" href="<?php echo esc_url(self::SIGNUP_URL); ?>">
+                    simpleanalytics.com
+                </a>.
+                The trial includes almost all features, then you can choose a free or paid plan.
+            </p>
+            <p class="mt-6">
+                <a
+                    href="<?php echo esc_url(self::DASHBOARD_URL); ?>"
+                    target="_blank"
+                    class="inline-flex items-center rounded bg-primary px-3 py-2 text-sm font-semibold text-white shadow-sm hover:bg-red-500"
+                >
+                    Visit your analytics dashboard
+                </a>
+            </p>
+        </div>
+        <?php
+    }
 }
diff --git a/tests/Browser/pluginSettings.spec.ts b/tests/Browser/pluginSettings.spec.ts
index 0d296d3..2e6a5d9 100644
--- a/tests/Browser/pluginSettings.spec.ts
+++ b/tests/Browser/pluginSettings.spec.ts
@@ -3,6 +3,10 @@ import { test, expect, type Page, type Browser } from '@playwright/test';
 const DEFAULT_SCRIPT_SELECTOR = 'script[src="https://scripts.simpleanalyticscdn.com/latest.js"]';
 const INACTIVE_ADMIN_SCRIPT_SELECTOR = 'script[src*="resources/js/inactive.js"]';
 const INACTIVE_ADMIN_COMMENT = '<!-- Simple Analytics: Not logging requests from admins -->';
+const DASHBOARD_URL =
+  'https://dashboard.simpleanalytics.com/?utm_source=wordpress&utm_medium=plugin&utm_content=go_to_dashboard_button';
+const SIGNUP_URL =
+  'https://www.simpleanalytics.com/signup?utm_source=wordpress&utm_medium=plugin&utm_content=signup_link';
 
 async function loginAs(page: Page, username: string, password: string) {
   await page.goto('/wp-login.php');
@@ -36,7 +40,7 @@ async function visitAsGuest(browser: Browser, path = '/'): Promise<Page> {
 
 test('adds a script by default', async ({ page, browser }) => {
   await asAdmin(page);
-  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=general');
+  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=advanced');
   await page.fill('[name="simpleanalytics_custom_domain"]', '');
   await saveSettings(page);
 
@@ -45,6 +49,22 @@ test('adds a script by default', async ({ page, browser }) => {
   await guest.context().close();
 });
 
+test('shows guidance on general tab and keeps custom domain in advanced tab', async ({ page }) => {
+  await asAdmin(page);
+  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=general');
+
+  await expect(page.getByText('Thanks for choosing Simple Analytics.')).toBeVisible();
+  await expect(page.getByRole('link', { name: 'your dashboard' })).toHaveAttribute('href', DASHBOARD_URL);
+  await expect(page.getByRole('link', { name: 'simpleanalytics.com' })).toHaveAttribute('href', SIGNUP_URL);
+  await expect(page.getByRole('link', { name: 'Visit your analytics dashboard' })).toHaveAttribute('href', DASHBOARD_URL);
+  await expect(page.getByRole('link', { name: 'Open Dashboard' })).toHaveAttribute('href', DASHBOARD_URL);
+  await expect(page.getByRole('button', { name: 'Save Changes' })).toHaveCount(0);
+  await expect(page.locator('[name="simpleanalytics_custom_domain"]')).toHaveCount(0);
+
+  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=advanced');
+  await expect(page.locator('[name="simpleanalytics_custom_domain"]')).toBeVisible();
+});
+
 test('adds inactive script for authenticated users by default', async ({ page }) => {
   await asAdmin(page);
   await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=ignore-rules');
@@ -244,7 +264,7 @@ test('adds automated events script with override global', async ({ page, browser
 
 test('adds a script with a custom domain name', async ({ page, browser }) => {
   await asAdmin(page);
-  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=general');
+  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=advanced');
   await page.fill('[name="simpleanalytics_custom_domain"]', 'mydomain.com');
   await saveSettings(page);
   await expect(page.locator('[name="simpleanalytics_custom_domain"]')).toHaveValue('mydomain.com');
@@ -253,7 +273,7 @@ test('adds a script with a custom domain name', async ({ page, browser }) => {
   await expect(guest.locator('script[src="https://mydomain.com/latest.js"]')).toBeAttached();
   await guest.context().close();
 
-  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=general');
+  await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=advanced');
   await page.fill('[name="simpleanalytics_custom_domain"]', '');
   await saveSettings(page);
 });

From 10d9ecf6cb0c49ce6bd24d56a4cba41e6e3de006 Mon Sep 17 00:00:00 2001
From: Paul Bertrand <paulbertrand.nl@gmail.com>
Date: Thu, 18 Jun 2026 14:54:41 +0200
Subject: [PATCH 2/2] Apply General tab copy review

---
 src/UI/PageLayoutComponent.php       | 29 ++++++++++++++--------------
 tests/Browser/pluginSettings.spec.ts | 11 ++++++-----
 2 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/src/UI/PageLayoutComponent.php b/src/UI/PageLayoutComponent.php
index 7fe3aa5..586d108 100644
--- a/src/UI/PageLayoutComponent.php
+++ b/src/UI/PageLayoutComponent.php
@@ -154,30 +154,31 @@ protected function renderGeneralTabIntro(): void
         ?>
         <div class="mb-7" style="max-width: 64ch;">
             <p class="text-sm text-gray-700">
-                Thanks for choosing Simple Analytics.
+                Simple Analytics is now added to your WordPress site.
             </p>
             <p class="mt-4 text-sm text-gray-700">
-                This plugin adds Simple Analytics to your WordPress site and collects pageviews in a privacy-first way.
-                Your stats appear in
+                The plugin collects pageviews in a privacy-first way, without cookies or personal data.
+            </p>
+            <p class="mt-4 text-sm text-gray-700">
+                Your stats will appear in
                 <a class="text-primary hover:underline" target="_blank" href="<?php echo esc_url(self::DASHBOARD_URL); ?>">
-                    your dashboard
+                    the Simple Analytics dashboard
                 </a>
-                within minutes.
+                within a few minutes.
             </p>
             <p class="mt-4 text-sm text-gray-700">
-                To exclude your own visits, open the "Ignore Rules" tab and enable the option for logged-in admins.
-                You can also add your own IP there.
+                To avoid tracking your own visits, go to the "Ignore Rules" tab and ignore visits from logged-in admins.
+                You can also add your own IP address there.
             </p>
             <p class="mt-4 text-sm text-gray-700">
-                Want automated events, like downloads, outbound link clicks, and email clicks, collected for you,
-                check "Collect automated events" in the "Events" tab.
+                To automatically track downloads, outbound links, and email clicks, go to the "Events" tab and enable "Collect automated events".
             </p>
             <p class="mt-4 text-sm text-gray-700">
-                No account yet? Sign up at
+                No account yet? Create one at
                 <a class="text-primary hover:underline" target="_blank" href="<?php echo esc_url(self::SIGNUP_URL); ?>">
-                    simpleanalytics.com
-                </a>.
-                The trial includes almost all features, then you can choose a free or paid plan.
+                    simpleanalytics.com.
+                </a>
+                You can start with a free trial and choose a free or paid plan later.
             </p>
             <p class="mt-6">
                 <a
@@ -185,7 +186,7 @@ protected function renderGeneralTabIntro(): void
                     target="_blank"
                     class="inline-flex items-center rounded bg-primary px-3 py-2 text-sm font-semibold text-white shadow-sm hover:bg-red-500"
                 >
-                    Visit your analytics dashboard
+                    Open dashboard
                 </a>
             </p>
         </div>
diff --git a/tests/Browser/pluginSettings.spec.ts b/tests/Browser/pluginSettings.spec.ts
index a1c04fc..d466623 100644
--- a/tests/Browser/pluginSettings.spec.ts
+++ b/tests/Browser/pluginSettings.spec.ts
@@ -57,11 +57,12 @@ test('shows guidance on general tab and keeps custom domain in advanced tab', as
   await asAdmin(page);
   await page.goto('/wp-admin/options-general.php?page=simpleanalytics&tab=general');
 
-  await expect(page.getByText('Thanks for choosing Simple Analytics.')).toBeVisible();
-  await expect(page.getByRole('link', { name: 'your dashboard' })).toHaveAttribute('href', DASHBOARD_URL);
-  await expect(page.getByRole('link', { name: 'simpleanalytics.com' })).toHaveAttribute('href', SIGNUP_URL);
-  await expect(page.getByRole('link', { name: 'Visit your analytics dashboard' })).toHaveAttribute('href', DASHBOARD_URL);
-  await expect(page.getByRole('link', { name: 'Open Dashboard' })).toHaveAttribute('href', DASHBOARD_URL);
+  await expect(page.getByText('Simple Analytics is now added to your WordPress site.')).toBeVisible();
+  await expect(page.getByText('without cookies or personal data')).toBeVisible();
+  await expect(page.getByRole('link', { name: 'the Simple Analytics dashboard' })).toHaveAttribute('href', DASHBOARD_URL);
+  await expect(page.getByRole('link', { name: 'simpleanalytics.com.' })).toHaveAttribute('href', SIGNUP_URL);
+  await expect(page.getByRole('link', { name: 'Open dashboard', exact: true })).toHaveAttribute('href', DASHBOARD_URL);
+  await expect(page.getByRole('link', { name: 'Open Dashboard', exact: true })).toHaveAttribute('href', DASHBOARD_URL);
   await expect(page.getByRole('button', { name: 'Save Changes' })).toHaveCount(0);
   await expect(page.locator('[name="simpleanalytics_custom_domain"]')).toHaveCount(0);