Skip to main content

WordPress Plugin

The LinkForty WordPress plugin puts the web pixel on every page of your site and, when WooCommerce is active, reports purchases as conversions attributed to the LinkForty link that brought the customer. Install it, paste your site key, done. No theme editing, no tagging buttons, and it works with every page builder because the pixel goes into the page head, not into the layout.

Cloud only

The plugin sends events to LinkForty Cloud and shows up in the Web Analytics dashboard. Self-hosted Core does not include the pixel ingestion pipeline.

What it does​

  • Page views and engagement on every front-end page, including client-side route changes
  • WooCommerce purchases as a purchase conversion with the order total as revenue, reported exactly once per order
  • Checkout starts and add-to-cart actions as begin_checkout and add_to_cart
  • Attribution that survives the journey — the pixel remembers the link a visitor arrived from for the whole session, and the plugin carries it through WooCommerce's add-to-cart redirect, which otherwise drops it
  • Consent-aware — a persistent visitor ID is only set when you turn it on and, with a consent plugin that supports the WP Consent API, only after the visitor grants statistics consent

Install​

  1. Download the latest release from GitHub and upload the zip under Plugins → Add New → Upload Plugin, then activate it.
  2. In the LinkForty dashboard, open Workspace Settings → Web Pixel and copy your site key. It starts with ws_.
  3. In WordPress, open Settings → LinkForty, paste the site key, and save.

Page views start flowing immediately. Open Analytics → Web in LinkForty and load a page on your site to confirm.

Mark purchase as a goal

Any event the pixel reports arrives as a conversion row, but only the events you designate as goals count toward conversion rate and revenue. On the Web analytics tab, add purchase to your goals. See Goals & revenue.

Settings​

All settings live under Settings → LinkForty.

SettingDefaultDescription
Site key—Your workspace's public site key (ws_ + 32 hex characters). The plugin validates the format on save.
Enable web trackingOnAdds the pixel to every front-end page. With it off, nothing is sent and the WooCommerce events are not reported either.
Enable visitor IDOffAdds data-visitors="true" for new-vs-returning analytics. Consent-sensitive; see Visitor ID.
Track WooCommerce eventsOnReports purchase, begin_checkout, and add_to_cart. Only shown as active when WooCommerce is installed.
Exclude administratorsOffSkips the pixel for logged-in users who can manage options, keeping test orders and admin browsing out of your numbers. Leave it off while verifying the install.
Linked domains—Other hostnames you send visitors to, comma-separated. Links and forms pointing at them carry the session's attribution across. See Cross-domain tracking.
Ingestion endpoint—Override for a custom domain or self-hosted deployment. Must be https://. Leave blank otherwise.

WooCommerce events​

Events are handed to the browser pixel, never sent from your server to LinkForty. That is deliberate: the pixel attaches the session's click id (lf_click) and UTM parameters, which is what attributes an event to a link. A server-to-server call would have neither.

EventWhenProperties
purchaseThe order-received page, once per order, for orders in processing, completed, or on-holdorder_id, revenue, currency, item_count, payment_method, coupon
begin_checkoutEach checkout page view with a non-empty cartvalue, currency, item_count
add_to_cartAJAX add-to-cart buttons, the block cart, and product-page form submitsproduct_id, quantity, sku, plus product_name, price, variation_id, currency on form submits

A few details worth knowing:

  • Purchases fire on confirmed orders, not on button clicks. A click on "Place order" is intent. An order on the order-received page is revenue.
  • Each order is reported once. The plugin stamps the order with a private meta key the first time it reports it. Refreshing the order-received page does not double count, and the stamp survives plugin reinstalls.
  • Pending orders wait. The order-received page can render before an off-site gateway confirms payment, while the order is still pending. Those orders are reported when the customer next lands on the page with the order in a paid status. If your store uses a gateway that never returns the customer to the site, see Troubleshooting.
  • Revenue is the order total including tax and shipping, as WooCommerce reports it. Use the linkforty_purchase_properties filter to change that.

How attribution works on WordPress​

  1. A visitor clicks a LinkForty link. The redirect appends lf_click and the link's UTM parameters to the destination URL.
  2. The pixel on the landing page reads them and stores them for the session. They follow the visitor through product pages, the cart, and checkout.
  3. On the order-received page, the plugin hands the purchase event to the pixel, which attaches the stored click id. LinkForty resolves it to the exact click and link.

The one WordPress-specific trap is WooCommerce's Redirect to the cart page after successful addition setting. A link landing on ?add-to-cart=123 redirects before the pixel can read lf_click, and the session is never attributed. The plugin fixes this by carrying lf_click and the UTM parameters through that redirect, so you can leave the setting on.

For the general rules, including the 7-day click id window and last-click behavior, see How web attribution works.

Page builders​

Elementor, Beaver Builder, WPBakery, Divi, Bricks, and the block editor all render inside your theme's <head>, which is where the plugin places the pixel. No builder-specific setup is needed and you never have to add attributes to a button.

If you also want to count a non-WooCommerce action as a conversion, such as a form submission from a builder's form widget, you have two options:

  • Turn on autocapture via the linkforty_pixel_attributes filter, which reports every form submit as form_submit.
  • Add data-lf-event="your_event_name" to the element using the builder's custom-attributes field, where it has one. See Declarative conversions.

Hooks for developers​

HookPurpose
linkforty_should_track (filter, bool)Suppress the pixel and all events for a request
linkforty_pixel_attributes (filter, array)Change the data-* attributes on the pixel tag, for example to enable autocapture
linkforty_pixel_url (filter, string)Load the pixel from another URL
linkforty_visitor_id_allowed (filter, bool)Override the consent decision for the visitor ID
linkforty_event_properties (filter, array, name)Adjust or drop any event before it is sent
linkforty_purchase_properties (filter, array, order)Adjust the purchase properties
linkforty_purchase_order_statuses (filter, string[], order)Which order statuses count as a purchase

Your own code can report conversions through the same path, with the session's attribution attached:

add_action( 'wp', function () {
    if ( is_page( 'thank-you' ) ) {
        LinkForty_Events::track( 'demo_requested', array( 'plan' => 'pro' ) );
    }
} );

Enabling autocapture from a theme or a snippet plugin:

add_filter( 'linkforty_pixel_attributes', function ( $attributes ) {
    $attributes['data-autocapture'] = 'true';
    return $attributes;
} );

Troubleshooting​

No page views

  1. Confirm the site key under Settings → LinkForty is the real ws_… key and that Enable web tracking is on.
  2. View the page source and look for cdn.linkforty.com/pixel.js in the <head>. If it is missing, a caching or optimization plugin may be deferring or stripping scripts; exclude linkforty-pixel from it.
  3. Check the browser network tab for a POST to …/api/pixel/v1/event returning 204.
  4. A 204 with nothing stored usually means an origin allowlist is configured under Workspace Settings and your hostname is not on it.
  5. If Exclude administrators is on, log out or use a private window.
  6. Do Not Track or Global Privacy Control in your test browser silences the pixel by design.

Missing purchases

  • The order must be processing, completed, or on-hold when the order-received page renders. Check the order status in WooCommerce.
  • The customer's browser must reach the order-received page. Gateways that complete off-site and never return the customer cannot be reported by this plugin; that path needs a server-side event with the click id stored on the order, which is not in this version.
  • Ad blockers that block the pixel also block the purchase. There is nothing to configure; the event is simply not sent from that browser.

Purchases not attributed to a link

  • The visit must have arrived through a LinkForty link within the last 7 days, on the same domain where the purchase happens. For a store on a different domain from the landing site, set Linked domains on the landing site's plugin and install the plugin on both sites with the same site key.
  • If the link has Click-ID passthrough turned off, attribution falls back to UTM parameters, which the link must carry.

Requirements​

  • WordPress 6.3 or newer
  • PHP 7.4 or newer
  • WooCommerce 7.0 or newer for the e-commerce events. The plugin works without WooCommerce; you get page views, engagement, and any conversions you report yourself.
  • Compatible with WooCommerce High-Performance Order Storage

Next steps​