Skip to content

Analytics & SEO setup

Configure Google Analytics 4, Search Console, and conversion tracking for the docs site.

Google Analytics 4 property

Tracking is injected on every page at build time via hooks.py.

Register Key Events (do this once in GA4 Admin)

Custom events fired by the docs site are not counted as conversions until you mark them as key events:

  1. Open Google Analytics → property SquarebyWPPayments
  2. Admin → Data display → Events
  3. Wait 24–48 hours after launch for events to appear, or test by clicking buttons on the live site
  4. Toggle Mark as key event for:
Event name Triggered when
plugin_download_click User clicks Download on WordPress.org (sticky bar, footer, inline)
support_whatsapp_click User opens WhatsApp from Support form
feature_request_whatsapp_click User opens WhatsApp from Feature requests

Test Realtime

  1. Open Reports → Realtime
  2. Visit the docs site in an incognito window (disable ad blockers)
  3. Click a download button — watch for plugin_download_click under Event count by Event name

!!! tip "No Realtime data?" Ad blockers (uBlock, Brave) block GA4. Test in Chrome incognito without extensions.

Google Search Console

  • Property: https://payments-connect-square.pages.dev/ (URL prefix)
  • Verification: HTML file google9fcf0f0d145ece39.html (keep on site — do not delete)
  • Sitemap: sitemap.xml (submit under Indexing → Sitemaps)

GSC PAP in Cursor (optional)

Connect GSC PAP to ask search analytics questions in Cursor:

  1. Sign in at gscpap.com → copy bearer token
  2. Cursor → Settings → MCP → update gsc-pap Authorization header
  3. Ask: "What are my top queries for payments-connect-square.pages.dev?"

UTM parameters

Source utm_source utm_medium
Docs download buttons docs_site download_button
WordPress.org readme wordpress_org readme
Plugin admin wordpress_org wp_admin
Blog posts docs_site blog

In GA4: Reports → Acquisition → Traffic acquisition → filter by session source.

Cloudflare Pages environment variables

Set these in Cloudflare Dashboard → Workers & Pages → payments-connect-square → Settings → Environment variables so Git auto-deploys never drop tracking:

Variable Value
GA4_MEASUREMENT_ID G-CPT1BL1T96
GSC_VERIFICATION l4g7JMtZSX-ltYaUTRWNMLtIFEt3lwYqYTCOEEQA2n8,3po3l-SQTgul8CfecRuRsVxFLZEadqs_10yXAOnMGVg
PYTHON_VERSION 3.11

Local deploy via deploy.cmd sets these automatically.

Custom domain (optional)

For stronger SEO and brand trust:

  1. Add docs.yourdomain.com in Cloudflare Pages → Custom domains
  2. Update site_url in mkdocs.yml
  3. Add the new property in Google Search Console
  4. Define in WordPress wp-config.php: define( 'SHC4WC_DOCS_BASE_URL', 'https://docs.yourdomain.com' );