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

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.

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

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:

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

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

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:

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:

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:

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:

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.

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:

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:

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

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

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:

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.