8 · Engagement & SEO

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 8 · Engagement & SEO
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/08-engagement-and-seo/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 6
- part_number: 8 (legacy stepNumber frontmatter)
- legacy_step_number: 8
- est_time: 30–90 min
- description: Wire the growth surfaces — GA4 analytics via the universal 3-file Safe Vendor Deviation Pattern (the canonical example), plus the lighter check-first tasks for a chat widget, social login, the blog system, and the sitemap. Most CodeCanyon scripts ship zero built-in analytics, so the deviation path is the common case.
- tags: codecanyon, laravel, analytics, ga4, seo, social-login

## Execution rules (binding)
- This is Part 8 of phase 6 (30–90 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 8 · Engagement & SEO

## TL;DR

**Objective** — wire the growth surfaces, led by GA4 via the universal **3-file Safe Vendor Deviation Pattern** (one blade edit, one config key, one env var) — the canonical example whose shape recurs for Sentry JS, PostHog, Pixel, and Turnstile — then run check-first on chat, social login, blog, and sitemap.

**Steps at a glance:**
1. **Wire analytics tracking (GA4)** — Getting the Measurement ID and confirming Realtime are
   Google-Analytics-dashboard actions a person performs; the 3-file code change is agent work.
2. **Configure the chat widget** — CHECK: `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget
   field.
3. **Configure social login** — CHECK: `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Creating
   provider apps is mixed: the human owns login/consent/secret fields, while the agent can drive non-secret
   console setup and panel verification after authorization.
4. **Confirm the blog system** — CHECK: `Admin → Blog` (or `Posts` / `Content`).
5. **Verify the sitemap** — CHECK: visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

:::note[User part + done-when]
**🔀 User part** — the human owns provider login, OAuth app authorization, and any secret fields. The agent can drive non-secret provider-console navigation after the authorized session exists, make the 3-file blade/config/env edits, run `curl`, and verify Realtime when the dashboard session is available.

**Done when** GA4 is wired (built-in field or the 3-file deviation), `curl | grep -c` returns **≥1** for the real Measurement ID, Realtime shows traffic, and chat/social/blog/sitemap are each configured or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ 30–90 min** &nbsp;·&nbsp; 🔀 mixed (👤 GA4 property + OAuth, 🤖 3-file edit + verify).
:::

## Background

The growth surfaces — analytics, chat, social login, blog, sitemap. Most are **SHOULD** check-first tasks or tracked post-launch non-blockers, but **analytics is the canonical example of the universal Safe Vendor Deviation Pattern** and earns the most space because the same 3-file shape recurs for Sentry JS, PostHog, Facebook Pixel, Turnstile, and more.

:::caution[SSH artisan + `shared/.env` use `$PHP_BIN` and "add-not-set"]
Config-cache rebuilds run over SSH — use the `$PHP_BIN` from [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/). Always append to `shared/.env` idempotently (`grep -q … || echo …`); never overwrite a line silently.
:::

## Steps

### 1. Wire analytics tracking (GA4)

:::note[Prerequisite — finish the demo-content audit first]
Wire GA4 **after** the demo-content replacement on [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), or your event stream fills with test clicks on vendor placeholder content.
:::

Getting the Measurement ID and confirming Realtime happen in the Google Analytics dashboard. Use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) when an agent drives the non-secret console steps after the human login; the 3-file code change is agent work.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** handles Google login and any account authorization. 🤖 **Agent** can drive non-secret GA4 property/stream navigation and Realtime verification after the session exists.
:::

**Most CodeCanyon Laravel scripts ship ZERO built-in analytics** — no admin field, no `tracking_code` column. Pick your path from the capabilities doc.

**Path 1 — vendor has a built-in analytics field (rare):** `Admin → Config → SEO` (or `Settings → Tracking`) → paste the Measurement ID → save → view-source the landing page to confirm the GA4 script is present → check GA4 Realtime.

**Path 2 — no built-in field (common): the 3-file Safe Vendor Deviation.** The pattern keeps your change small, env-gated, and auditable across vendor updates — one blade edit, one convention-file key, one env var:

```mermaid
flowchart LR
    BLADE["landing.blade.php<br/>@if(config('services.google.ga4_measurement_id'))<br/>…gtag snippet…"]
    CONFIG["config/services.php<br/>'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]"]
    ENV["shared/.env<br/>GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\""]
    BLADE -->|reads via config()| CONFIG
    CONFIG -->|reads via env()| ENV
```

<Steps>

1. **Edit the blade** — in `resources/views/layouts/landing.blade.php` (the **public landing** layout — **not** `guest.blade.php`, which has Jetstream tenant-context issues, and **not** authenticated app layouts), insert the standard `gtag.js` snippet **right before `</head>`**, gated on config **and** cookie consent (Termly/GetTerms autoblock or your Phase 6/7 banner). Example with Termly autoblock — the script stays inert until analytics consent:

   ```blade
   @if (config('services.google.ga4_measurement_id'))
   {{-- <PROJECT> Phase 6 — GA4 (consent-gated; Termly data-auto-block="on" must load first in <head>) --}}
   <script type="text/plain" data-cookie-category="analytics"
     src="https://www.googletagmanager.com/gtag/js?id={{ config('services.google.ga4_measurement_id') }}"></script>
   <script type="text/plain" data-cookie-category="analytics">
     window.dataLayer = window.dataLayer || [];
     function gtag(){dataLayer.push(arguments);}
     gtag('js', new Date());
     gtag('config', '{{ config('services.google.ga4_measurement_id') }}');
   </script>
   @endif
   ```

   - ✅ The gtag snippet is config-gated, **consent-gated** (not unconditional), with a project-name comment marker.

2. **Edit the config** — add `'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]` to `config/services.php`. Vendors almost never touch this convention file, which is what makes it a safe home. **Read via `config(...)`, never `env(...)` from blade/app code.**

   - ✅ `config/services.php` exposes `services.google.ga4_measurement_id`.

3. **Append the env var** to **`shared/.env` on the server** (not the ephemeral release `.env`), then rebuild the config cache.

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php" | head -1)
   DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md, e.g. staging-primary/qa/uat/client-demo
   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
   SSH_ALIAS="<non-prod-alias-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "grep -q '^GA4_MEASUREMENT_ID=' $DEPLOY_PATH/shared/.env \
     || echo 'GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\"' >> $DEPLOY_PATH/shared/.env"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan config:clear && $PHP_BIN artisan config:cache"
   # Expected: the ID is appended once on shared/.env, then the config cache rebuilds
   ```

   - ✅ `GA4_MEASUREMENT_ID` is set in `shared/.env` and the config cache is rebuilt.

4. **Verify the tag fires.**

   ```bash
   curl -sS https://nonprod.example.com/ | grep -c "$GA4_MEASUREMENT_ID"   # expect ≥1 (consent-gated tag may show once in HTML)
   # Expected: ≥1
   ```

   - ✅ `curl | grep -c` returns **≥1** for the real Measurement ID; GA4 → Reports → Realtime shows your visit within ~30s. **Record the deviation** in `Zaj-CUSTOMIZATIONS.md` (file / what added / task / comment marker) — that registry is the shopping list for every vendor-update merge.

</Steps>

:::danger[Consent gate is a launch blocker]
GA4 must **not** fire before analytics consent on production **or the selected non-production environment** (EU testers need a banner on QA/UAT/client-demo hosts too). Use Termly/GetTerms autoblock (`type="text/plain" data-cookie-category="analytics"`) or equivalent from [page 6](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/06-legal-and-consent/) / [Phase 7 legal](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/06-legal-gdpr/). Local/dev may omit the tag entirely.
:::

### 2. Configure the chat widget

**CHECK:** `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget field.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates/logs into the provider account and owns any widget secret/API key. 🤖 **Agent** can paste non-secret embed snippets or drive panel save/verify after the secret is available.
:::

<Steps>

1. **Configure now or capture the widget task.**
   - **If present** — paste the provider's widget code or API key.
   - **If absent** — capture the layout-footer widget task in `Zaj-BACKLOG.md` as a post-launch non-blocker.

   - ✅ The widget is configured, or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker with owner, trigger, and acceptance criterion.

</Steps>

### 3. Configure social login

**CHECK:** `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Provider login, consent screens, and secret fields are human-owned; the non-secret console setup, callback URL verification, panel save, and browser checks are agent-drivable after the authorized session exists.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns provider login, consent screens, secret/client-secret creation, and password entry. 🤖 With an authorized browser session, the agent can drive non-secret OAuth-app setup, copy public client IDs into the panel when safe, and verify callback URLs/scopes. See [vendor console automation](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) for the safe console pattern.
:::

<Steps>

1. **Configure now or capture the social-login task.**
   - **If present** — enter the Google / Facebook / GitHub OAuth **client ID + secret** and enable the providers you want.
   - **If absent** — likely needs Laravel Socialite + code. **Check for an existing `SocialLoginController` before building from scratch** — many vendors ship one that's just unwired.

   - ✅ Social login is configured (OAuth app created first), or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker after checking for an existing `SocialLoginController`.

</Steps>

### 4. Confirm the blog system

**CHECK:** `Admin → Blog` (or `Posts` / `Content`).

<Steps>

1. **Confirm status or capture the blog task.**
   - **If present** — the system is ready; just start writing posts. No setup needed.
   - **If absent** — adding a blog is a code task; capture it in `Zaj-BACKLOG.md`.

   - ✅ Blog status is confirmed (ready now or captured in `Zaj-BACKLOG.md`). Blog content is a **growth activity, not a launch blocker.**

</Steps>

### 5. Verify the sitemap

**CHECK:** visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

<Steps>

1. **Verify now or capture the sitemap task.**
   - **If auto-generated** — confirm it lists your key pages, then submit it to Google Search Console.
   - **If absent** — generating a sitemap is a small code/SEO task; capture it in `Zaj-BACKLOG.md`.

   - ✅ `/sitemap.xml` is verified and submitted to Search Console, or captured in `Zaj-BACKLOG.md`. Important for SEO but **not a launch blocker.**

</Steps>

:::note[Who does this]
🔀 **User + Agent** — 👤 the user authorizes the Google account/property. 🤖 With that session, the agent can submit the sitemap, capture evidence, and verify the submitted URL status.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🔀 GA4 wired** — built-in field **or** the 3-file deviation; `curl | grep -c` returns **≥1** for the real Measurement ID; Realtime shows traffic; deviation recorded in `Zaj-CUSTOMIZATIONS.md`.
- [ ] **🔀 Consent dependency queued** — GA4 consent-gating (page 6) is in `Zaj-BACKLOG.md` for production launch.
- [ ] **🔀 Chat configured** — chat widget configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Social login handled** — configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion; existing `SocialLoginController` checked before any new build.
- [ ] **🤖 Blog status confirmed** — ready now or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Sitemap handled** — `/sitemap.xml` verified and submitted to Search Console **or** captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.

:::next[Next step]
SuperAdmin setup is complete. Continue to **[Phase 7 · Security & monitoring](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/)** — harden the app, then wire backups and observability before real users arrive.
:::

# 8 · Engagement & SEO

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/08-engagement-and-seo/

## TL;DR

**Objective** — wire the growth surfaces, led by GA4 via the universal **3-file Safe Vendor Deviation Pattern** (one blade edit, one config key, one env var) — the canonical example whose shape recurs for Sentry JS, PostHog, Pixel, and Turnstile — then run check-first on chat, social login, blog, and sitemap.

**Steps at a glance:**
1. **Wire analytics tracking (GA4)** — Getting the Measurement ID and confirming Realtime are
   Google-Analytics-dashboard actions a person performs; the 3-file code change is agent work.
2. **Configure the chat widget** — CHECK: `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget
   field.
3. **Configure social login** — CHECK: `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Creating
   provider apps is mixed: the human owns login/consent/secret fields, while the agent can drive non-secret
   console setup and panel verification after authorization.
4. **Confirm the blog system** — CHECK: `Admin → Blog` (or `Posts` / `Content`).
5. **Verify the sitemap** — CHECK: visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

:::note[User part + done-when]
**🔀 User part** — the human owns provider login, OAuth app authorization, and any secret fields. The agent can drive non-secret provider-console navigation after the authorized session exists, make the 3-file blade/config/env edits, run `curl`, and verify Realtime when the dashboard session is available.

**Done when** GA4 is wired (built-in field or the 3-file deviation), `curl | grep -c` returns **≥1** for the real Measurement ID, Realtime shows traffic, and chat/social/blog/sitemap are each configured or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ 30–90 min** &nbsp;·&nbsp; 🔀 mixed (👤 GA4 property + OAuth, 🤖 3-file edit + verify).
:::

## Background

The growth surfaces — analytics, chat, social login, blog, sitemap. Most are **SHOULD** check-first tasks or tracked post-launch non-blockers, but **analytics is the canonical example of the universal Safe Vendor Deviation Pattern** and earns the most space because the same 3-file shape recurs for Sentry JS, PostHog, Facebook Pixel, Turnstile, and more.

:::caution[SSH artisan + `shared/.env` use `$PHP_BIN` and "add-not-set"]
Config-cache rebuilds run over SSH — use the `$PHP_BIN` from [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/). Always append to `shared/.env` idempotently (`grep -q … || echo …`); never overwrite a line silently.
:::

## Steps

### 1. Wire analytics tracking (GA4)

:::note[Prerequisite — finish the demo-content audit first]
Wire GA4 **after** the demo-content replacement on [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), or your event stream fills with test clicks on vendor placeholder content.
:::

Getting the Measurement ID and confirming Realtime happen in the Google Analytics dashboard. Use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) when an agent drives the non-secret console steps after the human login; the 3-file code change is agent work.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** handles Google login and any account authorization. 🤖 **Agent** can drive non-secret GA4 property/stream navigation and Realtime verification after the session exists.
:::

**Most CodeCanyon Laravel scripts ship ZERO built-in analytics** — no admin field, no `tracking_code` column. Pick your path from the capabilities doc.

**Path 1 — vendor has a built-in analytics field (rare):** `Admin → Config → SEO` (or `Settings → Tracking`) → paste the Measurement ID → save → view-source the landing page to confirm the GA4 script is present → check GA4 Realtime.

**Path 2 — no built-in field (common): the 3-file Safe Vendor Deviation.** The pattern keeps your change small, env-gated, and auditable across vendor updates — one blade edit, one convention-file key, one env var:

```mermaid
flowchart LR
    BLADE["landing.blade.php<br/>@if(config('services.google.ga4_measurement_id'))<br/>…gtag snippet…"]
    CONFIG["config/services.php<br/>'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]"]
    ENV["shared/.env<br/>GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\""]
    BLADE -->|reads via config()| CONFIG
    CONFIG -->|reads via env()| ENV
```

<Steps>

1. **Edit the blade** — in `resources/views/layouts/landing.blade.php` (the **public landing** layout — **not** `guest.blade.php`, which has Jetstream tenant-context issues, and **not** authenticated app layouts), insert the standard `gtag.js` snippet **right before `</head>`**, gated on config **and** cookie consent (Termly/GetTerms autoblock or your Phase 6/7 banner). Example with Termly autoblock — the script stays inert until analytics consent:

   ```blade
   @if (config('services.google.ga4_measurement_id'))
   {{-- <PROJECT> Phase 6 — GA4 (consent-gated; Termly data-auto-block="on" must load first in <head>) --}}
   <script type="text/plain" data-cookie-category="analytics"
     src="https://www.googletagmanager.com/gtag/js?id={{ config('services.google.ga4_measurement_id') }}"></script>
   <script type="text/plain" data-cookie-category="analytics">
     window.dataLayer = window.dataLayer || [];
     function gtag(){dataLayer.push(arguments);}
     gtag('js', new Date());
     gtag('config', '{{ config('services.google.ga4_measurement_id') }}');
   </script>
   @endif
   ```

   - ✅ The gtag snippet is config-gated, **consent-gated** (not unconditional), with a project-name comment marker.

2. **Edit the config** — add `'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]` to `config/services.php`. Vendors almost never touch this convention file, which is what makes it a safe home. **Read via `config(...)`, never `env(...)` from blade/app code.**

   - ✅ `config/services.php` exposes `services.google.ga4_measurement_id`.

3. **Append the env var** to **`shared/.env` on the server** (not the ephemeral release `.env`), then rebuild the config cache.

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php" | head -1)
   DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md, e.g. staging-primary/qa/uat/client-demo
   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
   SSH_ALIAS="<non-prod-alias-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "grep -q '^GA4_MEASUREMENT_ID=' $DEPLOY_PATH/shared/.env \
     || echo 'GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\"' >> $DEPLOY_PATH/shared/.env"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan config:clear && $PHP_BIN artisan config:cache"
   # Expected: the ID is appended once on shared/.env, then the config cache rebuilds
   ```

   - ✅ `GA4_MEASUREMENT_ID` is set in `shared/.env` and the config cache is rebuilt.

4. **Verify the tag fires.**

   ```bash
   curl -sS https://nonprod.example.com/ | grep -c "$GA4_MEASUREMENT_ID"   # expect ≥1 (consent-gated tag may show once in HTML)
   # Expected: ≥1
   ```

   - ✅ `curl | grep -c` returns **≥1** for the real Measurement ID; GA4 → Reports → Realtime shows your visit within ~30s. **Record the deviation** in `Zaj-CUSTOMIZATIONS.md` (file / what added / task / comment marker) — that registry is the shopping list for every vendor-update merge.

</Steps>

:::danger[Consent gate is a launch blocker]
GA4 must **not** fire before analytics consent on production **or the selected non-production environment** (EU testers need a banner on QA/UAT/client-demo hosts too). Use Termly/GetTerms autoblock (`type="text/plain" data-cookie-category="analytics"`) or equivalent from [page 6](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/06-legal-and-consent/) / [Phase 7 legal](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/06-legal-gdpr/). Local/dev may omit the tag entirely.
:::

### 2. Configure the chat widget

**CHECK:** `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget field.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates/logs into the provider account and owns any widget secret/API key. 🤖 **Agent** can paste non-secret embed snippets or drive panel save/verify after the secret is available.
:::

<Steps>

1. **Configure now or capture the widget task.**
   - **If present** — paste the provider's widget code or API key.
   - **If absent** — capture the layout-footer widget task in `Zaj-BACKLOG.md` as a post-launch non-blocker.

   - ✅ The widget is configured, or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker with owner, trigger, and acceptance criterion.

</Steps>

### 3. Configure social login

**CHECK:** `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Provider login, consent screens, and secret fields are human-owned; the non-secret console setup, callback URL verification, panel save, and browser checks are agent-drivable after the authorized session exists.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns provider login, consent screens, secret/client-secret creation, and password entry. 🤖 With an authorized browser session, the agent can drive non-secret OAuth-app setup, copy public client IDs into the panel when safe, and verify callback URLs/scopes. See [vendor console automation](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) for the safe console pattern.
:::

<Steps>

1. **Configure now or capture the social-login task.**
   - **If present** — enter the Google / Facebook / GitHub OAuth **client ID + secret** and enable the providers you want.
   - **If absent** — likely needs Laravel Socialite + code. **Check for an existing `SocialLoginController` before building from scratch** — many vendors ship one that's just unwired.

   - ✅ Social login is configured (OAuth app created first), or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker after checking for an existing `SocialLoginController`.

</Steps>

### 4. Confirm the blog system

**CHECK:** `Admin → Blog` (or `Posts` / `Content`).

<Steps>

1. **Confirm status or capture the blog task.**
   - **If present** — the system is ready; just start writing posts. No setup needed.
   - **If absent** — adding a blog is a code task; capture it in `Zaj-BACKLOG.md`.

   - ✅ Blog status is confirmed (ready now or captured in `Zaj-BACKLOG.md`). Blog content is a **growth activity, not a launch blocker.**

</Steps>

### 5. Verify the sitemap

**CHECK:** visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

<Steps>

1. **Verify now or capture the sitemap task.**
   - **If auto-generated** — confirm it lists your key pages, then submit it to Google Search Console.
   - **If absent** — generating a sitemap is a small code/SEO task; capture it in `Zaj-BACKLOG.md`.

   - ✅ `/sitemap.xml` is verified and submitted to Search Console, or captured in `Zaj-BACKLOG.md`. Important for SEO but **not a launch blocker.**

</Steps>

:::note[Who does this]
🔀 **User + Agent** — 👤 the user authorizes the Google account/property. 🤖 With that session, the agent can submit the sitemap, capture evidence, and verify the submitted URL status.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🔀 GA4 wired** — built-in field **or** the 3-file deviation; `curl | grep -c` returns **≥1** for the real Measurement ID; Realtime shows traffic; deviation recorded in `Zaj-CUSTOMIZATIONS.md`.
- [ ] **🔀 Consent dependency queued** — GA4 consent-gating (page 6) is in `Zaj-BACKLOG.md` for production launch.
- [ ] **🔀 Chat configured** — chat widget configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Social login handled** — configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion; existing `SocialLoginController` checked before any new build.
- [ ] **🤖 Blog status confirmed** — ready now or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Sitemap handled** — `/sitemap.xml` verified and submitted to Search Console **or** captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.

:::next[Next step]
SuperAdmin setup is complete. Continue to **[Phase 7 · Security & monitoring](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/)** — harden the app, then wire backups and observability before real users arrive.
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

TL;DR

Objective — wire the growth surfaces, led by GA4 via the universal 3-file Safe Vendor Deviation Pattern (one blade edit, one config key, one env var) — the canonical example whose shape recurs for Sentry JS, PostHog, Pixel, and Turnstile — then run check-first on chat, social login, blog, and sitemap.

Steps at a glance:

Wire analytics tracking (GA4) — Getting the Measurement ID and confirming Realtime are Google-Analytics-dashboard actions a person performs; the 3-file code change is agent work.
Configure the chat widget — CHECK: Admin → Settings for a Crisp / Tawk.to / Intercom / generic widget field.
Configure social login — CHECK: Admin → Config → Login (or Social Auth / OAuth Settings). Creating provider apps is mixed: the human owns login/consent/secret fields, while the agent can drive non-secret console setup and panel verification after authorization.
Confirm the blog system — CHECK: Admin → Blog (or Posts / Content).
Verify the sitemap — CHECK: visit /sitemap.xml on the domain, and look under Admin → SEO.

Background

The growth surfaces — analytics, chat, social login, blog, sitemap. Most are SHOULD check-first tasks or tracked post-launch non-blockers, but analytics is the canonical example of the universal Safe Vendor Deviation Pattern and earns the most space because the same 3-file shape recurs for Sentry JS, PostHog, Facebook Pixel, Turnstile, and more.

Steps

1. Wire analytics tracking (GA4)

Getting the Measurement ID and confirming Realtime happen in the Google Analytics dashboard. Use the vendor console automation guide when an agent drives the non-secret console steps after the human login; the 3-file code change is agent work.

Most CodeCanyon Laravel scripts ship ZERO built-in analytics — no admin field, no tracking_code column. Pick your path from the capabilities doc.

Path 1 — vendor has a built-in analytics field (rare): Admin → Config → SEO (or Settings → Tracking) → paste the Measurement ID → save → view-source the landing page to confirm the GA4 script is present → check GA4 Realtime.

Path 2 — no built-in field (common): the 3-file Safe Vendor Deviation. The pattern keeps your change small, env-gated, and auditable across vendor updates — one blade edit, one convention-file key, one env var:

flowchart LR
    BLADE["landing.blade.php<br/>@if(config('services.google.ga4_measurement_id'))<br/>…gtag snippet…"]
    CONFIG["config/services.php<br/>'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]"]
    ENV["shared/.env<br/>GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\""]
    BLADE -->|reads via config()| CONFIG
    CONFIG -->|reads via env()| ENV

Edit the blade — in resources/views/layouts/landing.blade.php (the public landing layout — not guest.blade.php, which has Jetstream tenant-context issues, and not authenticated app layouts), insert the standard gtag.js snippet right before </head>, gated on config and cookie consent (Termly/GetTerms autoblock or your Phase 6/7 banner). Example with Termly autoblock — the script stays inert until analytics consent:

@if (config('services.google.ga4_measurement_id'))
{{-- <PROJECT> Phase 6 — GA4 (consent-gated; Termly data-auto-block="on" must load first in <head>) --}}
<script type="text/plain" data-cookie-category="analytics"
  src="https://www.googletagmanager.com/gtag/js?id={{ config('services.google.ga4_measurement_id') }}"></script>
<script type="text/plain" data-cookie-category="analytics">
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', '{{ config('services.google.ga4_measurement_id') }}');
</script>
@endif

✅ The gtag snippet is config-gated, consent-gated (not unconditional), with a project-name comment marker.

Edit the config — add 'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')] to config/services.php. Vendors almost never touch this convention file, which is what makes it a safe home. Read via config(...), never env(...) from blade/app code.
- ✅ config/services.php exposes services.google.ga4_measurement_id.

Append the env var to shared/.env on the server (not the ephemeral release .env), then rebuild the config cache.

PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php" | head -1)
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md, e.g. staging-primary/qa/uat/client-demo
DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
SSH_ALIAS="<non-prod-alias-from-Zaj-PROJECT>"
ssh "$SSH_ALIAS" "grep -q '^GA4_MEASUREMENT_ID=' $DEPLOY_PATH/shared/.env \
  || echo 'GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\"' >> $DEPLOY_PATH/shared/.env"
ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan config:clear && $PHP_BIN artisan config:cache"
# Expected: the ID is appended once on shared/.env, then the config cache rebuilds

✅ GA4_MEASUREMENT_ID is set in shared/.env and the config cache is rebuilt.

Verify the tag fires.
Terminal window
```
curl -sS https://nonprod.example.com/ | grep -c "$GA4_MEASUREMENT_ID"   # expect ≥1 (consent-gated tag may show once in HTML)
# Expected: ≥1
```
- ✅ curl | grep -c returns ≥1 for the real Measurement ID; GA4 → Reports → Realtime shows your visit within ~30s. Record the deviation in Zaj-CUSTOMIZATIONS.md (file / what added / task / comment marker) — that registry is the shopping list for every vendor-update merge.

CHECK: Admin → Settings for a Crisp / Tawk.to / Intercom / generic widget field.

Configure now or capture the widget task.
- If present — paste the provider’s widget code or API key.
- If absent — capture the layout-footer widget task in Zaj-BACKLOG.md as a post-launch non-blocker.
- ✅ The widget is configured, or captured in Zaj-BACKLOG.md as a post-launch non-blocker with owner, trigger, and acceptance criterion.

CHECK: Admin → Config → Login (or Social Auth / OAuth Settings). Provider login, consent screens, and secret fields are human-owned; the non-secret console setup, callback URL verification, panel save, and browser checks are agent-drivable after the authorized session exists.

Configure now or capture the social-login task.
- If present — enter the Google / Facebook / GitHub OAuth client ID + secret and enable the providers you want.
- If absent — likely needs Laravel Socialite + code. Check for an existing SocialLoginController before building from scratch — many vendors ship one that’s just unwired.
- ✅ Social login is configured (OAuth app created first), or captured in Zaj-BACKLOG.md as a post-launch non-blocker after checking for an existing SocialLoginController.

4. Confirm the blog system

CHECK: Admin → Blog (or Posts / Content).

Confirm status or capture the blog task.
- If present — the system is ready; just start writing posts. No setup needed.
- If absent — adding a blog is a code task; capture it in Zaj-BACKLOG.md.
- ✅ Blog status is confirmed (ready now or captured in Zaj-BACKLOG.md). Blog content is a growth activity, not a launch blocker.

5. Verify the sitemap

CHECK: visit /sitemap.xml on the domain, and look under Admin → SEO.

Verify now or capture the sitemap task.
- If auto-generated — confirm it lists your key pages, then submit it to Google Search Console.
- If absent — generating a sitemap is a small code/SEO task; capture it in Zaj-BACKLOG.md.
- ✅ /sitemap.xml is verified and submitted to Search Console, or captured in Zaj-BACKLOG.md. Important for SEO but not a launch blocker.

Checklist

Do not mark this step done until every box below is checked.

🔀 GA4 wired — built-in field or the 3-file deviation; curl | grep -c returns ≥1 for the real Measurement ID; Realtime shows traffic; deviation recorded in Zaj-CUSTOMIZATIONS.md.
🔀 Consent dependency queued — GA4 consent-gating (page 6) is in Zaj-BACKLOG.md for production launch.
🔀 Chat configured — chat widget configured or captured as a post-launch non-blocker in Zaj-BACKLOG.md with owner, trigger, and acceptance criterion.
🔀 Social login handled — configured or captured as a post-launch non-blocker in Zaj-BACKLOG.md with owner, trigger, and acceptance criterion; existing SocialLoginController checked before any new build.
🤖 Blog status confirmed — ready now or captured in Zaj-BACKLOG.md with owner, trigger, and acceptance criterion.
🔀 Sitemap handled — /sitemap.xml verified and submitted to Search Console or captured in Zaj-BACKLOG.md with owner, trigger, and acceptance criterion.

SuperAdmin setup is complete. Continue to Phase 7 · Security & monitoring — harden the app, then wire backups and observability before real users arrive.

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 8 · Engagement & SEO
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/08-engagement-and-seo/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 6
- part_number: 8 (legacy stepNumber frontmatter)
- legacy_step_number: 8
- est_time: 30–90 min
- description: Wire the growth surfaces — GA4 analytics via the universal 3-file Safe Vendor Deviation Pattern (the canonical example), plus the lighter check-first tasks for a chat widget, social login, the blog system, and the sitemap. Most CodeCanyon scripts ship zero built-in analytics, so the deviation path is the common case.
- tags: codecanyon, laravel, analytics, ga4, seo, social-login

## Execution rules (binding)
- This is Part 8 of phase 6 (30–90 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 8 · Engagement & SEO

## TL;DR

**Objective** — wire the growth surfaces, led by GA4 via the universal **3-file Safe Vendor Deviation Pattern** (one blade edit, one config key, one env var) — the canonical example whose shape recurs for Sentry JS, PostHog, Pixel, and Turnstile — then run check-first on chat, social login, blog, and sitemap.

**Steps at a glance:**
1. **Wire analytics tracking (GA4)** — Getting the Measurement ID and confirming Realtime are
   Google-Analytics-dashboard actions a person performs; the 3-file code change is agent work.
2. **Configure the chat widget** — CHECK: `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget
   field.
3. **Configure social login** — CHECK: `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Creating
   provider apps is mixed: the human owns login/consent/secret fields, while the agent can drive non-secret
   console setup and panel verification after authorization.
4. **Confirm the blog system** — CHECK: `Admin → Blog` (or `Posts` / `Content`).
5. **Verify the sitemap** — CHECK: visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

:::note[User part + done-when]
**🔀 User part** — the human owns provider login, OAuth app authorization, and any secret fields. The agent can drive non-secret provider-console navigation after the authorized session exists, make the 3-file blade/config/env edits, run `curl`, and verify Realtime when the dashboard session is available.

**Done when** GA4 is wired (built-in field or the 3-file deviation), `curl | grep -c` returns **≥1** for the real Measurement ID, Realtime shows traffic, and chat/social/blog/sitemap are each configured or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ 30–90 min** &nbsp;·&nbsp; 🔀 mixed (👤 GA4 property + OAuth, 🤖 3-file edit + verify).
:::

## Background

The growth surfaces — analytics, chat, social login, blog, sitemap. Most are **SHOULD** check-first tasks or tracked post-launch non-blockers, but **analytics is the canonical example of the universal Safe Vendor Deviation Pattern** and earns the most space because the same 3-file shape recurs for Sentry JS, PostHog, Facebook Pixel, Turnstile, and more.

:::caution[SSH artisan + `shared/.env` use `$PHP_BIN` and "add-not-set"]
Config-cache rebuilds run over SSH — use the `$PHP_BIN` from [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/). Always append to `shared/.env` idempotently (`grep -q … || echo …`); never overwrite a line silently.
:::

## Steps

### 1. Wire analytics tracking (GA4)

:::note[Prerequisite — finish the demo-content audit first]
Wire GA4 **after** the demo-content replacement on [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), or your event stream fills with test clicks on vendor placeholder content.
:::

Getting the Measurement ID and confirming Realtime happen in the Google Analytics dashboard. Use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) when an agent drives the non-secret console steps after the human login; the 3-file code change is agent work.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** handles Google login and any account authorization. 🤖 **Agent** can drive non-secret GA4 property/stream navigation and Realtime verification after the session exists.
:::

**Most CodeCanyon Laravel scripts ship ZERO built-in analytics** — no admin field, no `tracking_code` column. Pick your path from the capabilities doc.

**Path 1 — vendor has a built-in analytics field (rare):** `Admin → Config → SEO` (or `Settings → Tracking`) → paste the Measurement ID → save → view-source the landing page to confirm the GA4 script is present → check GA4 Realtime.

**Path 2 — no built-in field (common): the 3-file Safe Vendor Deviation.** The pattern keeps your change small, env-gated, and auditable across vendor updates — one blade edit, one convention-file key, one env var:

```mermaid
flowchart LR
    BLADE["landing.blade.php<br/>@if(config('services.google.ga4_measurement_id'))<br/>…gtag snippet…"]
    CONFIG["config/services.php<br/>'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]"]
    ENV["shared/.env<br/>GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\""]
    BLADE -->|reads via config()| CONFIG
    CONFIG -->|reads via env()| ENV
```

<Steps>

1. **Edit the blade** — in `resources/views/layouts/landing.blade.php` (the **public landing** layout — **not** `guest.blade.php`, which has Jetstream tenant-context issues, and **not** authenticated app layouts), insert the standard `gtag.js` snippet **right before `</head>`**, gated on config **and** cookie consent (Termly/GetTerms autoblock or your Phase 6/7 banner). Example with Termly autoblock — the script stays inert until analytics consent:

   ```blade
   @if (config('services.google.ga4_measurement_id'))
   {{-- <PROJECT> Phase 6 — GA4 (consent-gated; Termly data-auto-block="on" must load first in <head>) --}}
   <script type="text/plain" data-cookie-category="analytics"
     src="https://www.googletagmanager.com/gtag/js?id={{ config('services.google.ga4_measurement_id') }}"></script>
   <script type="text/plain" data-cookie-category="analytics">
     window.dataLayer = window.dataLayer || [];
     function gtag(){dataLayer.push(arguments);}
     gtag('js', new Date());
     gtag('config', '{{ config('services.google.ga4_measurement_id') }}');
   </script>
   @endif
   ```

   - ✅ The gtag snippet is config-gated, **consent-gated** (not unconditional), with a project-name comment marker.

2. **Edit the config** — add `'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]` to `config/services.php`. Vendors almost never touch this convention file, which is what makes it a safe home. **Read via `config(...)`, never `env(...)` from blade/app code.**

   - ✅ `config/services.php` exposes `services.google.ga4_measurement_id`.

3. **Append the env var** to **`shared/.env` on the server** (not the ephemeral release `.env`), then rebuild the config cache.

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php" | head -1)
   DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md, e.g. staging-primary/qa/uat/client-demo
   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
   SSH_ALIAS="<non-prod-alias-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "grep -q '^GA4_MEASUREMENT_ID=' $DEPLOY_PATH/shared/.env \
     || echo 'GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\"' >> $DEPLOY_PATH/shared/.env"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan config:clear && $PHP_BIN artisan config:cache"
   # Expected: the ID is appended once on shared/.env, then the config cache rebuilds
   ```

   - ✅ `GA4_MEASUREMENT_ID` is set in `shared/.env` and the config cache is rebuilt.

4. **Verify the tag fires.**

   ```bash
   curl -sS https://nonprod.example.com/ | grep -c "$GA4_MEASUREMENT_ID"   # expect ≥1 (consent-gated tag may show once in HTML)
   # Expected: ≥1
   ```

   - ✅ `curl | grep -c` returns **≥1** for the real Measurement ID; GA4 → Reports → Realtime shows your visit within ~30s. **Record the deviation** in `Zaj-CUSTOMIZATIONS.md` (file / what added / task / comment marker) — that registry is the shopping list for every vendor-update merge.

</Steps>

:::danger[Consent gate is a launch blocker]
GA4 must **not** fire before analytics consent on production **or the selected non-production environment** (EU testers need a banner on QA/UAT/client-demo hosts too). Use Termly/GetTerms autoblock (`type="text/plain" data-cookie-category="analytics"`) or equivalent from [page 6](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/06-legal-and-consent/) / [Phase 7 legal](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/06-legal-gdpr/). Local/dev may omit the tag entirely.
:::

### 2. Configure the chat widget

**CHECK:** `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget field.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates/logs into the provider account and owns any widget secret/API key. 🤖 **Agent** can paste non-secret embed snippets or drive panel save/verify after the secret is available.
:::

<Steps>

1. **Configure now or capture the widget task.**
   - **If present** — paste the provider's widget code or API key.
   - **If absent** — capture the layout-footer widget task in `Zaj-BACKLOG.md` as a post-launch non-blocker.

   - ✅ The widget is configured, or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker with owner, trigger, and acceptance criterion.

</Steps>

### 3. Configure social login

**CHECK:** `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Provider login, consent screens, and secret fields are human-owned; the non-secret console setup, callback URL verification, panel save, and browser checks are agent-drivable after the authorized session exists.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns provider login, consent screens, secret/client-secret creation, and password entry. 🤖 With an authorized browser session, the agent can drive non-secret OAuth-app setup, copy public client IDs into the panel when safe, and verify callback URLs/scopes. See [vendor console automation](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) for the safe console pattern.
:::

<Steps>

1. **Configure now or capture the social-login task.**
   - **If present** — enter the Google / Facebook / GitHub OAuth **client ID + secret** and enable the providers you want.
   - **If absent** — likely needs Laravel Socialite + code. **Check for an existing `SocialLoginController` before building from scratch** — many vendors ship one that's just unwired.

   - ✅ Social login is configured (OAuth app created first), or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker after checking for an existing `SocialLoginController`.

</Steps>

### 4. Confirm the blog system

**CHECK:** `Admin → Blog` (or `Posts` / `Content`).

<Steps>

1. **Confirm status or capture the blog task.**
   - **If present** — the system is ready; just start writing posts. No setup needed.
   - **If absent** — adding a blog is a code task; capture it in `Zaj-BACKLOG.md`.

   - ✅ Blog status is confirmed (ready now or captured in `Zaj-BACKLOG.md`). Blog content is a **growth activity, not a launch blocker.**

</Steps>

### 5. Verify the sitemap

**CHECK:** visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

<Steps>

1. **Verify now or capture the sitemap task.**
   - **If auto-generated** — confirm it lists your key pages, then submit it to Google Search Console.
   - **If absent** — generating a sitemap is a small code/SEO task; capture it in `Zaj-BACKLOG.md`.

   - ✅ `/sitemap.xml` is verified and submitted to Search Console, or captured in `Zaj-BACKLOG.md`. Important for SEO but **not a launch blocker.**

</Steps>

:::note[Who does this]
🔀 **User + Agent** — 👤 the user authorizes the Google account/property. 🤖 With that session, the agent can submit the sitemap, capture evidence, and verify the submitted URL status.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🔀 GA4 wired** — built-in field **or** the 3-file deviation; `curl | grep -c` returns **≥1** for the real Measurement ID; Realtime shows traffic; deviation recorded in `Zaj-CUSTOMIZATIONS.md`.
- [ ] **🔀 Consent dependency queued** — GA4 consent-gating (page 6) is in `Zaj-BACKLOG.md` for production launch.
- [ ] **🔀 Chat configured** — chat widget configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Social login handled** — configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion; existing `SocialLoginController` checked before any new build.
- [ ] **🤖 Blog status confirmed** — ready now or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Sitemap handled** — `/sitemap.xml` verified and submitted to Search Console **or** captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.

:::next[Next step]
SuperAdmin setup is complete. Continue to **[Phase 7 · Security & monitoring](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/)** — harden the app, then wire backups and observability before real users arrive.
:::

# 8 · Engagement & SEO

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/08-engagement-and-seo/

## TL;DR

**Objective** — wire the growth surfaces, led by GA4 via the universal **3-file Safe Vendor Deviation Pattern** (one blade edit, one config key, one env var) — the canonical example whose shape recurs for Sentry JS, PostHog, Pixel, and Turnstile — then run check-first on chat, social login, blog, and sitemap.

**Steps at a glance:**
1. **Wire analytics tracking (GA4)** — Getting the Measurement ID and confirming Realtime are
   Google-Analytics-dashboard actions a person performs; the 3-file code change is agent work.
2. **Configure the chat widget** — CHECK: `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget
   field.
3. **Configure social login** — CHECK: `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Creating
   provider apps is mixed: the human owns login/consent/secret fields, while the agent can drive non-secret
   console setup and panel verification after authorization.
4. **Confirm the blog system** — CHECK: `Admin → Blog` (or `Posts` / `Content`).
5. **Verify the sitemap** — CHECK: visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

:::note[User part + done-when]
**🔀 User part** — the human owns provider login, OAuth app authorization, and any secret fields. The agent can drive non-secret provider-console navigation after the authorized session exists, make the 3-file blade/config/env edits, run `curl`, and verify Realtime when the dashboard session is available.

**Done when** GA4 is wired (built-in field or the 3-file deviation), `curl | grep -c` returns **≥1** for the real Measurement ID, Realtime shows traffic, and chat/social/blog/sitemap are each configured or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ 30–90 min** &nbsp;·&nbsp; 🔀 mixed (👤 GA4 property + OAuth, 🤖 3-file edit + verify).
:::

## Background

The growth surfaces — analytics, chat, social login, blog, sitemap. Most are **SHOULD** check-first tasks or tracked post-launch non-blockers, but **analytics is the canonical example of the universal Safe Vendor Deviation Pattern** and earns the most space because the same 3-file shape recurs for Sentry JS, PostHog, Facebook Pixel, Turnstile, and more.

:::caution[SSH artisan + `shared/.env` use `$PHP_BIN` and "add-not-set"]
Config-cache rebuilds run over SSH — use the `$PHP_BIN` from [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/). Always append to `shared/.env` idempotently (`grep -q … || echo …`); never overwrite a line silently.
:::

## Steps

### 1. Wire analytics tracking (GA4)

:::note[Prerequisite — finish the demo-content audit first]
Wire GA4 **after** the demo-content replacement on [page 3](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/03-credentials-and-branding/), or your event stream fills with test clicks on vendor placeholder content.
:::

Getting the Measurement ID and confirming Realtime happen in the Google Analytics dashboard. Use the [vendor console automation guide](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) when an agent drives the non-secret console steps after the human login; the 3-file code change is agent work.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** handles Google login and any account authorization. 🤖 **Agent** can drive non-secret GA4 property/stream navigation and Realtime verification after the session exists.
:::

**Most CodeCanyon Laravel scripts ship ZERO built-in analytics** — no admin field, no `tracking_code` column. Pick your path from the capabilities doc.

**Path 1 — vendor has a built-in analytics field (rare):** `Admin → Config → SEO` (or `Settings → Tracking`) → paste the Measurement ID → save → view-source the landing page to confirm the GA4 script is present → check GA4 Realtime.

**Path 2 — no built-in field (common): the 3-file Safe Vendor Deviation.** The pattern keeps your change small, env-gated, and auditable across vendor updates — one blade edit, one convention-file key, one env var:

```mermaid
flowchart LR
    BLADE["landing.blade.php<br/>@if(config('services.google.ga4_measurement_id'))<br/>…gtag snippet…"]
    CONFIG["config/services.php<br/>'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]"]
    ENV["shared/.env<br/>GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\""]
    BLADE -->|reads via config()| CONFIG
    CONFIG -->|reads via env()| ENV
```

<Steps>

1. **Edit the blade** — in `resources/views/layouts/landing.blade.php` (the **public landing** layout — **not** `guest.blade.php`, which has Jetstream tenant-context issues, and **not** authenticated app layouts), insert the standard `gtag.js` snippet **right before `</head>`**, gated on config **and** cookie consent (Termly/GetTerms autoblock or your Phase 6/7 banner). Example with Termly autoblock — the script stays inert until analytics consent:

   ```blade
   @if (config('services.google.ga4_measurement_id'))
   {{-- <PROJECT> Phase 6 — GA4 (consent-gated; Termly data-auto-block="on" must load first in <head>) --}}
   <script type="text/plain" data-cookie-category="analytics"
     src="https://www.googletagmanager.com/gtag/js?id={{ config('services.google.ga4_measurement_id') }}"></script>
   <script type="text/plain" data-cookie-category="analytics">
     window.dataLayer = window.dataLayer || [];
     function gtag(){dataLayer.push(arguments);}
     gtag('js', new Date());
     gtag('config', '{{ config('services.google.ga4_measurement_id') }}');
   </script>
   @endif
   ```

   - ✅ The gtag snippet is config-gated, **consent-gated** (not unconditional), with a project-name comment marker.

2. **Edit the config** — add `'google' => ['ga4_measurement_id' => env('GA4_MEASUREMENT_ID')]` to `config/services.php`. Vendors almost never touch this convention file, which is what makes it a safe home. **Read via `config(...)`, never `env(...)` from blade/app code.**

   - ✅ `config/services.php` exposes `services.google.ga4_measurement_id`.

3. **Append the env var** to **`shared/.env` on the server** (not the ephemeral release `.env`), then rebuild the config cache.

   ```bash
   PHP_BIN=$(grep "set('bin/php'" deploy.php | grep -oE "/[^'\"]+/php" | head -1)
   DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md, e.g. staging-primary/qa/uat/client-demo
   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
   SSH_ALIAS="<non-prod-alias-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "grep -q '^GA4_MEASUREMENT_ID=' $DEPLOY_PATH/shared/.env \
     || echo 'GA4_MEASUREMENT_ID=\"G-XXXXXXXXXX\"' >> $DEPLOY_PATH/shared/.env"
   ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/current && $PHP_BIN artisan config:clear && $PHP_BIN artisan config:cache"
   # Expected: the ID is appended once on shared/.env, then the config cache rebuilds
   ```

   - ✅ `GA4_MEASUREMENT_ID` is set in `shared/.env` and the config cache is rebuilt.

4. **Verify the tag fires.**

   ```bash
   curl -sS https://nonprod.example.com/ | grep -c "$GA4_MEASUREMENT_ID"   # expect ≥1 (consent-gated tag may show once in HTML)
   # Expected: ≥1
   ```

   - ✅ `curl | grep -c` returns **≥1** for the real Measurement ID; GA4 → Reports → Realtime shows your visit within ~30s. **Record the deviation** in `Zaj-CUSTOMIZATIONS.md` (file / what added / task / comment marker) — that registry is the shopping list for every vendor-update merge.

</Steps>

:::danger[Consent gate is a launch blocker]
GA4 must **not** fire before analytics consent on production **or the selected non-production environment** (EU testers need a banner on QA/UAT/client-demo hosts too). Use Termly/GetTerms autoblock (`type="text/plain" data-cookie-category="analytics"`) or equivalent from [page 6](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/06-superadmin/06-legal-and-consent/) / [Phase 7 legal](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/06-legal-gdpr/). Local/dev may omit the tag entirely.
:::

### 2. Configure the chat widget

**CHECK:** `Admin → Settings` for a Crisp / Tawk.to / Intercom / generic widget field.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates/logs into the provider account and owns any widget secret/API key. 🤖 **Agent** can paste non-secret embed snippets or drive panel save/verify after the secret is available.
:::

<Steps>

1. **Configure now or capture the widget task.**
   - **If present** — paste the provider's widget code or API key.
   - **If absent** — capture the layout-footer widget task in `Zaj-BACKLOG.md` as a post-launch non-blocker.

   - ✅ The widget is configured, or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker with owner, trigger, and acceptance criterion.

</Steps>

### 3. Configure social login

**CHECK:** `Admin → Config → Login` (or `Social Auth` / `OAuth Settings`). Provider login, consent screens, and secret fields are human-owned; the non-secret console setup, callback URL verification, panel save, and browser checks are agent-drivable after the authorized session exists.

:::note[Who does this]
🔀 **User + Agent** — 👤 the user owns provider login, consent screens, secret/client-secret creation, and password entry. 🤖 With an authorized browser session, the agent can drive non-secret OAuth-app setup, copy public client IDs into the panel when safe, and verify callback URLs/scopes. See [vendor console automation](/tech-stack/laravel/codecanyon/learn/guides/vendor-console-automation/) for the safe console pattern.
:::

<Steps>

1. **Configure now or capture the social-login task.**
   - **If present** — enter the Google / Facebook / GitHub OAuth **client ID + secret** and enable the providers you want.
   - **If absent** — likely needs Laravel Socialite + code. **Check for an existing `SocialLoginController` before building from scratch** — many vendors ship one that's just unwired.

   - ✅ Social login is configured (OAuth app created first), or captured in `Zaj-BACKLOG.md` as a post-launch non-blocker after checking for an existing `SocialLoginController`.

</Steps>

### 4. Confirm the blog system

**CHECK:** `Admin → Blog` (or `Posts` / `Content`).

<Steps>

1. **Confirm status or capture the blog task.**
   - **If present** — the system is ready; just start writing posts. No setup needed.
   - **If absent** — adding a blog is a code task; capture it in `Zaj-BACKLOG.md`.

   - ✅ Blog status is confirmed (ready now or captured in `Zaj-BACKLOG.md`). Blog content is a **growth activity, not a launch blocker.**

</Steps>

### 5. Verify the sitemap

**CHECK:** visit `/sitemap.xml` on the domain, and look under `Admin → SEO`.

<Steps>

1. **Verify now or capture the sitemap task.**
   - **If auto-generated** — confirm it lists your key pages, then submit it to Google Search Console.
   - **If absent** — generating a sitemap is a small code/SEO task; capture it in `Zaj-BACKLOG.md`.

   - ✅ `/sitemap.xml` is verified and submitted to Search Console, or captured in `Zaj-BACKLOG.md`. Important for SEO but **not a launch blocker.**

</Steps>

:::note[Who does this]
🔀 **User + Agent** — 👤 the user authorizes the Google account/property. 🤖 With that session, the agent can submit the sitemap, capture evidence, and verify the submitted URL status.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🔀 GA4 wired** — built-in field **or** the 3-file deviation; `curl | grep -c` returns **≥1** for the real Measurement ID; Realtime shows traffic; deviation recorded in `Zaj-CUSTOMIZATIONS.md`.
- [ ] **🔀 Consent dependency queued** — GA4 consent-gating (page 6) is in `Zaj-BACKLOG.md` for production launch.
- [ ] **🔀 Chat configured** — chat widget configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Social login handled** — configured **or** captured as a post-launch non-blocker in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion; existing `SocialLoginController` checked before any new build.
- [ ] **🤖 Blog status confirmed** — ready now or captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.
- [ ] **🔀 Sitemap handled** — `/sitemap.xml` verified and submitted to Search Console **or** captured in `Zaj-BACKLOG.md` with owner, trigger, and acceptance criterion.

:::next[Next step]
SuperAdmin setup is complete. Continue to **[Phase 7 · Security & monitoring](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/07-security-monitoring/)** — harden the app, then wire backups and observability before real users arrive.
:::