File manager - Edit - /home/verseaumee/colorkeysstudio/wp-content/plugins/reddit-for-woocommerce/includes/Tracking/ConversionTrackerInterface.php
Back
<?php /** * Interface definition for Ad Partner Conversion API tracking implementations. * * This interface defines a contract for classes that send server-side tracking events * (such as Add to Cart or Purchase) to an Ad Partner’s Conversions API endpoint. * * These events are commonly used to enable better attribution, reporting, and optimization * for ad campaigns that run on platforms like Reddit, Meta, TikTok, or others. * * @package RedditForWooCommerce\Tracking */ namespace RedditForWooCommerce\Tracking; use WC_Cart; /** * Interface for sending server-side conversion events to an Ad Partner API. * * Implementers of this interface are responsible for preparing and dispatching * conversion payloads that correspond to WooCommerce user actions — such as * product additions to cart or completed purchases. * * These events are typically sent through an API endpoint provided by the Ad Partner, * and may be transmitted immediately or via background job processors such as Action Scheduler. * * A matching client-side event (e.g. tracking pixel) is often sent in parallel to improve * measurement accuracy. Deduplication identifiers (e.g., `event_id`) are used to avoid double attribution. * * --- * 🎯 Tracking Event Priority Reference * * | Impact Level | Description | Recommended Delivery Strategy | * |--------------|------------------------------------------------------------|-------------------------------------| * | 🔴 Critical | Missing this breaks ROAS, attribution, and ad optimization | Use Action Scheduler or job queue | * | 🟠 High | Important for funnels and retargeting | Use Action Scheduler where feasible | * | 🟡 Medium | Useful for remarketing and behavior signals | Use async request (AJAX) | * | 🟢 Low | Low impact analytics or audience seeding | Use async request (AJAX) | * --- * * @since 0.1.0 */ interface ConversionTrackerInterface { /** * Tracks a completed purchase event via the Ad Partner’s Conversions API. * * This method should be called when a WooCommerce order is completed or reaches a defined status. * The implementing class is expected to extract relevant order metadata (e.g., total amount, item list, currency), * contextual information (e.g., user agent, IP), and deduplication identifiers (e.g., event ID or transaction ID). * It should construct a payload compatible with the Ad Partner’s API and dispatch it accordingly. * * To ensure reliable delivery — even if the customer closes the browser or loses connectivity — * this method must enqueue the event for asynchronous processing using a background job system * such as Action Scheduler or a custom job queue. * * @since 0.1.0 * @impact 🔴 critical — Required for accurate revenue attribution and ad spend optimization. * * @param int $order WooCommerce order ID to track. * @return void */ public function track_purchase( int $order ): void; /** * Tracks a product add-to-cart event via the Ad Partner’s Conversions API. * * This method should be called when a product is added to the cart server-side * (e.g., during AJAX handlers or custom logic). The implementing class is expected * to extract product details (e.g., ID, price, quantity), contextual metadata * (e.g., session, IP, user agent), and deduplication keys (e.g., event ID) to build * a compatible payload for the Ad Partner’s Conversions API. * * To ensure reliable delivery — even if the customer closes the browser or loses connectivity — * this method must enqueue the event for asynchronous processing using a background job system * such as Action Scheduler or a custom job queue. * * @since 0.1.0 * @impact 🟠 high — Valuable for retargeting and funnel analytics. * * @param int $product_id WooCommerce product ID being added. * @param int $quantity Quantity of the product added to cart. * @param string $event_id The unique event ID. * @return void */ public function track_add_to_cart( int $product_id, int $quantity, string $event_id = '' ): void; /** * Tracks a product view (ViewContent) event via the Ad Partner’s Conversions API. * * This method should be called when a user views a single product page. The implementing class * is expected to extract relevant product metadata (e.g., product ID). along with contextual * user data (e.g., IP address, user agent, session ID), and deduplication identifiers such as * an `event_id`. The constructed payload should comply with the Ad Partner’s Conversions API * specification and be dispatched either immediately or queued for asynchronous processing. * * ⚠️ Important: This event is triggered with high frequency on high-traffic sites. Therefore, it * should **not** be enqueued using Action Scheduler or background job queues, as those tables * would grow rapidly and impact performance. Instead, dispatch the event immediately via a * lightweight async mechanism such as `navigator.sendBeacon()` or a fire-and-forget AJAX request. * * 🧠 For high-quality signal generation, avoid firing this event on simple page reloads. Instead, * treat direct URL visits, redirections, and backward/forward browser navigation as meaningful * product views worthy of triggering this event. * * @since 0.1.0 * @impact 🟠 high — Valuable for retargeting and funnel analytics. * * @param int $product_id WooCommerce product ID being viewed. * @param string $event_id The unique event ID used for deduplication. * @return void */ public function track_view_content( int $product_id, string $event_id = '' ): void; /** * Tracks a page view event via the Ad Partner’s Conversions API. * * This method should be called when a user views a non-product page (e.g., homepage, category page, blog). * The implementing class is expected to gather contextual metadata such as the current URL, * referrer, session ID, user agent, and IP address. A deduplication identifier (e.g., `event_id`) * should be included if possible to match client-side tracking. * * To avoid performance bottlenecks, this event should be dispatched using a lightweight async method * such as an AJAX call. Avoid queuing it in background job systems like Action Scheduler. * * @since 0.1.0 * @impact 🟢 low — General analytics or audience seeding. * * @param string $event_id The unique event ID used for deduplication. * @return void */ public function track_page_view( string $event_id = '' ): void; /** * Sends a previously constructed conversion event payload to the Ad Partner’s Conversions API. * * This method is typically triggered asynchronously by background job processors such as * Action Scheduler. The implementing class is expected to retrieve necessary authentication * credentials (e.g., access token), contextual data (e.g., user identifiers), and construct * the full API request to the appropriate Ad Partner endpoint. * * The payload may represent events such as purchases or add-to-cart actions and should be * formatted according to the Ad Partner’s specification. This method should also handle * response parsing, error handling, and optionally trigger related WordPress hooks for * extensibility. * * @since 0.1.0 * * @param array<string,mixed> $event_payload The event payload to transmit, including metadata and user data. * @param array $args Additional arguments passed alongside the payload (e.g., order ID). * @return void */ public function send( array $event_payload, array $args ): void; }
| ver. 1.4 |
Github
|
.
| PHP 8.5.7 | Generation time: 0 |
proxy
|
phpinfo
|
Settings