# JavaScript-események

> A pmw:event:* figyelhető és a pmw:* belépő események, az eseménybusz (pmw.bus), az adatcsomag, a hozzájárulás kezelése és az életciklus-események.

A Pixel Manager JavaScript eseményes API-t kínál: egyrészt a saját eseménybuszán (`pmw.bus`), másrészt a jQuery eseményrendszerén, amely tartósan támogatott marad. Két irányban használhatod:

- A `pmw:event:*` eseményeket **figyeled**, hogy mindenre reagálj, amit a Pixel Manager követ, a teljesen feldolgozott adatcsomaggal.
- A `pmw:*` eseményt **kiváltod**, hogy jelezd a Pixel Managernek: történt valami, amit ő maga nem tudott észlelni.

Mindkettő támogatott belépési pont a saját kódodnak és a harmadik fél bővítményeinek.

## Melyik irányra van szükséged?

| Ezt szeretnéd | Ezt használd | Példa |
|---|---|---|
| Adatot küldeni egy másik rendszernek, valahányszor a Pixel Manager követ valamit | a `pmw:event:*` figyelése | minden vásárlást a saját elemző végpontodra küldeni |
| Olyan pixelt vagy konverziót hozzáadni, amelyet a Pixel Manager nem fed le | a `pmw:event:*` figyelése | partnerhálózati címkét elsütni vásárláskor |
| Elérni, hogy a Pixel Manager követeljen egy interakciót, amelyet nem lát | a `pmw:*` kiváltása | fej nélküli vagy egyedi készítésű kosárba tétel gomb |
| Módosítani az adatot, mielőtt egy platformhoz ér | egyik sem, használj [eseményszűrőt](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-esemenyszurok/) | a Metának küldött termékazonosító átírása |

Ha csak azt akarod módosítani, amit a Pixel Manager már küld, használj eseményszűrőt. A szűrők a feldolgozási láncon belül futnak és módosítják az adatcsomagot, az itt leírt események a lánc körül futnak.

## Események figyelése

Figyeld a `pmw:event:<eseménynév>` eseményt. Az eseménynév a követési esemény neve, az alsóvonások kötőjelre cserélve: az `add_to_cart` így `pmw:event:add-to-cart` lesz.

Az ajánlott mód a Pixel Manager saját eseménybusza:

```js
pmw.bus.on("pmw:event:purchase", function (payload) {
    console.log(payload.event);       // az esemény neve
    console.log(payload.event_data);  // az esemény fő adatai
    console.log(payload.context);     // környezet, hozzájárulási állapot
    console.log(payload.pixels);      // pixelenkénti adatok
    console.log(payload.firing);      // melyik pixel sült el
});
```

A jQuery-s forma az eredeti, és tartósan támogatott marad. Használd, ha az eseménybuszt még nem tartalmazó régebbi változatot is támogatnod kell. Figyelj a különbségre: a jQuery a visszahívásnak `(event, payload)` értékeket ad, a `pmw.bus.on()` közvetlenül a `payload`-ot.

```js
jQuery(document).on("pmw:event:purchase", function (event, payload) {
    console.log(payload.event);
});
```

Ezek az események azután futnak, hogy a Pixel Manager feldolgozta az eseményt, alkalmazta az összes szűrőt, és eldöntötte, mely pixelek sülnek el. Ezért a végleges, hiteles adat olvasására ez a megfelelő hely.

### A regisztráció időzítése

A legtöbb esemény csak azokhoz a kezelőkhöz jut el, amelyek az elsülés pillanatában már léteznek. A vásárlási esemény kivétel, mert rendelésenként pontosan egyszer sül el, utána véglegesen zárolódik (az oldal újratöltése sem ismétli). Az az integráció, amely túl későn regisztrált, elvesztené a konverziót, második esély nélkül.

Ezért a `pmw:event:purchase` és a belépő `pmw:purchase` esemény visszajátszható: az utolsó adatcsomagját a busz megőrzi, és a `pmw.bus.on()` hívással az elsülés után regisztrált kezelő azonnal megkapja. Más esemény nem játszódik vissza, és a visszajátszás csak a buszon létezik. A `jQuery(document).on()` vagy `document.addEventListener()` kezelő soha nem hall olyat, ami a kötése előtt sült el.

A kezelőidet mindenképp a [parancssorból](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-command-queue/) regisztráld. Ez az egyetlen forma, amely a jQuery API-val és a régebbi változatokkal is biztonságos.

> **Fontos:** A saját kódodat minden oldalon töltsd be, ne csak a rendelés-megerősítő oldalon. A vásárlási esemény nem csak a megerősítő oldalon sül el: az [Automatic Conversion Recovery](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/funkciok-acr/) (Pro) egy közönséges bolti oldalon is elsüti, amikor olyan vásárló tér vissza, akinek a rendelését nem követték, és ugyanazt a rendelésobjektumot tölti ki. Az a kódrészlet, amely csak a megerősítő oldalra kerül ki, éppen azokat a rendeléseket hagyja ki, amelyeknek a visszaszerzésére a helyreállítás való. Az esemény a kapu, ezért biztonságos mindenhol betölteni a kódot.

### Elérhető események

A Pixel Manager minden feldolgozott eseményt kiküld:

| Esemény | Mikor sül el |
|---|---|
| `pmw:event:page-view` | oldalmegtekintéskor |
| `pmw:event:view-item` | termékmegtekintéskor |
| `pmw:event:view-item-list` | amikor egy terméklista láthatóvá válik |
| `pmw:event:view-category` | termékkategória-oldal megtekintésekor |
| `pmw:event:select-item` | listában egy termékre kattintáskor |
| `pmw:event:search` | keresési találati oldal megtekintésekor |
| `pmw:event:add-to-cart` | termék kosárba tételekor |
| `pmw:event:remove-from-cart` | termék kosárból való eltávolításakor |
| `pmw:event:view-cart` | a kosár megtekintésekor |
| `pmw:event:add-to-wishlist` | termék kívánságlistára tételekor |
| `pmw:event:begin-checkout` | a pénztár megkezdésekor |
| `pmw:event:add-shipping-info` | szállítási mód kiválasztásakor |
| `pmw:event:add-payment-info` | fizetési mód kiválasztásakor |
| `pmw:event:place-order` | a rendelés gombra kattintáskor |
| `pmw:event:purchase` | a vásárlást megerősítő oldal elérésekor |
| `pmw:event:login` | vásárló bejelentkezésekor |
| `pmw:event:account-created` | vásárlói fiók létrehozásakor |

### Az adatcsomag (payload)

| Kulcs | Tartalom |
|---|---|
| `event` | az esemény neve kanonikus alakban, például `add_to_cart` |
| `event_data` | az esemény fő adatai: `product`, `order` és így tovább. Üres azoknál az eseményeknél, amelyek nem hordoznak saját adatot |
| `context` | `timestamp`, `url`, `referrer`, `user_agent`, `page_type`, `user_id` és a teljes `consent` állapot |
| `pixels` | az esemény adatai az egyes aktív pixelek saját formátumában |
| `firing` | pixelenként, hogy elsült-e a böngészőben és hogy elsült-e a szerver oldalán |

### Vedd figyelembe a hozzájárulást

Az adatcsomag a látogató hozzájárulási állapotától függetlenül kiküldésre kerül, hogy a kódod maga dönthessen. A `payload.context.consent` megmondja, mit engedélyezett a látogató:

```js
pmw.bus.on("pmw:event:purchase", function (payload) {
    if (!payload.context.consent.categories.marketing) return;
    // csak akkor fut, ha a látogató elfogadta a marketing sütiket
});
```

> **Figyelem:** Ha a kódod sütit állít be vagy személyes adatot küld harmadik félnek, a hozzájárulás tiszteletben tartásáért te felelsz. A Pixel Manager a hozzájárulást csak a saját pixeleire alkalmazza.

### Az eseményt olvasd, ne az adatréteget

Csábító kihagyni az eseményt, és a `pmwDataLayer.order` értéket közvetlenül a megerősítő oldalon egy beágyazott szkriptből olvasni. Ne tedd. Az esemény hordozza a Pixel Manager garanciáit: rendelésenként egyszer sül el, a helyreállítás (ACR) által visszaszerzett rendeléseknél is elsül, és a feldolgozott adatcsomagot adja. Az adatréteg-objektum egyszerűen jelen van az oldalon, ezért az azt közvetlenül olvasó kód minden újratöltéskor elsül, soha nem lát visszaszerzett rendelést, és nincs hozzájárulási állapota, amelyet megnézhetne.

A hozzájárulást az esemény nem dönti el helyetted. A saját címkéd a Pixel Manager láncán kívül sül el, ezért a hozzájárulás ellenőrzése a kezelődbe tartozik.

## Események kiváltása

Váltsd ki a `pmw:<eseménynév>` eseményt, ha a Pixel Manager nem tud magától észlelni egy interakciót. Ezek a belépő események, ugyanazok, amelyeket a Pixel Manager saját figyelői használnak, ezért az esemény a teljes láncon végigmegy: szűrők, az összes aktív pixel, szerveroldali követés és hozzájárulás-kezelés mind érvényesül.

Az ajánlott mód az eseménybusz:

```js
pmw.bus.emit("pmw:add-to-cart", product);
```

A jQuery-s forma az eredeti, tartósan támogatott:

```js
jQuery(document).trigger("pmw:add-to-cart", product);
```

Mindkettő ugyanazokat az eseményneveket és argumentumokat fogadja, és ugyanoda jut. Figyeléskor ne feledd a kezelő aláírásának különbségét: a `pmw.bus.on()` közvetlenül az adatcsomagot adja, a jQuery `(event, payload)` párost.

### Elérhető események

| Esemény | Argumentum | Megjegyzés |
|---|---|---|
| `pmw:add-to-cart` | termékobjektum | lásd: Termékobjektum összeállítása |
| `pmw:remove-from-cart` | termékobjektum | |
| `pmw:view-item` | termékobjektum, nem kötelező | |
| `pmw:view-item-list` | termékobjektum, nem kötelező | |
| `pmw:view-category` | termékobjektum, nem kötelező | |
| `pmw:select-item` | termékobjektum | |
| `pmw:add-to-wishlist` | termékobjektum | |
| `pmw:search` | nincs | a keresőkifejezést az oldalról olvassa ki |
| `pmw:view-cart` | nincs | |
| `pmw:begin-checkout` | nincs | a Pixel Manager saját pénztári indítóival szemben kettőzésmentesítve |
| `pmw:add-shipping-info` | `{shippingTier: {slug, text}}` | |
| `pmw:add-payment-info` | `{paymentType: {slug, text}}` | |
| `pmw:place-order` | nincs | |
| `pmw:purchase` | nincs | a rendelést az adatrétegből olvassa |
| `pmw:login` | nincs | |
| `pmw:account-created` | nincs | |

> **Vigyázat:** Ne váltsd ki a `pmw:purchase` eseményt olyan rendelés jelentésére, amelyről a Pixel Manager nem tud. A rendelést a `pmwDataLayer.order` objektumból olvassa, amelyet a bővítmény a vásárlást megerősítő oldalon ír ki, és nem kerüli meg a rendelés kettőzésmegelőzését. Vásárlások jelentése a saját kódodból nem támogatott út.

### Mikor váltsd ki őket?

A Pixel Manager csak azután reagál egy belépő eseményre, hogy regisztrálta a saját figyelőit és betöltötte a pixeleket. Ez az indulás végén történik: előtte megvárja a jQuery-t, az adatréteget és a hozzájárulás-kezelő platformot is.

Az újabb változatokban ez már nem számít: a Pixel Manager indulása közben érkező belépő eseményt visszatartja, és amint kész, feldolgozza, a kiváltás sorrendjében. Bármikor kiválthatsz egyet, miután a `pmw.bus` létezik.

A régebbi változatokban a Pixel Manager teljes betöltése előtt kiváltott belépő eseményt csendben eldobta. Semmit nem naplózott és egy pixel sem sült el, ami pontosan úgy néz ki, mint a hibás adatcsomag vagy a rossz eseménynév. Tipikus áldozat az a kódrészlet, amely valamit a bolt vagy egy pénztári bővítmény korai kirajzolására reagálva jelent. Azokon a változatokon a kiváltás előtt várd meg a `pmwLoad` eseményt:

```js
document.addEventListener("pmwLoad", function () {
    jQuery(document).trigger("pmw:add-shipping-info", {shippingTier: {slug: "flat_rate", text: "Fix díj"}});
});
```

A parancssor itt nem segít: az a belépő figyelők regisztrálása előtt fut. A saját figyelőid és szűrőid regisztrálására való, nem belépő esemény kiváltására azokon a változatokon.

Ha a kódodnak tudnia kell, hogy a Pixel Manager regisztrálta-e már egy esemény figyelőjét, megkérdezheted:

```js
if (pmw.bus.hasListeners("pmw:add-to-cart")) {
    // a Pixel Manager már figyeli
}
```

Az újabb változatokon a kiváltáshoz nincs szükség erre az ellenőrzésre. Régebbi változatokon hasznos, és akkor is, ha a kódod ki akarja hagyni egy olyan adatcsomag összeállítását, amelyet senki nem olvas.

Egyet semmilyen változat nem tud megtartani: azt az eseményt, amelyet a Pixel Manager szkriptjének első lefutása előtt váltanak ki. Ilyenkor a `pmw.bus` még nem létezik, és a kódod hibát dobna. Tedd a parancssorba, amely akkor futtatja a függvényedet, amikor a Pixel Manager odaér, és onnantól a Pixel Manager tartja vissza az eseményt.

#### Duplikátumok

A belépő esemény annak a jelentése, hogy valami történt, nem kérés arra, hogy egy pixel kétszer süljön el. A Pixel Manager a saját indítója és a te kódod által is jelentett szállítási módot egyetlen `add_shipping_info` eseménnyé vonja össze, a `pmw:begin-checkout` pedig a saját pénztári indítói ellen van kettőzésmentesítve. A többi esemény úgy megy át, ahogy kiváltottad, ezért minden interakciót egyszer válts ki.

### Termékobjektum összeállítása

A termék argumentum nem szabad formátumú. A Pixel Manager saját segédfüggvényével állítsd össze, hogy minden mezőt tartalmazzon, amit a pixelek várnak:

```js
let product = pmw.getProductDetailsFormattedForEvent(productId, quantity);
```

Ha a termék még nincs az adatrétegben, mert az oldalon sosem jelent meg, előbb kérd le a szervertől:

```js
if (!pmwDataLayer.products[productId]) {
    await pmw.getProductsFromBackend([productId]);
}
```

### Teljes példa: egyedi kosárba tétel gomb

Így működik a Pixel Manager saját Doofinder-integrációja: figyeli a keresőbővítmény eseményét, és átadja a terméket a Pixel Managernek.

```js
document.addEventListener("doofinder.cart.add", async function (event) {
    const {item_id, amount} = event.detail;

    if (!pmwDataLayer.products[item_id]) {
        await pmw.getProductsFromBackend([item_id]);
    }
    if (!pmwDataLayer.products[item_id]) return;

    const product = pmw.getProductDetailsFormattedForEvent(item_id, amount);
    if (!product) return;

    pmw.bus.emit("pmw:add-to-cart", product);
});
```

Az eseményt csak a követéshez válts ki. Ha a termék már bekerült a WooCommerce-kosárba, akár a saját kódod, akár a szerver oldalán, ne hívd meg emellé a `pmw.addProductToCart()` függvényt is: az másodszor is hozzáadná a Pixel Manager saját kosárállapotához.

## Betöltési sorrend

A figyelőidet azelőtt kell csatolnod, hogy a Pixel Manager elsüti az eseményeit, és a kódod nem futhat előbb, mint hogy a `pmw` létezik. Mindkettőt megoldja a [parancssor](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-command-queue/):

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    pmw.bus.on("pmw:event:add-to-cart", function (payload) {
        // a te kódod
    });
});
```

Ez akkor is működik, amikor a Pixel Manager betöltődik, ami számít azokon a boltokon, amelyek késleltetik vagy lustán töltik a JavaScriptet. A parancssor az újabb változatokon belépő esemény kiváltására is biztonságos hely: a sor garantálja, hogy a `pmw` létezik, a Pixel Manager pedig visszatartja az eseményt, amíg a figyelői és a pixelei élesek nem lesznek.

## Életciklus-események

A követési események mellett a Pixel Manager néhány eseményt a saját állapotáról is kiküld. Ebben a sorrendben sülnek el:

| Esemény | Mikor sül el |
|---|---|
| `pmw:load-pixels` | az összes aktív pixel betöltődött, és mindjárt inicializálódik |
| `pmwLoad` | a Pixel Manager betöltődött, és a `pmw` elérhető |
| `pmw:ready` | az oldal betöltődött, és a Pixel Manager teljesen működőképes |

Ez a három a `document` elemen kiváltott natív böngészőesemény, ezért az `addEventListener` megfogja őket, és az eseménybuszon is rajta vannak:

```js
document.addEventListener("pmwLoad", function () {
    // a Pixel Manager betöltődött
});
```

```js
pmw.bus.on("pmwLoad", function () {
    // a Pixel Manager betöltődött
});
```

> **Az életciklus-eseményekhez ne használj jQuery-t.** A jQuery `.on()` ezeket is megfogja, mert a `document` elemen váltódnak ki, de ne támaszkodj rá. A régebbi változatok némelyikén az életciklus-eseményre kötött jQuery-kezelő oldalbetöltésenként kétszer futott, és ha olyan Pixel Manager függvényt hívott, amely eseményt vált ki, végtelen ciklusba küldhette az oldalt, amely `RangeError: Maximum call stack size exceeded` hibával végződik. Az `addEventListener` és a `pmw.bus.on()` egyik változaton sem volt érintett.

> **Egyszeri és adat nélküli.** Az életciklus-események nem hordoznak adatcsomagot, és nem játszódnak vissza. Az az eseménykezelő, amelyet az elsülésük után regisztrálsz, soha nem fut le, és semmi nem naplózódik. Ezért rossz kapu mindenhez, amit nem szabad elmulasztani. A klasszikus hiba: egy beágyazott lábrész-kódrészlet megnézi, készen áll-e a Pixel Manager, nem találja késznek, és visszaesik a `pmw:ready` várására. Azon a boltban, amely késlelteti a JavaScriptet, a Pixel Manager csomagja a beágyazott szkript után fut le, így a tartalék regisztráció minden egyes alkalommal túl későn jön. Ez nem olyan versenyhelyzet, amely néha működik. Futtasd a kódodat a parancssorból, és a konverziódat a `pmw.bus.on("pmw:event:purchase", …)` kezelőre akaszd. Mindkettő ellenáll a betöltési sorrendnek.

Saját kódodnál a parancssort részesítsd előnyben a `pmwLoad` helyett. A sor akkor is lefuttatja a függvényedet, ha a Pixel Manager a szkripted előtt töltődött be, a `pmwLoad` viszont nem, mert addigra már elsült.

## Hibakeresés

Kapcsold be a [konzolnaplózót](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-konzolnaplozo/) úgy, hogy bármelyik oldalt a `?pmwloggeron` paraméterrel töltöd be. Minden eseményről kiír egy sort, amely belép a feldolgozásba és kilép belőle, így azonnal látod, megérkezett-e a kiváltott eseményed:

```text
Pixel Manager: pmw:add-to-cart event fired
Pixel Manager: Processing event: add_to_cart
Pixel Manager: Public event dispatched: pmw:event:add-to-cart
```

Ha az eseményed az indulás alatt érkezett, először azt látod, hogy visszatartotta, majd a kézbesítést, amikor a Pixel Manager készen áll:

```text
Pixel Manager: pmw:add-to-cart arrived while the library was still loading, held until it is ready
Pixel Manager: delivering 1 entry event(s) that arrived while the library was still loading
Pixel Manager: pmw:add-to-cart event fired
```

Ha egyik sor sem jelenik meg, az esemény nem jutott el a Pixel Managerhez: ellenőrizd az eseménynevet, és jQuery-s formánál azt, hogy a jQuery ott betöltődött-e.

Kikapcsolás a `?pmwloggeroff` paraméterrel.

## Stabilitás

Az ezen az oldalon leírt eseménynevek és adatcsomag-szerkezet nyilvános API, és stabilan marad. Két megjegyzés:

- Léteznek belső `pmw:pixel:*` és `pmw:s2s:*` események is. Ezek a feldolgozási lánc és az egyes pixelek közötti vezetékezés, ne építs rájuk, mert a pixelek megvalósításával együtt változnak.
- Az adatcsomagba új kulcsok kerülhetnek. A szükséges kulcsokat olvasd ki, és ne feltételezz rögzített alakot.