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

> A Pixel Manager vásárlási eseményének továbbítása olyan külső címkének, amelyet a bővítmény natívan nem támogat (partnerhálózat, egyedi követő).

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](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/funkciok-acr/) (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](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-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.

```php
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](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/elso-lepesek-bolt-beallitasok/) 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](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-tippek-es-trukkok/)). 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ó](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-konzolnaplozo/) 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](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-command-queue/), [JavaScript-események](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/fejlesztoknek-javascript-esemenyek/), [Consent API](https://hub.hellowp.io/hu/plugins/woocommerce-pixel-manager/hozzajarulas-api/).