Command queue

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:

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

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

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:

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 fejezetben olvashatsz.

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

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

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

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

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

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

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-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:

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:

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:

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.

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.

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:

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

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

Szűrők és hookok

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

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

A teljes leírás a Consent API fejezetben van.

Adatok elérése

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:

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 fejezet tartalmazza.

Hibaelhárítás

A parancs nem fut le

A parancs nem látszik lefutni. Kapcsold be a konzolnaplózót, és ellenőrizd, mikor töltődik be a Pixel Manager. Egy egyszerű teszt a parancs lefutásának megerősítésére:

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:

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 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: a teljes minta partnerhálózatokhoz és más külső címkékhez.
• Eseményszűrők: a követési adatok módosítása szűrőkkel és hookokkal.
• Konzolnaplózó: a parancssoros megoldásaid hibakeresése.
• Tippek és trükkök: további kódpéldák és minták.
• PHP-szűrők: a szerveroldali WordPress- és WooCommerce-szűrők.