Recept: státuszvezérelt vásárlási konverziók

Ez a recept a Facebook (és más platformok) vásárlási konverzióját csak akkor rögzíti, ha a WooCommerce megerősíti, hogy a rendelés kifizetett állapotban van, a platform Conversions API-ját használva egyetlen igazságforrásként.

Mikor van szükséged erre a receptre?

A WooCommerce-rendelések a pénztár után három nagy kimenetelre oszlanak:

1. A rendelés azonnal meghiúsul. A vásárló sosem ér el a megköszönő oldalra. Semmi nem sül el, nincs teendő.
2. A rendelés azonnal kifizetett (a legtöbb Stripe- vagy PayPal-szerű integráció). A böngészőpixel a megköszönő oldalon, a CAPI a kifizetett státuszra váltáskor sül el, mindkettő ugyanazt az event_id értéket használja, és a Meta kettőzésmentesíti őket. Ez a normál eset, nincs teendő.
3. A rendelés feldolgozás alatt (processing) állapotba kerül, de még meghiúsulhat vagy sosem fizetik ki (banki átutalás, számla, részletfizetés, kézi ellenőrzés). A böngészőpixel a megköszönő oldalon elsül és rögzíti a konverziót, akkor is, ha a rendelést később lemondják vagy sosem fizetik ki.

Ez a recept a 3. esetre szól.

A Pixel Manager alapértelmezett működése mindent követ, ami nem hiúsul meg azonnal, mert a legtöbb pénztár a 2. esetbe esik, és a kifizetett státuszra várás a gyakori esetben rontja az attribúciót és a Meta optimalizálóját. Csak akkor használd ezt a receptet, ha a 3. eset annyira gyakori a boltodban, hogy torzítja a számokat.

Mi a CAPI, és mi nem

A Conversions API a követés megbízhatóságára készült: az eseményeket a szerverről közvetlenül a Metának küldi, hogy túlélje a hirdetésblokkolókat, a böngészők adatvédelmi szabályait és a böngészőpixelt elnyomó hálózati szűrőket. A szokásos beállításban a CAPI a böngészőpixel mellett tartalékként fut, és a Meta az event_id alapján kettőzésmentesíti a kettőt. Ez a recept a CAPI-t a vásárlási események egyetlen küldőjévé teszi, hogy kihasználja a beépített, státuszvezérelt kiváltóját.

A 7 napos korlát

A Meta Conversions API csak olyan eseményt fogad el, amelynek event_time értéke az elmúlt 7 napon belül van. Ha egy rendelés 7 napnál tovább marad feldolgozás alatt állapotban, mielőtt kifizetett státuszra vált, a konverziója véglegesen elvész. Ez a Meta oldalán kemény korlát.

Hogyan kezeli a Pixel Manager alapból a vásárlási eseményeket

A Facebooknál a Pixel Manager a vásárlási eseményt két helyről sütti el:

1. Böngészőpixel: a rendelés-megerősítő (megköszönő) oldalon sül el, a rendelés fizetési státuszától függetlenül.
2. Conversion API (CAPI): az alább felsorolt rendelési státuszváltásokra regisztrált. A rendelésen egy meta-kulcsos őr megakadályozza a dupla elsülést ezek között a hookok között.

Mindkét esemény ugyanazt az event_id értéket kapja (pmw_{rendelés azonosítója}), a Facebook ezen kettőzésmentesít.

Mely váltások váltják ki a szerveroldali vásárlást

A szerveroldali vásárlási esemény ezekre van regisztrálva:

• woocommerce_payment_complete
• minden woocommerce_order_status_{kifizetett státusz} váltás, ahol a kifizetett státuszokat a wc_get_is_paid_statuses() adja, alapból processing és completed
• woocommerce_order_status_on-hold

A szerveroldali vásárlás státuszvezérelt, de a „státuszvezérelt” nem azonos a „kifizetettel”. Két eset eljut a hirdetési platformokhoz, bár pénz nem érkezett:

• Függőben (on-hold) lévő rendelések. Az on-hold állapotba lépés szándékos kiváltó. Azok a fizetési módok, amelyek a rendelést fizetésre várva parkoltatják (kriptoszámlák, banki átutalás, egyes részletfizetési megoldások), különben napokkal későn jelentenék a konverziókat, a Meta pedig bünteti a késő jelentést. Egy olyan boltban, ahol a legtöbb függő rendelést sosem fizetik ki, ez felfújja a konverziók számát.
• Nulla értékű rendelések. Az ingyenes rendelés (nulla forintos próbaelőfizetés, ingyenes csomag, teljesen kedvezményezett kosár) a payment_complete() függvényen át kifizetett státuszba kerül, ezért mint bármely más rendelés, vásárlást vált ki. Ezen az úton semmi nem vizsgálja a rendelés végösszegét.

A meghiúsult, lemondott és visszatérített rendelések soha nem váltanak ki szerveroldali vásárlást. A pending (függőben lévő fizetés) státuszú rendelések sem, mert arra nem fut hook, de az a rendelés, amely röviden áthaladt az on-hold állapoton, mielőtt a fizetési mód visszaállította, útközben kiváltott egyet.

Ha bármelyik eset érint, a szerveroldali vásárlást kapuzd a lent leírt pmw_skip_s2s_purchase_event szűrővel. A nem kifizetett rendeléseket nem csak a böngészőpixel rögzíti.

A recept

Ha a konverziókat szigorúan akkor akarod rögzíteni, amikor a rendelés kifizetett állapotba ér, két dolgot kell tenned:

1. Kapcsold be a Facebook CAPI-t

A Pixel Managerben nyisd meg a Tracking Pixels → Meta részt, és kapcsold be a Conversions API beállítást. Ez teszi a CAPI-t azzá a forrássá, amely a vásárlási eseményt a Metának eljuttatja.

A Facebook bekapcsolása a Pixel Managerben a Meta for WooCommerce bővítmény követőpixelét is kikapcsolja, ha az telepítve van. A termékkatalógus-szinkront a Meta for WooCommerce-ből ez nem érinti.

2. Nyomd el a Facebook böngészőpixelt a vásárlási eseményeknél

Adj hozzá egy JavaScript-szűrőt, amely a Facebook-pixel purchase eseményeire null értéket ad vissza. A pmw_pixel_data_{pixel} szűrőből visszaadott null megakadályozza, hogy az adott pixel elsüljön az illeszkedő eseményre.

A gyermektéma functions.php fájljába:

add_action('wp_head', function () {
    ?>
    <script>
        window._pmwq = window._pmwq || [];
        window._pmwq.push(function () {
            pmw.hooks.addFilter(
                'pmw_pixel_data_facebook',
                'my-store/status-driven-purchase',
                function (pixelData, eventName) {
                    if (eventName === 'purchase') {
                        return null;
                    }
                    return pixelData;
                }
            );
        });
    </script>
    <?php
}, 1);

Az elnyomott böngészős vásárlási eseménnyel a CAPI az egyetlen küldő, a kettőzésmentesítés megszűnik, és a konverziók akkor jelennek meg a Metában, amikor a WooCommerce a rendelést kifizetett állapotba teszi. A legtöbb fizetési módnál ez gyakorlatilag azonnali. Offline vagy kézzel jóváhagyott fizetésnél a konverzió abban a pillanatban rögzül, amikor a rendelés kifizetett státuszra vált.

Szigorúbb „kifizetett” definíció (szerveroldali szűrő)

Akkor használd, ha a fenti kiváltólista tágabb, mint a te konverziódefiníciód: ki akarod zárni a függő (on-hold) rendeléseket, a nulla értékű rendeléseket, vagy a processing rendeléseket egy olyan boltban, amely csak a completed rendeléseket számolja.

A használandó szűrő a pmw_skip_s2s_purchase_event (lásd: Szerveroldali szűrők). Maga a rendelést kapja, és a true visszaadása minden platformra elnyomja a szerveroldali vásárlást, a SweetCode Cloud proxy útvonalat is, és a rendelést kizárja a Google Ads konverziómódosítási adatforrásból is.

add_filter('pmw_skip_s2s_purchase_event', function ($skip, $order) {
    if (!$order instanceof WC_Order) {
        return $skip;
    }

    // Nulla értékű rendelés ne számítson
    if ((float) $order->get_total() <= 0) {
        return true;
    }

    // Csak kifizetett rendelés számítson
    if (!$order->is_paid()) {
        return true;
    }

    return $skip;
}, 10, 2);

A kihagyott rendelést a bővítmény nem jelöli elküldöttnek, ezért a vásárlás normálisan kimegy abban a pillanatban, amikor a rendelés ténylegesen eléri a kifizetett státuszt. Ettől lesz a szűrő kapu, nem végleges kizárás.

A definíció tovább szűkítéséhez, például csak a completed státuszra, cseréld le az is_paid() ellenőrzést:

if ($order->get_status() !== 'completed') {
    return true;
}

Ha a szabályt csak egy platformra akarod alkalmazni, olvasd a szűrő harmadik argumentumát, amely a pixelosztály nevét hordozza:

use SweetCode\Pixel_Manager\Pixels\Facebook\Facebook_CAPI;

add_filter('pmw_skip_s2s_purchase_event', function ($skip, $order, $context) {
    if ($context !== Facebook_CAPI::class) {
        return $skip;
    }
    return ($order instanceof WC_Order && !$order->is_paid()) ? true : $skip;
}, 10, 3);

Ehhez ne használd a pmw_server_event_payload_{pixel}_purchase szűrőt. Az Eseményszűrők fejezetben leírt pmw_server_event_payload_* szűrők a szerverre továbbított böngészőeseményeken futnak. A láncot tápláló végpont elutasítja a purchase eseményeket, mert a vásárlást mindig a szerveren állítja össze a rendelésből, és sosem fogadja el a böngészőtől. A pmw_server_event_payload_facebook_purchase szűrőre írt visszahívás ezért soha nem fut le, és az arra épített státuszkapu csendben hibázik. Az egyetlen kivétel a Google Analytics 4: a Measurement Protocol a pmw_server_event_payload_google_analytics, pmw_server_event_payload_google_analytics_purchase és pmw_server_event_payload_post szűrőket a saját vásárlási adatcsomagjára alkalmazza, így ez a három GA4-re lefut. Minden más platformra használd a pmw_skip_s2s_purchase_event szűrőt.

A régebbi változatokon a szerveroldali vásárlási út a Pixel Manager belső rendelésobjektumát adta át ennek a szűrőnek a WC_Order helyett, ezért a fenti instanceof WC_Order őr csendben kihagyta az egész visszahívást. Frissíts egy újabb változatra, ahol a szűrő ismét a WooCommerce-rendelést kapja. Ha régebbi változatot is támogatnod kell, előbb old fel az argumentumot: $order = wc_get_order(is_object($order) ? $order->get_id() : $order);.

Egyedi rendelési státuszok (például partially-paid)

A foglaló- és részfizetési bővítmények egyedi rendelési státuszokat adnak hozzá, amelyeket a WooCommerce nem kezel kifizetettként. Mivel a vásárlási konverzió a kifizetett státuszba lépéskor sül el, az a rendelés, amely csak egy egyedi státuszba (például partially-paid) jut el, soha nem vált ki vásárlási konverziókövetést.

Egyedi rendelési státusz kifizetettként való regisztrálására használd a WooCommerce woocommerce_order_is_paid_statuses szűrőjét. Ez a wc_get_is_paid_statuses() mögötti szűrő, ezért a Pixel Manager automatikusan felveszi, és elsüti a vásárlási konverziót, amikor a rendelés ebbe a státuszba lép:

add_filter('woocommerce_order_is_paid_statuses', function ($statuses) {
    $statuses[] = 'partially-paid';
    return $statuses;
});

Ehhez nincs külön Pixel Manager-szűrő: a WooCommerce szűrője az egyetlen igazságforrás. Vedd figyelembe, hogy ez kiszélesíti azt, amit maga a WooCommerce kifizetettnek tekint (például az $order->is_paid() eredményét), nem csak a Pixel Manager konverziókiváltóját.

Nem kötelező: a CAPI kézi újraküldése egy rendelésre

Ha egy egyedi munkafolyamatnak egy adott rendelésre CAPI vásárlási eseményt kell küldenie (például egy egyedi hookból), hívd meg a platform statikus send_purchase_hit() metódusát a rendelésobjektummal:

\SweetCode\Pixel_Manager\Pixels\Facebook\Facebook_CAPI::send_purchase_hit($order);

Ez belső metódus, és nem része a Pixel Manager nyilvános API-jának. Kiadások között változhat.

Ugyanez a minta más platformokra

Ugyanez a megközelítés minden olyan platformra működik, amelynek van szerveroldali megfelelője a Pixel Managerben. Csak a JavaScript-szűrő neve változik platformonként, mert a szerveroldali kapu mindegyiknél ugyanaz az egy szűrő.

Platform	JavaScript-szűrő	Szerveroldali kapu
Facebook / Meta	pmw_pixel_data_facebook	pmw_skip_s2s_purchase_event, a $context értéke Facebook_CAPI::class
TikTok	pmw_pixel_data_tiktok	pmw_skip_s2s_purchase_event, a $context értéke TikTok_EAPI::class
Pinterest	pmw_pixel_data_pinterest	pmw_skip_s2s_purchase_event, a $context értéke Pinterest_APIC::class
Snapchat	pmw_pixel_data_snapchat	pmw_skip_s2s_purchase_event, a $context értéke Snapchat_CAPI::class
Reddit	pmw_pixel_data_reddit	pmw_skip_s2s_purchase_event, a $context értéke Reddit_CAPI::class
Google Analytics 4	pmw_pixel_data_google_analytics	pmw_skip_s2s_purchase_event, a $context értéke Google_MP_GA4::class

A Microsoft Advertising, a Nextdoor, a Mixpanel, az OpenAI és a többi szerveroldali platform ugyanezzel a szűrővel kapuzható, a pixelosztályaik a SweetCode\Pixel_Manager\Pixels\{Platform} névtérben vannak. Ha kihagyod a $context ellenőrzést, az összes platformot egyszerre kapuzod, ahogy a fenti példa is teszi.

A Google Analytics 4 emellett kínálja a pmw_server_event_payload_google_analytics_purchase szűrőt a Measurement Protocol adatcsomag módosítására. Ezt arra használd, hogy megváltoztasd, mi megy ki, nem arra, hogy eldöntsd, kimegy-e egyáltalán: a kihagyó szűrő korábban fut, és olcsóbb kapu, mert a kihagyott rendeléshez sosem épül adatcsomag.

Platformok szerveroldali megfelelő nélkül (Google Ads és mások)

Ez a recept azon alapul, hogy a platformnak van szerveroldali vásárlási API-ja a Pixel Managerben, mert az adja a státuszvezérelt kiváltót. A Google Adsnek nincs, és a LinkedInnek, az X-nek, a Taboolának, az Outbrainnek, az AdRollnak, a Criteónak és a többi, csak böngészős pixelnek sincs. Ezeknél a vásárlási konverzió a böngészőből megy, ezért a böngészős esemény elnyomása szerveroldali küldő nélkül teljesen eldobja a konverziót.

A Microsoft Advertising korábban ezen a listán volt. A Pro változatban már van Conversions API-ja, ezért a fenti receptet követi.

Ezekhez használd a pmw_conversion_prevention PHP-szűrőt (lásd: Szerveroldali szűrők). Egy adott rendelésnél visszatartja a böngészős vásárlási konverziót, amíg a rendelés nem kifizetett státuszú, és mivel a szűrőt az Automatic Conversion Recovery (Pro) újra kiértékeli, a konverzió teljes egészében visszaszerződik a vásárló következő látogatásakor, miután a rendelést kifizették.

Két különbséget érdemes tudnod a CAPI-alapú recepthez képest, mielőtt ezt választod:

• Az érintett rendeléseknél minden böngészős vásárlási pixelt elnyom, nem csak egy platformot, mert a rendelés adatait az adatrétegből teljes egészében visszatartja.
• A helyreállításhoz a vásárlónak ugyanazzal a böngészővel vissza kell térnie a boltba. A CAPI-nak nincs szüksége visszatérő látogatásra.

Ha a beállításodban egy platformnak van Conversion API-ja, azon a platformon ezt a receptet részesítsd előnyben, a szűrőt pedig csak a csak böngészős pixelekre használd.

Hibaelhárítás

• A konverziók még mindig megjelennek a meghiúsult rendeléseknél. A böngészőpixel-szűrő nincs aktív. Ellenőrizd, hogy a kódrészlet kikerül az oldal forrására, és hogy a pmw.hooks definiált, amikor lefut (ezt garantálja a _pmwq parancssor).
• Egyáltalán nem jelennek meg konverziók. Ellenőrizd, hogy a Facebook CAPI be van-e kapcsolva a Pixel Managerben a Tracking Pixels → Meta alatt, és hogy a hozzáférési token érvényes-e. A CAPI-kérést a Pixel Manager Support → Logger részén kapcsolt naplókban keresd.
• A konverziók később jelennek meg, mint vártad. Ez a várt működés. A CAPI akkor sül el, amikor a WooCommerce a rendelést kifizetett státuszba teszi, nem amikor a vásárló a megköszönő oldalra ér.
• A böngészőpixel elnyomása után is megjelennek konverziók függő (on-hold), nem kifizetett vagy ingyenes rendeléseknél. Ezek a szerveroldali eseményből jönnek, amely az on-hold állapotba lépéskor is elsül, és nem ellenőrzi a rendelés végösszegét. Add hozzá a pmw_skip_s2s_purchase_event kaput. Ha már hozzáadtad, és semmi nem változott, ellenőrizd két dolgot: hogy a visszahívásod a pmw_skip_s2s_purchase_event szűrőre van-e regisztrálva, és nem a pmw_server_event_payload_{pixel}_purchase szűrőre, amely vásárlásra soha nem fut le, valamint hogy a bővítményed elég friss-e, mert a régebbi változatok rossz objektumot adtak át a visszahívásnak.
• Több vásárlási esemény van, mint kifizetett rendelés a platform eseménykezelőjében. Hasonlítsd össze a mögöttük álló rendelésazonosítókat. Az eseményazonosító pmw_{rendelés azonosítója}, így egy szúrópróba a rendelés státuszelőzményével általában kimutat egy függő (on-hold) váltást, egy ingyenes rendelést vagy egy olyan rendelést, amely röviden áthaladt az on-hold állapoton, mielőtt a fizetési mód visszaállította pending állapotra.

Kapcsolódó fejezetek: Eseményszűrők, PHP-szűrők.