drmaterac.pl/.paul/phases/03-ga4-checkout-events/03-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, delegation

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
03-ga4-checkout-events	01	execute	1		modules/pdgoogleanalytycs4pro/views/templates/hook/displayFooter.tpl modules/pdgoogleanalytycs4pro/views/js/scripts_17.js modules/pdgoogleanalytycs4pro/controllers/front/ajax.php modules/pdgoogleanalytycs4pro/views/templates/hook/addDeliveryInfo.tpl modules/pdgoogleanalytycs4pro/views/templates/hook/addPaymentInfo.tpl	false	off

## Goal Fix GA4 checkout tracking in `modules/pdgoogleanalytycs4pro` so checkout emits the intended event sequence: `begin_checkout` once from the cart CTA, `add_shipping_info` after address confirmation / shipping step entry, `add_payment_info` when payment is selected, and `purchase` on order confirmation.

Purpose

The client currently sees repeated begin_checkout events in Tag Assistant across checkout steps and does not reliably see the later ecommerce events. The plan restores useful funnel reporting without touching PrestaShop core.

Output

Scoped changes to the GA4 module JavaScript/templates/controller logic, plus a completion summary at .paul/phases/03-ga4-checkout-events/03-01-SUMMARY.md.

- No clarifications needed - the client message defines the target sequence and trigger moments. - Assumption: the primary checkout is the standard PrestaShop 1.7 step checkout rendered by `body#checkout` and `themes/leo_gstore/templates/checkout/_partials/steps/*.tpl`; existing module fallbacks for known OPC modules should not be removed unless they directly cause duplicate events. - Assumption: `purchase` remains controlled by the module's existing order confirmation logic; this plan verifies and preserves it rather than moving purchase to a checkout-step click.

Project Context

@.paul/PROJECT.md @.paul/ROADMAP.md @.paul/STATE.md @.paul/codebase/architecture.md @.paul/codebase/db_schema.md

Source Files

@modules/pdgoogleanalytycs4pro/pdgoogleanalytycs4pro.php @modules/pdgoogleanalytycs4pro/views/templates/hook/displayFooter.tpl @modules/pdgoogleanalytycs4pro/views/js/scripts_17.js @modules/pdgoogleanalytycs4pro/controllers/front/ajax.php @modules/pdgoogleanalytycs4pro/views/templates/hook/addDeliveryInfo.tpl @modules/pdgoogleanalytycs4pro/views/templates/hook/addPaymentInfo.tpl @modules/pdgoogleanalytycs4pro/views/templates/hook/displayOrderConfirmation.tpl @themes/leo_gstore/templates/checkout/_partials/steps/addresses.tpl @themes/leo_gstore/templates/checkout/_partials/steps/shipping.tpl @themes/leo_gstore/templates/checkout/_partials/steps/payment.tpl

<acceptance_criteria>

AC-1: Begin Checkout Fires Once From Cart CTA

Given a customer has products in the cart
When the customer clicks "przejdz do realizacji zamowienia" / checkout CTA from the cart
Then GA4 receives one `begin_checkout` event for that cart transition
And navigating between checkout steps does not emit additional `begin_checkout` events

AC-2: Shipping Event Fires At Shipping Stage

Given a customer is in checkout with address data accepted
When the checkout advances from address/customer data into delivery selection or confirms the delivery option
Then GA4 receives `add_shipping_info` with cart items, value, currency, and `shipping_tier`
And the event is not emitted repeatedly from unrelated checkout step refreshes

AC-3: Payment Event Fires On Payment Selection

Given a customer is on the payment step
When the customer selects a payment option
Then GA4 receives `add_payment_info` with cart items, value, currency, and `payment_type`
And accepting terms or refreshing the step does not cause duplicate payment events for the same selected option

AC-4: Purchase Remains Available On Confirmation

Given an order is successfully placed
When the order confirmation page renders
Then GA4 receives `purchase` with transaction id, value, shipping, tax, currency, and item data
And the fix for earlier checkout steps does not disable the existing purchase path

</acceptance_criteria>

Task 1: Move begin_checkout to the cart checkout CTA modules/pdgoogleanalytycs4pro/views/templates/hook/displayFooter.tpl, modules/pdgoogleanalytycs4pro/views/js/scripts_17.js Stop automatic footer-rendered `begin_checkout` on `tagType === 'order'` / `order-opc`, because that fires on each checkout page/step render. Preserve the existing ecommerce payload generation by either reusing the rendered data in a JS-accessible helper or moving the trigger into a click handler for the cart's checkout CTA. Add a client-side once guard keyed by cart/session so double clicks or repeated binding do not send duplicate `begin_checkout`. Preserve existing lulandia.pl Ads conversion behavior only when `begin_checkout` actually fires. Inspect rendered cart HTML/JS and use browser console/Tag Assistant to confirm one `begin_checkout` after clicking the cart checkout CTA and none from checkout step navigation. AC-1 satisfied. Task 2: Trigger shipping and payment events from real checkout transitions modules/pdgoogleanalytycs4pro/views/js/scripts_17.js, modules/pdgoogleanalytycs4pro/controllers/front/ajax.php, modules/pdgoogleanalytycs4pro/views/templates/hook/addDeliveryInfo.tpl, modules/pdgoogleanalytycs4pro/views/templates/hook/addPaymentInfo.tpl Replace or augment the current radio-click-only handlers with handlers aligned to the PrestaShop 1.7 checkout flow: - `add_shipping_info`: fire when address confirmation moves the customer into the delivery step and/or when `confirmDeliveryOption` is submitted, using the currently selected carrier. - `add_payment_info`: fire when `input[name="payment-option"]` is selected on the payment step. Add de-duplication guards keyed by selected carrier/payment module and cart so repeated DOM updates do not emit duplicate events. Ensure AJAX responses containing script snippets are inserted into an existing stable container or executed safely even when `#hook-display-before-carrier` is absent. Fix unsafe coupon checks in `ajax.php` such as `($cart_rules & is_array($cart_rules))` if touched, using `is_array($cart_rules) && sizeof($cart_rules)`. Use Tag Assistant and browser console on checkout: address continue -> `add_shipping_info`; payment radio selection -> `add_payment_info`; repeat step refreshes do not duplicate the same selected values. AC-2 and AC-3 satisfied. Task 3: Preserve purchase and validate syntax modules/pdgoogleanalytycs4pro/controllers/front/ajax.php, modules/pdgoogleanalytycs4pro/views/templates/hook/displayOrderConfirmation.tpl Confirm the existing `purchase` path still renders on order confirmation when `PD_GA4P_TRANSACTION_SEND_TYPE` is frontend-confirmation mode. Do not move `purchase` onto payment or final-summary clicks. Only adjust escaping or event wrapper code if required by the previous tasks; otherwise leave purchase template behavior intact. Run `php -l modules\pdgoogleanalytycs4pro\controllers\front\ajax.php` and confirm an order confirmation page still includes a single `gtag('event', 'purchase', ...)` block or Tag Assistant sees `purchase` after order placement. AC-4 satisfied and PHP syntax passes. GA4 checkout funnel event sequencing for begin_checkout, add_shipping_info, add_payment_info, and purchase. 1. Open Tag Assistant for the test domain. 2. Add a product to cart and click the cart checkout CTA. 3. Confirm exactly one `begin_checkout`. 4. Continue through personal/address data into delivery and confirm `add_shipping_info`. 5. Select payment and confirm `add_payment_info`. 6. Place a test order and confirm `purchase`. Type "approved" if the sequence is correct, or describe the missing/duplicated event.

DO NOT CHANGE

• PrestaShop core files in classes/, controllers/, vendor/, or root checkout controllers.
• Theme checkout templates unless implementation proves the module cannot hook into the existing DOM safely.
• GA4 Measurement Protocol server-side purchase logic in hookActionOrderStatusPostUpdate, except for read-only verification.
• Unrelated analytics modules such as fbpixel.

SCOPE LIMITS

• This plan fixes GA4 event timing only; it does not redesign the checkout UI.
• No new third-party dependencies.
• No database schema changes.
• Preserve existing item payload fields as much as possible.

Before declaring plan complete: - [ ] `php -l modules\pdgoogleanalytycs4pro\controllers\front\ajax.php` - [ ] Browser console has no JavaScript errors from `scripts_17.js`. - [ ] Tag Assistant shows the sequence: one `begin_checkout` -> `add_shipping_info` -> `add_payment_info` -> `purchase`. - [ ] Repeating checkout step navigation does not duplicate already-sent event values. - [ ] All acceptance criteria met.

<success_criteria>

• begin_checkout no longer fires automatically on every checkout step.
• add_shipping_info and add_payment_info fire on their intended checkout stages.
• Existing purchase event remains functional.
• Changes are scoped to pdgoogleanalytycs4pro unless a checkout-template blocker is discovered.
• A completion summary is written after implementation. </success_criteria>

After completion, create `.paul/phases/03-ga4-checkout-events/03-01-SUMMARY.md`.