# Command queue

> A Pixel Manager parancssora (window._pmwq): biztonságos kódfuttatás a betöltési sorrendtől függetlenül, szűrők, események, hibaelhárítás.

A Pixel Manager parancssora (command queue) egy aszinkron API. Segítségével biztonságosan futtathatsz kódot és használhatod a Pixel Manager függvényeit akkor is, ha nem tudod, mikor töltődik be a Pixel Manager szkriptje.

## Miért érdemes használni?

Sok bolt optimalizálási technikákat használ: szkripthalasztást, lusta betöltést, JavaScript-csomagolókat. Ezek késleltetik a szkriptek betöltését, így a saját kódod megpróbálhat olyan Pixel Manager függvényt elérni, amely még nem létezik, és hibát kap. A parancssor ezt oldja meg:

- **Biztos végrehajtás:** a parancsok mindenképp lefutnak, akár már be van töltve a Pixel Manager, akár később töltődik be.
- **Sorrend:** a parancsok abban a sorrendben futnak, ahogy a sorba tetted őket.
- **Nincs „undefined” hiba:** nem érsz el olyan függvényt, amely még nem létezik.
- **Nem blokkol:** aszinkron fut, nem akasztja meg az oldal megjelenítését.

## Hogyan működik?

A parancssor egy JavaScript-tömb (`window._pmwq`), amely a lefuttatandó függvényeket tárolja. Amikor függvényt teszel bele:

1. Ha a Pixel Manager már betöltődött, a függvény azonnal lefut.
2. Ha még nem, a függvény eltárolódik, és a betöltés után magától lefut.

## Alapvető használat

Egy parancs:

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    console.log('A Pixel Manager kész!');
});
```

Több parancs, a sorrend: első, második, harmadik.

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () { console.log('Első parancs'); });
window._pmwq.push(function () { console.log('Második parancs'); });
window._pmwq.push(function () { console.log('Harmadik parancs'); });
```

## Gyakori felhasználási esetek

### 1. Eseményszűrők regisztrálása

Az eseményszűrőkkel a hirdetési platformoknak küldött adatokat módosíthatod. A parancssor biztosítja, hogy a szűrők a megfelelő időben regisztrálódjanak:

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    pmw.hooks.addFilter('pmw_event_payload_purchase', 'my-custom-filter', function (payload) {
        payload.event_data.value = payload.event_data.value * 1.1;
        return payload;
    });
});
```

A szűrők neveiről és a kapott adatokról az [Eseményszűrők](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-esemenyszurok/) fejezetben olvashatsz.

### 2. A Pixel Manager függvényeinek elérése

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    pmw.trackCustomFacebookEvent('CustomEvent', {
        custom_param: 'value',
        another_param: 123
    });
});
```

### 3. A Pixel Manager eseményeinek figyelése

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    jQuery(document).on('pmw:add-to-cart', function (event, product) {
        console.log('Kosárba tett termék:', product.name);
        dataLayer.push({
            event: 'custom_add_to_cart',
            product_name: product.name,
            product_price: product.price
        });
    });
});
```

### 4. Feltételes követés

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    if (pmwDataLayer.user && pmwDataLayer.user.role === 'customer') {
        pmw.hooks.addFilter('pmw_event_payload_pre', 'customer-only', function (payload) {
            payload.event_data.custom_property = 'customer_value';
            return payload;
        });
    }
});
```

## Használat WordPressben (PHP)

A parancssori kódot a téma `functions.php` fájljából vagy egyedi bővítményből adhatod hozzá.

### Példa: egyedi eseménykövetés

```php
add_action('wp_footer', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            jQuery('.contact-form-submit').on('click', function () {
                pmw.trackCustomFacebookEvent('ContactFormClick');
            });
        });
    </script>
    <?php
});
```

### Példa: a konverzióérték módosítása

```php
add_action('wp_footer', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            pmw.hooks.addFilter('pmw_event_payload_purchase', 'exclude-shipping', function (payload) {
                if (pmwDataLayer.order) {
                    payload.event_data.value = payload.event_data.value - pmwDataLayer.order.shipping;
                }
                return payload;
            });
        });
    </script>
    <?php
});
```

### Példa: bővített e-kereskedelmi követés

```php
add_action('wp_footer', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            jQuery(document).on('pmw:add-to-cart', function (event, product) {
                dataLayer.push({
                    event: 'enhanced_add_to_cart',
                    ecommerce: {
                        currencyCode: product.currency,
                        add: {
                            products: [{
                                name: product.name,
                                id: product.id,
                                price: product.price,
                                brand: product.brand || '',
                                category: product.category || '',
                                quantity: product.quantity || 1
                            }]
                        }
                    }
                });
            });
        });
    </script>
    <?php
});
```

## Mikor fut le a parancsod?

A sorba tett parancsok a Pixel Manager indulásának egy meghatározott pontján futnak le:

1. A Pixel Manager betöltődik, és beolvassa az adatréteget.
2. Betöltődik a hozzájárulási modul, és megállapítja a látogató hozzájárulási állapotát.
3. Lefutnak a sorba tett parancsok.
4. Regisztrálódnak az eseményfigyelők, és betöltődnek a pixelek.
5. Elsülnek az első események.

Ebből két következmény adódik:

- A hozzájárulási állapot már elérhető: a parancs legfelső szintjén olvashatod a `pmw.consent` értékét, és hívhatod a [Consent API](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/hozzajarulas-api/)-t.
- Még semmi nem sült el: a regisztrált szűrők és eseményfigyelők az első esemény előtt a helyükön vannak, és éppen ezért érdemes a parancssort használni.

### Esemény jelentése sorba tett parancsból

A 3. lépés a 4. előtt van. Ez akkor számít, ha a parancsod nem csak figyel, hanem eseményt is jelent a Pixel Managernek, például `pmw:add-to-cart` eseményt egyedi kosárba tétel gombhoz, vagy `pmw:add-shipping-info` eseményt olyan pénztárhoz, amelyet a Pixel Manager nem tud kiolvasni. Ekkor a Pixel Manager még nem hallgatja a saját belépő eseményeit.

A sorba tett parancsból küldött belépő eseményt a bővítmény visszatartja, és feldolgozza, amint a figyelők és a pixelek élesek. A parancssor tehát a megfelelő hely erre:

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    pmw.bus.emit('pmw:add-to-cart', pmw.getProductDetailsFormattedForEvent(productId, 1));
});
```

A régebbi változatokban az ilyen eseményt csendben eldobta a bővítmény: nem volt naplósor, pixel és hibaüzenet sem. Ott az eseményt a `pmwLoad` figyelőből kellett küldeni, amely már a belépő figyelők létrejötte után fut:

```js
window._pmwq.push(function () {
    document.addEventListener('pmwLoad', function () {
        jQuery(document).trigger('pmw:add-to-cart', pmw.getProductDetailsFormattedForEvent(productId, 1));
    });
});
```

Ez csak az események jelentésére vonatkozik. A figyelők és szűrők regisztrálása, ami a parancsok többsége, mindig is a parancssorba tartozott.

### A hozzájárulási állapot régebbi változatokban

A régebbi változatokban a 2. és 3. lépés fordított sorrendben követte egymást: a sorba tett parancsok a hozzájárulási modul betöltése előtt futottak, a `pmw.consent` még nem létezett. Ha a parancs legfelső szintjén olvastad, hiba keletkezett, és mivel a parancsok try/catch blokkban futnak, a hiba csendes maradt, a hozzájárulás-ellenőrzés utáni sorok kimaradtak, tipikusan a saját eseményfigyelőid regisztrálása is. Ha régebbi változatot is támogatnod kell, a hozzájárulás ellenőrzését az eseménykezelőn belül végezd:

```js
window._pmwq.push(function () {
    jQuery(document).on('pmw:event:purchase', function (event, payload) {
        if (!payload.context.consent.categories.marketing) return;
        // saját kód
    });
});
```

### Az eseményfigyelőket szinkron regisztráld

A figyelőt azonnal, a parancson belül regisztráld, ne `await` után és ne `.then()` visszahívásban. Ha a parancs előbb vár valamire, például egy saját külső szkript betöltésére, a Pixel Manager eseményei még azelőtt elsülhetnek, hogy a figyelőd létezne.

Ez a vásárlási eseménynél a legfontosabb: rendelésenként pontosan egyszer sül el, utána véglegesen zárolódik (újratöltéssel sem ismétlődik). Aki túl későn regisztrálja a vásárlási figyelőjét, elveszíti a konverziót, és nincs második esély.

Helyes: a figyelő azonnal regisztrálódik, a külső szkript betöltése a kezelőn belül történik.

```js
window._pmwq.push(function () {
    pmw.bus.on('pmw:event:purchase', function (payload) {
        pmw.loadScriptAndCacheIt('https://example.com/tag.js').then(function () {
            // a külső címke használata
        });
    });
});
```

Hibás: a figyelő csak a szkript betöltése után regisztrálódik.

```js
window._pmwq.push(function () {
    pmw.loadScriptAndCacheIt('https://example.com/tag.js').then(function () {
        pmw.bus.on('pmw:event:purchase', function (payload) {
            // ez túl későn regisztrálódhat
        });
    });
});
```

A `pmw.bus.on()` az újabb változatokban azt a vásárlási figyelőt is kiszolgálja, amely az esemény elsülése után regisztrál, így a hibás forma is működhet. A szinkron regisztráció ettől függetlenül az ajánlott minta, mert csak ez biztonságos a `jQuery(document).on()` esetén is, és régebbi változatokon is csak ez működik. A régebbi változatokon a `pmw.bus` helyett használd a `jQuery(document).on('pmw:event:purchase', function (event, payload) { ... })` alakot, amely minden változaton működik.

### A hibákat elkapja és naplózza, nem dobja tovább

Minden sorba tett parancs try/catch blokkban fut, így egy hibás parancs nem állíthatja meg a Pixel Managert vagy a többi parancsot. Az ára az, hogy a hiba csendes: a böngészőkonzolba kerül, és a parancs hibás sora utáni rész kimarad. Ha az integrációd egy része rejtélyes módon nem csinál semmit, keresd a böngészőkonzolban ezt:

```text
Pixel Manager: Error executing queued command
```

Az üzenet tartalmazza a parancs forrásának elejét, így megtudhatod, melyik kódrészlet hibázott.

## Elérhető Pixel Manager függvények

A parancssoron belül a Pixel Manager API-ja is elérhető, a hozzájárulási állapottal együtt.

### Eseménykövető függvények

```js
pmw.trackCustomFacebookEvent(eventName, customData);
pmw.console.log(message, data);
```

### Szűrők és hookok

```js
pmw.hooks.addFilter(hookName, namespace, callback, priority);
pmw.hooks.addAction(hookName, namespace, callback, priority);
pmw.hooks.removeFilter(hookName, namespace);
pmw.hooks.removeAction(hookName, namespace);
```

### Hozzájárulási állapot

```js
pmw.consent.categories.get();
pmw.consent.api.acceptAll();
```

A teljes leírás a [Consent API](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/hozzajarulas-api/) fejezetben van.

### Adatok elérése

```js
console.log(pmwDataLayer);
if (pmwDataLayer.shop) {
    console.log('Pénznem:', pmwDataLayer.shop.currency);
}
if (pmwDataLayer.order) {
    console.log('Rendelésazonosító:', pmwDataLayer.order.id);
}
```

## Eseménylista

### Nyilvános API-események (ajánlott)

A `pmw:event:*` névtér a harmadik felek integrációinak hivatalos nyilvános API-ja. Ezek az események a teljesen feldolgozott adatcsomagot adják, az összes pixelspecifikus adattal és a hozzájárulási állapottal. Figyeld ezeket, ha teljes, feldolgozott adatot akarsz kapni:

- `pmw:event:page-view`: oldalmegtekintés teljes környezettel
- `pmw:event:view-item`: termékoldal megtekintése
- `pmw:event:view-item-list`: terméklista vagy kategória megtekintése
- `pmw:event:select-item`: termékre kattintás
- `pmw:event:add-to-cart`: termék kosárba tétele
- `pmw:event:remove-from-cart`: termék eltávolítása a kosárból
- `pmw:event:view-cart`: kosároldal megtekintése
- `pmw:event:begin-checkout`: pénztár megkezdése
- `pmw:event:add-payment-info`: fizetési mód kiválasztása
- `pmw:event:add-shipping-info`: szállítási mód kiválasztása
- `pmw:event:purchase`: a rendelés befejezése
- `pmw:event:add-to-wishlist`: termék kívánságlistára tétele
- `pmw:event:search`: keresés
- `pmw:event:account-created`: új fiók létrehozása

Példa:

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    jQuery(document).on('pmw:event:add-to-cart', function (event, payload) {
        console.log('Kosárba tétel esemény:', payload);
        console.log('Esemény neve:', payload.event);
        console.log('Termékadatok:', payload.event_data);
        console.log('Pixelspecifikus adatok:', payload.pixels);
    });
});
```

### Belépő események

Ezeket az eseményeket te küldöd a Pixel Managernek, ha valami olyasmit kell jelentened, amit a bővítmény magától nem érzékel. A bővítmény saját figyelői is ezeket használják belül, ezért a figyelésükkel a feldolgozás előtti, nyers interakciót látod:

- `pmw:page-view`: oldalmegtekintés
- `pmw:view-item`: termékoldal megtekintése
- `pmw:view-category`: kategóriaoldal megtekintése
- `pmw:search`: keresés
- `pmw:add-to-cart`: termék kosárba tétele
- `pmw:remove-from-cart`: termék eltávolítása a kosárból
- `pmw:select-item`: termékre kattintás
- `pmw:add-to-wishlist`: termék kívánságlistára tétele
- `pmw:begin-checkout`: pénztár megkezdése
- `pmw:add-payment-info`: fizetési mód kiválasztása
- `pmw:place-order`: a rendelés leadásának kezdete
- `pmw:purchase`: a rendelés befejezése
- `pmw:login`: bejelentkezés
- `pmw:account-created`: új fiók létrehozása

A két eseménytípus különbsége:

- A `pmw:event:*` események a teljesen feldolgozott adatcsomagot tartalmazzák, az összes pixelhez igazítással és a kiváltási döntésekkel.
- A `pmw:*` események belépési pont események, a feldolgozás előtti nyers eseményadattal.

Figyeléshez a `pmw:event:*` az ajánlott, mert teljes információt hordoz. Egy interakció jelentéséhez a `pmw:*` belépő eseményt használd. A részleteket a [JavaScript-események](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-javascript-esemenyek/) fejezet tartalmazza.

## Hibaelhárítás

### A parancs nem fut le

A parancs nem látszik lefutni. Kapcsold be a [konzolnaplózót](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-konzolnaplozo/), és ellenőrizd, mikor töltődik be a Pixel Manager. Egy egyszerű teszt a parancs lefutásának megerősítésére:

```js
window._pmwq = window._pmwq || [];
window._pmwq.push(function () {
    console.log('Ez az üzenet igazolja, hogy a parancs lefutott');
});
```

### A parancs félúton megáll

A parancs eleje biztosan lefut, a többi nem csinál semmit. Jellemzően az eseményfigyelőd soha nem hívódik meg, vagy az integrációd nem jelent konverziót, miközben az oldalon minden más működik.

A parancsod hibát dobott, amelyet a parancssor elkapott és naplózott. Nyisd meg a böngészőkonzolt az érintett oldalon, és keresd a `Pixel Manager: Error executing queued command` üzenetet. Az üzenet megnevezi a hibát, és megmutatja a parancs elejét. A hibás sor utáni rész kimaradt.

Tipikus okok: elgépelt Pixel Manager függvénynév, vagy olyan változóra hivatkozás, amely az adott oldaltípuson még nem létezik. Például a `pmwDataLayer.order` olvasása a rendelés-megerősítő oldalon kívül.

### Hiányzó vásárlási konverziók

Az integrációd oldalmegtekintést vagy kattintást jelent, de eladást soha. Ellenőrizd, hogy a vásárlási figyelőt szinkron regisztrálod a parancson belül, nem `await`, `.then()` vagy más várakozás után. Hogy az esemény egyáltalán eljut-e a kódodhoz, egy csak naplózó figyelővel ellenőrizheted:

```js
window._pmwq.push(function () {
    pmw.bus.on('pmw:event:purchase', function (payload) {
        console.log('purchase érkezett', payload);
    });
});
```

### „Function not found”

Hiba: `pmw.someFunction is not a function`. Ellenőrizd, hogy olyan függvényt hívsz-e, amely létezik a Pixel Manager API-jában. A használható függvények és szűrők az [Eseményszűrők](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-esemenyszurok/) fejezetben vannak.

## Ajánlott gyakorlatok

1. Mindig előbb hozd létre a sort: `window._pmwq = window._pmwq || [];`
2. A parancsok legyenek célzottak: egy parancs egy dolgot csináljon.
3. A szűrőknek értelmes névteret adj, például `pmw.hooks.addFilter('pmw_event_payload_purchase', 'my-shop-exclude-shipping', callback);`
4. Az eseményfigyelőket szinkron regisztráld, soha ne `await` vagy `.then()` mögött, különben az esemény előbb elsülhet, mint hogy a figyelő létezne.
5. Kezeld szépen a hibákat: tegyél a parancs kódjába `try { ... } catch (e) { console.error('Hiba:', e); }` blokkot.
6. A teszteléshez kapcsold be a konzolnaplózót a `?pmwloggeron` paraméterrel, így látod, hogy a kódod helyesen fut-e.

Kapcsolódó fejezetek:

- [Külső konverziós címke beépítése](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-receptek-kulso-cimke/): a teljes minta partnerhálózatokhoz és más külső címkékhez.
- [Eseményszűrők](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-esemenyszurok/): a követési adatok módosítása szűrőkkel és hookokkal.
- [Konzolnaplózó](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-konzolnaplozo/): a parancssoros megoldásaid hibakeresése.
- [Tippek és trükkök](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-tippek-es-trukkok/): további kódpéldák és minták.
- [PHP-szűrők](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-php-szurok-ertekek/): a szerveroldali WordPress- és WooCommerce-szűrők.