# Hyva_MetaConversion

Hyvä Theme compatibility module for **Meta_Conversion** (the "Meta Pixel &
Conversions API" module by Meta Platforms, Inc. — part of the official
`meta/module-conversion` / "Facebook & Instagram" Magento 2 integration).

`Meta_Conversion`'s frontend code depends entirely on jQuery, RequireJS
(`text/x-magento-init`), and `Magento_Customer/js/customer-data`
(Knockout). None of that is loaded in a Hyvä theme, so on Hyvä the module's
pixel/CAPI events silently never fire. This module replaces every
JS-dependent template with a plain, framework-free JavaScript
implementation and registers itself as a **Hyvä Compatibility Module**, so
no manual layout XML patching of the original module is required.

## What's in the box

```
Hyva_MetaConversion/
├── registration.php
├── composer.json
├── etc/
│   ├── module.xml
│   └── frontend/di.xml            <- registers the compat-module mapping
└── view/frontend/
    ├── layout/default.xml         <- loads meta-pixel.js in <head>
    ├── web/js/meta-pixel.js       <- vanilla-JS replacement library
    └── templates/pixel/*.phtml    <- Hyvä-safe template overrides
```

Templates that had **no** JS/jQuery dependency in the original module
(`noscript.phtml`, `status.phtml`) are intentionally **not** overridden —
they keep working as-is and simply fall back to the original module's
files.

## Installation

1. Make sure `Meta_Conversion` (the base Meta Pixel extension) and your
   Hyvä theme are already installed.
2. Copy the `Hyva_MetaConversion` folder into `app/code/Hyva/MetaConversion`
   of your Magento installation (the zip is already laid out this way —
   just extract it into `app/code/Hyva/`).
3. Run:
   ```
   bin/magento module:enable Hyva_MetaConversion
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento setup:static-content:deploy -f
   bin/magento cache:flush
   ```
4. Open your storefront, then check Meta Events Manager → **Test Events**
   to confirm PageView / ViewContent / etc. are being received.

> This module requires `hyva-themes/magento2-compat-module-fallback` to be
> installed (it ships with every Hyvä theme setup created via the Hyvä
> project template). If you get an "unknown type
> `Hyva\CompatModuleFallback\Model\CompatModuleRegistry`" error, run
> `composer require hyva-themes/magento2-compat-module-fallback` first.

## Event coverage & implementation notes

| Event | Status | Notes |
|---|---|---|
| PageView | ✅ Full | Fires from `head.phtml`, no dependency changes needed beyond dropping `text/x-magento-init`. |
| ViewContent (PDP) | ✅ Full | |
| ViewCategory (PLP) | ✅ Full | |
| Search | ✅ Full | |
| Contact | ✅ Full | Cookie-gated flow, unchanged logic, just jQuery-free. |
| AddToWishlist | ✅ Full | Cookie-gated flow, unchanged logic, just jQuery-free. |
| CompleteRegistration | ✅ Full | Cookie-gated flow, unchanged logic, just jQuery-free. |
| Purchase (order success page) | ✅ Full | |
| AddToCart | ✅ Rebuilt for Hyvä | Original code relied on Luma's `ajax:addToCart` jQuery event and swatch-renderer widget data, which don't exist in Hyvä. Rebuilt around a plain form-submit listener + Hyvä's `configurable-selection-changed` event + the `private-content-loaded` event (all documented Hyvä APIs). Works with Hyvä's default (page-reload) add-to-cart *and* AJAX add-to-cart add-ons. |
| CustomizeProduct | ✅ Rebuilt for Hyvä | Original code scraped Luma-specific CSS classes. Rebuilt around Hyvä's documented `configurable-selection-changed` / `listing-configurable-selection-changed` events. |
| InitiateCheckout | ⚠️ Conditional | No JS rewrite was actually needed (it only fires once on page load), **but** it only renders if your checkout page layout still exposes the standard `before.body.end` container. Confirm this works if you use **Hyvä Checkout** (a separate, self-contained checkout product) — its layout may not include that container by default. |
| AddPaymentInfo | ⚠️ Best effort | The original hooks into Magento_Checkout's Knockout.js `place-order-hooks`, which does not exist under Hyvä Checkout. This version listens for `change` on any `input[name="payment[method]"]` field (the standard Magento payment-method form field name). **Verify this actually fires in Meta Events Manager's Test Events tool** — if your checkout doesn't use that field name, you'll need to call `window.MetaConversion.trackEvent(config)` manually from your checkout's own JS. |

## How the library works

Everything lives in `window.MetaConversion` (`view/frontend/web/js/meta-pixel.js`),
loaded once, globally, as a plain non-deferred `<script>` tag (no
RequireJS). It re-implements, framework-free:

- `initPixel(config)` — loads `fbevents.js` and calls `fbq('init', ...)`.
- `trackEvent(config)` — fires the browser pixel event via `fbq()` **and**
  posts the matching server-side CAPI event, using an event ID drawn from
  the `capi-event-ids` private-content section (fetched directly via
  `/customer/section/load`, replacing `Magento_Customer/js/customer-data`).
- `addToCart`, `customizeProduct`, `addToWishlist`, `contactPixel`,
  `customerRegistration`, `addPaymentInfo` — the per-event glue described
  in the table above.
- `serialize()` / `postForm()` — a small `jQuery.param()`-equivalent
  serializer, because the module's PHP controllers expect classic
  `application/x-www-form-urlencoded` bracket-notation (`payload[contents][0][id]`)
  for nested arrays, not JSON bodies.

## Customizing further

If your theme customizes the add-to-cart form markup, checkout, or the
configurable-product selector so that it no longer dispatches Hyvä's
standard events, open `meta-pixel.js` and adjust the corresponding
listener — every function is short, commented, and independent of the
others.