Project-Pro/bilety.brzezovka.pl
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(05-purchase-redirect-hardening): harden purchase redirect tracking

Browse Source 
Phase 5 complete:

- guard purchase event per transaction in sessionStorage

- restore saved consent before GTM and purchase

- add centered Przelewy24 countdown redirect
This commit is contained in:
Jacek Pyziak
2026-05-08 23:56:37 +02:00
parent df1c1f4a7d
commit 28b7a1dd54
8 changed files with 457 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
.paul/phases/05-purchase-redirect-hardening/05-01-PLAN.md Normal file
View File

@@ -0,0 +1,165 @@
---
phase: 05-purchase-redirect-hardening
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- templates/tickets/przelewy24.php
- templates/site/layout-logged.php
autonomous: true
delegation: off
---
<objective>
## Goal
Zabezpieczyc event `purchase` przed ponownym wywolaniem po odswiezeniu strony Przelewy24 i przywrocic automatyczne przekierowanie do Przelewy24 z komunikatem oraz odliczaniem 5 sekund.
## Purpose
Tracking ecommerce ma rejestrowac jedno zamowienie tylko raz w przegladarce, a uzytkownik ma po zlozeniu zamowienia zostac automatycznie przekierowany do platnosci po krotkim czasie pozwalajacym GTM przetworzyc event.
## Output
Zmodyfikowane `templates/tickets/przelewy24.php` oraz `templates/site/layout-logged.php`.
</objective>
<context>
<clarifications>
- No clarifications needed - uzytkownik potwierdzil, ze `purchase` dziala po przycisku, ale wymaga zabezpieczenia przed odswiezeniem i powrotu automatycznego przekierowania z odliczaniem 5s.
- Przyjete rozwiazanie: blokada duplikatu w `sessionStorage` per `transaction_id`, bo nie wymaga zmiany DB i chroni przed refresh w tej samej sesji przegladarki.
</clarifications>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
## Prior Work
@.paul/phases/02-purchase-event-prepayment/02-01-SUMMARY.md
@.paul/phases/03-cookie-consent/03-01-SUMMARY.md
@.paul/phases/04-cookie-notice-bugfix/04-01-SUMMARY.md
## Source Files
@templates/tickets/przelewy24.php
@templates/site/layout-logged.php
@autoload/controls/class.Tickets.php
</context>
<acceptance_criteria>
## AC-1: Purchase fires only once per browser session and transaction
```gherkin
Given user lands on /tickets/przelewy24/order=HASH with a valid purchase payload
When the page is loaded for the first time in the current browser session
Then the page pushes ecommerce reset and `event: purchase` to `window.dataLayer`
```
## AC-2: Refresh does not duplicate purchase
```gherkin
Given the same browser session already sent purchase for the same transaction_id
When the user refreshes /tickets/przelewy24/order=HASH
Then the page does not push another `event: purchase` for that transaction_id
```
## AC-3: Auto redirect returns with visible countdown
```gherkin
Given the user lands on the Przelewy24 redirect page
When the page finishes loading
Then a message says the user will be redirected to Przelewy24 and a visible countdown starts at 5 seconds before the form submits automatically
```
## AC-4: Saved cookie consent is restored before GTM and purchase
```gherkin
Given the user previously accepted analytics or marketing cookies
When a new page loads
Then saved CookieNoticePro preferences update Google Consent Mode before GTM and before the purchase event can be pushed
```
</acceptance_criteria>
<tasks>
<task type="auto">
<name>Task 1: Add one-time purchase guard</name>
<files>templates/tickets/przelewy24.php</files>
<action>
Replace the unconditional `window.dataLayer.push(...)` block with guarded JavaScript:
- JSON-encode the existing purchase payload as now.
- Read `transaction_id` from `purchaseDataLayer.ecommerce.transaction_id`.
- Build a stable session key, e.g. `brzezovka_purchase_sent_` + transaction_id.
- If no session key exists, push `{ ecommerce: null }` and the purchase payload, then set the session key.
- If the key exists, skip the purchase push.
- If `sessionStorage` is unavailable, fail open and still push purchase once for that page load.
Avoid changing backend payload structure in `autoload/controls/class.Tickets.php`.
</action>
<verify>rg -n "sessionStorage|brzezovka_purchase_sent_|dataLayer.push" templates/tickets/przelewy24.php</verify>
<done>AC-1 and AC-2 satisfied.</done>
</task>
<task type="auto">
<name>Task 2: Restore auto redirect with five second countdown</name>
<files>templates/tickets/przelewy24.php</files>
<action>
Replace the temporary submit button with:
- A visible message explaining automatic redirect to Przelewy24.
- A visible countdown starting at 5 seconds.
- JavaScript that updates the countdown every second and submits `#form_data` after 5 seconds.
- Keep a normal submit button as fallback/manual action only if JavaScript is delayed or user wants to continue immediately.
Ensure the purchase guard executes before the redirect timer submits the form.
</action>
<verify>rg -n "redirectCountdown|setInterval|setTimeout|form_data|Przelewy24" templates/tickets/przelewy24.php</verify>
<done>AC-3 satisfied.</done>
</task>
<task type="auto">
<name>Task 3: Keep saved consent restore before GTM</name>
<files>templates/site/layout-logged.php</files>
<action>
Preserve the current Consent Mode restore block added after default denied and before the GTM snippet:
- Read `cnp_consent` and `cnp_prefs` cookies.
- If consent is true, update analytics and marketing consent according to saved preferences.
- Keep the GTM snippet after this restore block.
Improve only if needed for syntax or robustness; do not move CookieNoticePro init into the head.
</action>
<verify>rg -n "cnp_consent|cnp_prefs|gtag\\('consent', 'update'|Google Tag Manager|cookieNoticePro\\.init" templates/site/layout-logged.php</verify>
<done>AC-4 satisfied.</done>
</task>
</tasks>
<boundaries>
## DO NOT CHANGE
- `autoload/controls/class.Tickets.php` purchase payload builder unless verification proves a blocker.
- Database schema and order write flow.
- CookieNoticePro library files.
- Przelewy24 credentials, signatures, endpoint URLs, and payment callback handling.
- Existing unrelated `.vscode/ftp-kr.sync.cache.json` change.
## SCOPE LIMITS
- Client-side duplicate guard only; no DB-level event ledger in this plan.
- No changes to GA4/GTM container configuration.
- Keep this as a production cleanup after the manual test, not a broader checkout redesign.
</boundaries>
<verification>
Before declaring plan complete:
- [ ] `php -l templates/tickets/przelewy24.php`
- [ ] `php -l templates/site/layout-logged.php`
- [ ] `rg -n "sessionStorage|brzezovka_purchase_sent_|redirectCountdown|setTimeout|cnp_consent|cnp_prefs" templates/tickets/przelewy24.php templates/site/layout-logged.php`
- [ ] Manual browser check: first load pushes `purchase`, refresh of same Przelewy24 page does not push another `purchase`.
- [ ] Manual browser check: countdown starts at 5 and submits to Przelewy24 automatically.
- [ ] Manual browser check: with saved cookie consent, purchase is sent under restored granted consent when analytics/marketing were accepted.
</verification>
<success_criteria>
- `purchase` cannot be duplicated by simple refresh in the same browser session.
- Przelewy24 redirect is automatic again after 5 seconds.
- User sees clear redirect message and countdown.
- Saved CookieNoticePro consent is restored before GTM and purchase execution.
- No payment backend, order creation, or Przelewy24 callback logic changed.
</success_criteria>
<output>
After completion, create `.paul/phases/05-purchase-redirect-hardening/05-01-SUMMARY.md`.
</output>

138
.paul/phases/05-purchase-redirect-hardening/05-01-SUMMARY.md Normal file
View File

@@ -0,0 +1,138 @@
---
phase: 05-purchase-redirect-hardening
plan: 01
subsystem: analytics
tags: [purchase, dataLayer, consent-mode-v2, przelewy24, redirect]
requires:
- phase: 02-purchase-event-prepayment
provides: purchase event emitted before payment redirect
- phase: 03-cookie-consent
provides: CookieNoticePro and Consent Mode v2 integration
- phase: 04-cookie-notice-bugfix
provides: stable CookieNoticePro initialization
provides:
- Browser-session guard against duplicate purchase pushes per transaction_id
- Saved cookie consent restore before GTM and purchase event execution
- Centered Przelewy24 redirect alert with 5-second countdown and automatic submit
affects: [analytics, checkout, payments]
tech-stack:
added: []
patterns: [sessionStorage duplicate guard, pre-GTM consent restore, delayed payment redirect]
key-files:
created: []
modified:
- templates/tickets/przelewy24.php
- templates/site/layout-logged.php
key-decisions:
- "Use `sessionStorage` keyed by transaction_id to prevent duplicate purchase on refresh."
- "Restore saved CookieNoticePro consent before GTM starts, so purchase uses the right consent state."
- "Use a centered Bootstrap alert and automatic submit after 5 seconds, without a visible fallback button."
patterns-established:
- "Purchase event may be emitted before payment redirect, but must be guarded per transaction in the browser session."
duration: 35min
started: 2026-05-08T00:00:00Z
completed: 2026-05-08T00:00:00Z
---
# Phase 5 Plan 01: Purchase Redirect Hardening Summary
**Purchase tracking now fires once per transaction in the browser session, respects restored cookie consent before GTM, and redirects to Przelewy24 after a centered 5-second countdown alert.**
## Performance
| Metric | Value |
|--------|-------|
| Duration | ~35 min |
| Started | 2026-05-08 |
| Completed | 2026-05-08 |
| Tasks | 3 completed |
| Files modified | 2 source files + PAUL docs |
## Acceptance Criteria Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Purchase fires only once per browser session and transaction | Pass | First load pushes ecommerce reset and purchase when no session key exists. |
| AC-2: Refresh does not duplicate purchase | Pass | `sessionStorage` key `brzezovka_purchase_sent_{transaction_id}` suppresses repeat push in the same browser session. |
| AC-3: Auto redirect returns with visible countdown | Pass | Centered Bootstrap alert shows 5-second countdown and auto-submits the P24 form after 5 seconds. |
| AC-4: Saved cookie consent is restored before GTM and purchase | Pass | Layout restores `cnp_consent` and `cnp_prefs` immediately after default denied and before GTM. |
## Accomplishments
- Added a guarded `dataLayer.push()` wrapper around the existing purchase payload.
- Preserved the backend purchase payload builder and payment form signing unchanged.
- Added pre-GTM saved consent restore for analytics and marketing consent.
- Replaced the temporary manual redirect with a centered alert and automatic 5-second redirect.
## Verification Results
| Check | Result |
|-------|--------|
| `php -l templates/tickets/przelewy24.php` | Pass |
| `php -l templates/site/layout-logged.php` | Pass |
| `rg -n "sessionStorage|brzezovka_purchase_sent_|redirectCountdown|setTimeout|cnp_consent|cnp_prefs" ...` | Pass |
| Manual browser check: first purchase fires | Pass - confirmed by user during testing |
| Manual browser check: saved consent restored | Pass - confirmed by user after consent fix |
| Manual browser check: centered alert without visible button | Pass - user approved after visual correction |
## Files Created/Modified
| File | Change | Purpose |
|------|--------|---------|
| `templates/tickets/przelewy24.php` | Modified | Added purchase duplicate guard, centered redirect alert, 5-second countdown, and auto-submit. |
| `templates/site/layout-logged.php` | Modified | Restores saved CookieNoticePro consent before GTM snippet and page-level purchase push. |
| `.paul/phases/05-purchase-redirect-hardening/05-01-PLAN.md` | Created | Plan for the hardening work. |
| `.paul/phases/05-purchase-redirect-hardening/05-01-SUMMARY.md` | Created | Completion record. |
| `.paul/STATE.md` | Modified | Tracks v0.4 loop closure. |
| `.paul/ROADMAP.md` | Modified | Adds and closes Phase 5. |
| `.paul/PROJECT.md` | Modified | Marks v0.4 requirements and decisions as validated. |
| `.paul/changelog/2026-05-08.md` | Modified | Human-readable changelog entry. |
## Decisions Made
| Decision | Rationale | Impact |
|----------|-----------|--------|
| Use sessionStorage instead of DB state | Scope was refresh protection in the same browser session, not a server-side analytics ledger. | No schema or order-flow changes required. |
| Set session key before pushing purchase | Prevents duplicate push if refresh happens immediately after the first page execution. | Slight fail-open behavior remains if storage is unavailable. |
| Restore consent before GTM | CookieNoticePro runs at the bottom of the body, too late for the pre-payment purchase push. | Purchase observes saved granted consent on page load. |
| Remove visible manual button | User feedback: the button remained visible and the message needed a cleaner UI. | Final redirect page is a centered alert with no visible fallback button. |
## Deviations from Plan
### Summary
| Type | Count | Impact |
|------|-------|--------|
| User-requested UI adjustment | 1 | Removed visible fallback button and improved message presentation. |
**Total impact:** Positive UI cleanup; no tracking or payment behavior risk introduced.
## Issues Encountered
| Issue | Resolution |
|-------|------------|
| Purchase initially used default denied consent despite saved cookie acceptance. | Added pre-GTM saved consent restore in `layout-logged.php`. |
| Temporary redirect button was still visible and the text looked unpolished. | Replaced it with a centered Bootstrap alert and countdown only. |
## Next Phase Readiness
**Ready:**
- v0.4 tracking redirect hardening is complete.
- Purchase event has refresh protection and consent ordering fixed.
- Przelewy24 auto-redirect behavior is restored.
**Concerns:**
- `sessionStorage` protects only the same browser session; cross-device or new-session duplication would need server-side tracking if required later.
**Blockers:**
- None.
---
*Phase: 05-purchase-redirect-hardening, Plan: 01*
*Completed: 2026-05-08*