Recept: külső konverziós címke beépítése

Ez a recept megmutatja, hogyan jelentheted a Pixel Manager vásárlási eseményét olyan külső címkének, amelyet a bővítmény natívan nem támogat: például partnerhálózatnak (affiliate), partnerplatformnak vagy saját fejlesztésű követőnek.

A példa az Adtraction hálózatot használja, de a minta minden hálózatnál ugyanaz. Csak a címke saját szkript-URL-je és a paraméterei változnak.

A minta

Három szabály viszi az egész integrációt, minden más a hálózat saját API-ja.

1. A vásárlási figyelőt szinkron regisztráld. A vásárlási esemény rendelésenként pontosan egyszer sül el, utána véglegesen zárolódik, az oldal újratöltése sem ismétli. A pmw.bus.on() hívással regisztrált figyelő az újabb változatokon a késői regisztrációnál is megkapja a rendelést, mert az esemény visszajátszódik. Ennek ellenére regisztrálj elsőként: a visszajátszás a jQuery(document).on() esetén nem létezik, és régebbi változatokon sincs.
2. A külső szkriptet a kezelőn belül töltsd be. Ne előtte. A szkriptre csak akkor van szükség, ha van jelentendő konverzió.
3. A hozzájárulást a kezelőn belül ellenőrizd. A látogató hozzájárulási állapota a parancssor számára is elérhető, de a kezelőn belüli olvasás a döntést a konverzió mellett tartja, és akkor is helyes, ha a hozzájárulás az oldal betöltése után érkezik meg.
4. A kódrészletet minden oldalon írd ki. wp_head oldalfeltétel nélkül, ahogy lent. A vásárlási esemény a kapu, és a megerősítő oldalon kívül is elsülhet: az Automatic Conversion Recovery (Pro) a vásárló következő látogatásakor bármelyik bolti oldalon újra lejátssza az elmaradt rendelést. A csak a megerősítő oldalra kitett kódrészlet minden rendelést jelent, kivéve a visszaszerzetteket.

Miért számít ennyire a sorrend? Ha az integrációd kattintást vagy oldalmegtekintést jelent, de eladást soha, szinte biztosan ez az ok. Lásd a Command queue „Hiányzó vásárlási konverziók” részét.

A recept az eseménybuszt (pmw.bus) használja, és a hozzájárulási állapotot az esemény adatcsomagjából olvassa, ami minden változaton működik. A régebbi változatokon cseréld a pmw.bus.on('pmw:event:purchase', function (payload) { ... }) hívást erre: jQuery(document).on('pmw:event:purchase', function (event, payload) { ... }). Minden más ugyanaz marad. Régebbi változatokon ne olvasd a pmw.consent értéket a sorba tett parancs legfelső szintjén: a hozzájárulási modul akkor még nem töltődött be, a parancs csendben hibázott, és a figyelő sosem regisztrálódott. Az adatcsomagból olvasott hozzájárulás ezt minden változaton elkerüli.

A kód

Add hozzá a gyermektéma functions.php fájljához vagy egy kis egyedi bővítményhez.

add_action('wp_head', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            const programId         = 1234567890;   // a hálózat által adott program-azonosító
            const transactionTypeId = 9876543210;   // a hálózat által adott tranzakciótípus

            // 1. szabály: a figyelő szinkron regisztrálódik
            pmw.bus.on('pmw:event:purchase', function (payload) {

                // 3. szabály: a hozzájárulás ellenőrzése a kezelőben
                if (!payload.context.consent.categories.marketing) return;

                const order = pmwDataLayer.order;
                if (!order) return;

                // 2. szabály: a külső szkriptet a kezelőn belül töltjük be
                pmw.loadScriptAndCacheIt(
                    'https://gtm.adt313.net/jsTag?ap=' + programId
                ).then(function () {
                    if (typeof ADT === 'undefined' || !ADT.Tag) {
                        console.error('[Adtraction] A szkript betöltődött, de az ADT.Tag nem elérhető.');
                        return;
                    }
                    ADT.Tag.t   = 3;                                // a hálózat saját mezői
                    ADT.Tag.tp  = transactionTypeId;
                    ADT.Tag.ti  = order.number;                     // tranzakcióazonosító
                    ADT.Tag.am  = order.value.marketing;            // a konverzió értéke
                    ADT.Tag.c   = order.currency;
                    ADT.Tag.xd  = order.billing_email_hashed;       // hash-elt e-mail
                    ADT.Tag.cpn = order.coupon || '';
                    ADT.Tag.doEvent();
                });
            });
        });
    </script>
    <?php
});

A rendelés adatai

A vásárlási adatcsomag és a pmwDataLayer.order mindent megad, amit egy konverziós címke általában kér:

Mező	Tartalom
order.number	a rendelés száma úgy, ahogy a vásárló látja: ez kerül a hálózat tranzakcióazonosítójába
order.id	a WooCommerce belső rendelésazonosítója
order.value.marketing	a konverzió értéke, a bolt beállított marketingérték-logikáját követve
order.currency	a rendelés pénznemének kódja
order.coupon	a felhasznált kuponkódok vesszővel elválasztva, üres, ha nem volt
order.billing_email_hashed	a számlázási e-mail-cím kisbetűsítve, szóköz nélkül, SHA-256-tal hash-elve
payload.context.consent.categories	a látogató hozzájárulási állapota az esemény pillanatában

A rendelés összege helyett az order.value.marketing értéket használd, hogy a hálózatnak jelentett érték ugyanazt a logikát kövesse, mint az összes többi platformnak jelentett.

Ha a külső címke a gtag: ha a kiváltott címke saját Google Ads konverzió, a gtag() közvetlen hívása helyett használd a pmw.trackCustomGoogleAdsConversion() függvényt (lásd: Tippek és trükkök). Ez a két védelmet alkalmazza, amelyet a Pixel Manager a saját Google Ads konverzióira: a pmw.googleConfigConditionsMet({type: 'marketing'}) ellenőrzést a hozzájáruláshoz, és a várakozást a Google-címke betöltésére. Régebbi változatokon mindkettőt kézzel kell megírni. Azokon a boltokon, amelyek késleltetik a JavaScriptet, a gtag még nem létezik, amikor az adatréteg már az oldalon van, ezért az a kódrészlet, amely feltételezi, hogy ott van, egyáltalán nem sül el.

Ellenőrizd a paraméterneveket a hálózattal. A fenti mezőnevek a Pixel Manager mezőnevei. Az ADT.Tag.* nevek, a tranzakciótípus-azonosítók és a programazonosítók a hálózat sajátjai, és ő dokumentálja őket. Ellenőrizd őket a hálózat dokumentációjában és a fiókodban.

Tesztelés

Adj le egy tesztrendelést, és a rendelés-megerősítő oldalon nézd meg a böngészőkonzolban a következőket.

1. Az oldal megerősítő oldalnak van felismerve, és a rendelés jelen van: pmwDataLayer.shop.page_type; pmwDataLayer.order;
2. A kezelőd lefut. Írj egy console.log sort a vásárlási kezelő legelejére, és ellenőrizd, hogy megjelenik.
3. Egyetlen sorba tett parancs sem hibázott. Keresd a konzolban a Pixel Manager: Error executing queued command üzenetet. Ha ott van, a parancsod hibát dobott, és a hibás sor utáni rész kimaradt.
4. A konverzió tényleg elhagyja a böngészőt. A Hálózat (Network) fülön erősítsd meg a kérést a hálózat végpontjára, miután a kezelőd lefutott.

A konzolnaplózó a Pixel Manager saját eseményfolyamát mutatja a te kimeneted mellett. A ?pmwloggeron paraméterrel kapcsolhatod be.

Mivel a vásárlást rendelésenként csak egyszer követi a bővítmény, a megerősítő oldal újratöltése nem váltja ki újra az eseményt. Ismételt teszteléshez ugyanazzal a rendeléssel fűzd a ?nodedupe paramétert a megerősítő oldal URL-jéhez.

Kapcsolódó fejezetek: Command queue, JavaScript-események, Consent API.