JezK

Edit File: html-hooks.php

<?php

namespace PixelYourSite;

if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

<div id="pys-hooks-toolbar" data-pys-hooks-keep="1">
        <input type="text" id="pys-hooks-search" placeholder="Search hooks and filters&hellip;"
               autocomplete="off" aria-label="Search hooks and filters">
        <span id="pys-hooks-count"></span>
        <nav aria-label="Hook sections">
            <a href="#pys-hooks-consent">Consent (GDPR)</a>
            <a href="#pys-hooks-privacy">Privacy modes</a>
            <a href="#pys-hooks-cookies">Cookies &amp; identifiers</a>
            <a href="#pys-hooks-events">Pixels &amp; event firing</a>
            <a href="#pys-hooks-userdata">Server-side user data &amp; matching</a>
            <a href="#pys-hooks-shops">WooCommerce &amp; EDD</a>
        </nav>
    </div>

<p id="pys-hooks-no-results" style="display:none;">Nothing matches this search. <a href="#" id="pys-hooks-clear">Clear search</a></p>

<h3 class="pys-hooks-section-title" id="pys-hooks-consent">Consent (GDPR)</h3>

</div>
            </div>
        </div>
    </div>

<h3 class="pys-hooks-section-title" id="pys-hooks-privacy">Privacy modes</h3>

<h3 class="pys-hooks-section-title" id="pys-hooks-cookies">Cookies &amp; identifiers</h3>

<div class="card card-style3 hook-card">
        <div class="card-header card-header-style2 disable-card-wrap d-flex justify-content-between align-items-center">
            <div class="disable-card align-items-center">
                <h4 class="secondary_heading_type2">pys_disable_all_cookie</h4>
            </div>
            <?php cardCollapseSettings(); ?>
        </div>
        <div class="card-body">
            <div class="flex-column-24gap">
                <div class="double-line-height">
                    <p>disable all PYS cookies</p>
                    <p>Param: bool $status</p>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter('pys_disable_all_cookie',function ($status) {
    $user = wp_get_current_user();
    $roles = ( array ) $user->roles;
    if(in_array('administrator', $roles) ) {
        return true;
    }
    return $status;
});<div class="copy-icon" data-toggle="pys-popover"
        data-tippy-trigger="click" data-tippy-placement="bottom"
        data-popover_id="copied-popover"></div></pre>
                </div>
                <div class="double-line-height">
                    <p>there are also filters to disable certain groups of cookies that work on the same principle</p>
                    <p><code>pys_disabled_start_session_cookie</code> - disable start_session & session_limit cookie</p>
                    <p><code>pys_disable_first_visit_cookie</code> - disable pys_first_visit cookie</p>
                    <p><code>pys_disable_landing_page_cookie</code> - disable pys_landing_page & last_pys_landing_page cookies</p>
                    <p><code>pys_disable_trafficsource_cookie</code> - disable pysTrafficSource & last_pysTrafficSource cookies</p>
                    <p><code>pys_disable_utmTerms_cookie</code> - disable ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content' ,'utm_term'] with prefix <code>pys_</code> and <code>last_pys_</code> cookies</p>
                    <p><code>pys_disable_utmId_cookie</code> - disable ['fbadid', 'gadid', 'padid', 'bingid'] with prefix <code>pys_</code> and <code>last_pys_</code> cookies</p>
                    <p><code>pys_disable_advance_data_cookie</code> - disable pys_advanced_data cookies</p>
                    <p><code>pys_disable_externalID_by_gdpr</code> - disable pbid(external_id) cookie</p>
                </div>
            </div>
        </div>
    </div>

<div class="card card-style3 hook-card">
        <div class="card-header card-header-style2 disable-card-wrap d-flex justify-content-between align-items-center">
            <div class="disable-card align-items-center">
                <h4 class="secondary_heading_type2">pys_cookie_domain_override - Set the tracking-cookie domain manually</h4>
            </div>
            <?php cardCollapseSettings(); ?>
        </div>
        <div class="card-body">
            <div class="flex-column-24gap">
                <div class="double-line-height">
                    <p>Param: string $domain, string $host</p>
                    <p>PYS normally learns the cookie domain from the visitor's browser: the front-end script reports which domain the browser actually accepted, and server-side <span class="event-parameter-list">_fbp</span> waits for that answer. Return a domain here to skip the handshake &mdash; for sites where the script cannot run (aggressive page caching, a consent tool blocking it) or for unusual multi-domain setups.</p>
                    <p>The value must cover the current host (e.g. <span class="event-parameter-list">.example.com</span> for <span class="event-parameter-list">shop.example.com</span>), otherwise it is ignored. Return an empty string to let PYS decide. Register the filter no later than <span class="event-parameter-list">init</span> priority 20 &mdash; <span class="event-parameter-list">plugins_loaded</span> is the safe place.</p>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter( 'pys_cookie_domain_override', function ( $domain, $host ) {
    return '.example.com';
}, 10, 2 );<div class="copy-icon" data-toggle="pys-popover"
        data-tippy-trigger="click" data-tippy-placement="bottom"
        data-popover_id="copied-popover"></div></pre>
                </div>
            </div>
        </div>
    </div>

<div class="card card-style3 hook-card">
        <div class="card-header card-header-style2 disable-card-wrap d-flex justify-content-between align-items-center">
            <div class="disable-card align-items-center">
                <h4 class="secondary_heading_type2">pys_{platform}_cookie_lifetime_days - Lifetime of the click-id cookies</h4>
            </div>
            <?php cardCollapseSettings(); ?>
        </div>
        <div class="card-body">
            <div class="flex-column-24gap">
                <div class="double-line-height">
                    <p>{platform} - openai, or pinterest (needs the PixelYourSite Pinterest add-on); the TikTok variant exists in PixelYourSite PRO</p>
                    <p>Param: int $days</p>
                    <p>PYS stores each platform's ad click id in a first-party cookie (<span class="event-parameter-list">pys_ttclid</span>, <span class="event-parameter-list">pys_epik</span>, <span class="event-parameter-list">__oppref</span>) so a purchase sent later &mdash; from the events queue, a payment webhook, an admin order-status change &mdash; still carries the click that brought the buyer.</p>
                    <p>Defaults: TikTok 90 days (TikTok asks integrators to store the click id for 28 days or more), Pinterest 365 days (matching Pinterest's own <span class="event-parameter-list">_epik</span> cookie), OpenAI 90 days. Values are clamped between 1 and 400 days.</p>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter( 'pys_pinterest_cookie_lifetime_days', function ( $days ) {
    return 30;
} );<div class="copy-icon" data-toggle="pys-popover"
        data-tippy-trigger="click" data-tippy-placement="bottom"
        data-popover_id="copied-popover"></div></pre>
                </div>
            </div>
        </div>
    </div>

<div class="card card-style3 hook-card">
        <div class="card-header card-header-style2 disable-card-wrap d-flex justify-content-between align-items-center">
            <div class="disable-card align-items-center">
                <h4 class="secondary_heading_type2">pys_external_id_user_value - Change the account id sent as an external ID</h4>
            </div>
            <?php cardCollapseSettings(); ?>
        </div>
        <div class="card-body">
            <div class="flex-column-24gap">
                <div class="double-line-height">
                    <p>Params: string $value, int $user_id</p>
                    <p>When a visitor is logged in, their WordPress user ID travels alongside the browser ID as a second external ID, so the same person is recognised across devices and browsers. This filter receives the ID <em>before</em> it is hashed; whatever you return is SHA-256 hashed unless it already is a hash, which is the only format the browser Pixel and the Conversions API send identically.</p>
                    <p>Namespace it here if one Pixel serves several sites, where account 5 is a different person on each of them. Whatever you return must stay the same over time &mdash; changing it later starts a new identity and discards the matching built up so far.</p>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter('pys_external_id_user_value',function ($value, $user_id) {
    return 'shop-' . $user_id;
}, 10, 2);<div class="copy-icon" data-toggle="pys-popover"
        data-tippy-trigger="click" data-tippy-placement="bottom"
        data-popover_id="copied-popover"></div></pre>
                </div>
            </div>
        </div>
    </div>

<div class="card card-style3 hook-card">
        <div class="card-header card-header-style2 disable-card-wrap d-flex justify-content-between align-items-center">
            <div class="disable-card align-items-center">
                <h4 class="secondary_heading_type2">pys_external_ids - Change the whole set of external IDs for an event</h4>
            </div>
            <?php cardCollapseSettings(); ?>
        </div>
        <div class="card-body">
            <div class="flex-column-24gap">
                <div class="double-line-height">
                    <p>Params: array $ids, int $user_id</p>
                    <p>Meta's Conversions API takes <span class="event-parameter-list">external_id</span> as one value or a list of them, and Pinterest's API takes a list; this is that list. It holds the browser ID first, then the ID stored for a logged-in visitor, then the hashed account ID. Return an empty array to send none.</p>
                    <p>Keep the browser ID in the set. The Pixel sends a single value, and matching only holds together while that value is one of the ones the server sends. Anything you add here is sent as you return it, so hash it yourself &mdash; the values already in the list are hashes.</p>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter('pys_external_ids',function ($ids, $user_id) {
    $crm = $user_id ? get_user_meta($user_id, 'crm_contact_id', true) : '';
    if ($crm) {
        $ids[] = hash('sha256', strtolower(trim($crm)));
    }
    return array_values(array_unique(array_filter($ids)));
}, 10, 2);<div class="copy-icon" data-toggle="pys-popover"
        data-tippy-trigger="click" data-tippy-placement="bottom"
        data-popover_id="copied-popover"></div></pre>
                </div>
            </div>
        </div>
    </div>

<h3 class="pys-hooks-section-title" id="pys-hooks-events">Pixels &amp; event firing</h3>

<div class="card card-style3 hook-card">
        <div class="card-header card-header-style2 disable-card-wrap d-flex justify-content-between align-items-center">
            <div class="disable-card align-items-center">
                <h4 class="secondary_heading_type2">pys_pixel_disabled - Disable Pixel</h4>
            </div>
            <?php cardCollapseSettings(); ?>
        </div>
        <div class="card-body">
            <div class="flex-column-24gap">
                <div class="double-line-height">
                    <p>Param: bool $isActive,string $pixelSlug</p>
                    <p>Return: Array</p>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter('pys_pixel_disabled',function ($isActive,$pixelSlug) {
    if(get_current_user_id() == 0 && $pixelSlug == 'facebook') {
        return ['all']; // Disable all pixels
    }
    return $isActive;
},11,2);<div class="copy-icon" data-toggle="pys-popover"
             data-tippy-trigger="click" data-tippy-placement="bottom"
             data-popover_id="copied-popover"></div></pre>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter('pys_pixel_disabled',function ($isActive,$pixelSlug) {
    if(get_current_user_id() == 0 && $pixelSlug == 'facebook') {
        return ['1123450378576095', '1300447800692613']; // Disables pixels that are in the array
    }
    return $isActive;
},11,2);<div class="copy-icon" data-toggle="pys-popover"
             data-tippy-trigger="click" data-tippy-placement="bottom"
             data-popover_id="copied-popover"></div></pre>
                </div>
            </div>
        </div>
    </div>

<h3 class="pys-hooks-section-title" id="pys-hooks-userdata">Server-side user data &amp; matching</h3>

<div class="card card-style3 hook-card">
        <div class="card-header card-header-style2 disable-card-wrap d-flex justify-content-between align-items-center">
            <div class="disable-card align-items-center">
                <h4 class="secondary_heading_type2">pys_openai_matching_values - Edit the OpenAI matching values as lists</h4>
            </div>
            <?php cardCollapseSettings(); ?>
        </div>
        <div class="card-body">
            <div class="flex-column-24gap">
                <div class="double-line-height">
                    <p>The same identity as pys_openai_advanced_matching, but before it is reduced to one value per field: each key holds an ORDERED list. The Conversions API takes up to three emails and two phone numbers, and uses them in the order given — the browser Pixel takes only the first of each.</p>
                    <p>Keys are the same nine; values are arrays of already-normalised, already-hashed strings. Filter this to add a value the plugin cannot know about, or to reorder them; filter pys_openai_advanced_matching to change what the browser sends.</p>
                    <p>Params: array $values, int|null $wooOrder, int|null $eddOrder</p>
                </div>
                <div class="example-block">
                    <label>Example:</label>
                    <pre class="copy_text">
add_filter('pys_openai_matching_values',function ($values) {
    // A second address for the same customer, tried after the first.
    $values['email_sha256'][] = hash('sha256', 'billing@example.com');
    return $values;
});<div class="copy-icon" data-toggle="pys-popover"
        data-tippy-trigger="click" data-tippy-placement="bottom"
        data-popover_id="copied-popover"></div></pre>
                </div>
            </div>
        </div>
    </div>

<h3 class="pys-hooks-section-title" id="pys-hooks-shops">WooCommerce &amp; EDD</h3>

// optional: widen the window (seconds, default 1 hour)
add_filter( 'pys_woo_legacy_gateway_compat_window', function () {
    return 2 * HOUR_IN_SECONDS;
} );<div class="copy-icon" data-toggle="pys-popover"
        data-tippy-trigger="click" data-tippy-placement="bottom"
        data-popover_id="copied-popover"></div></pre>
                </div>
            </div>
        </div>
    </div>

</div>
<script>
(function () {
    var input = document.getElementById('pys-hooks-search');
    if (!input) { return; }
    var wrapper  = input.closest('.hooks-wrapper');
    var cards    = Array.prototype.slice.call(wrapper.querySelectorAll('.hook-card'))
        .filter(function (c) { return !c.hasAttribute('data-pys-hooks-keep'); });
    var headings = Array.prototype.slice.call(wrapper.querySelectorAll('.pys-hooks-section-title'));
    var chips    = Array.prototype.slice.call(document.querySelectorAll('#pys-hooks-toolbar nav a'));
    var empty    = document.getElementById('pys-hooks-no-results');
    var counter  = document.getElementById('pys-hooks-count');
    var clear    = document.getElementById('pys-hooks-clear');

// Per-section counts on the chips, computed from the page itself so the
    // Free and PRO copies never drift.
    chips.forEach(function (chip) {
        var id = chip.getAttribute('href').slice(1);
        var heading = document.getElementById(id);
        if (!heading) { return; }
        var n = document.createElement('span');
        n.className = 'pys-hooks-chip-count';
        n.textContent = sectionCards(heading).length;
        chip.appendChild(n);
    });

function apply() {
        var q = input.value.toLowerCase().trim();
        var shown = 0;

cards.forEach(function (card) {
            var hit = !q || card.textContent.toLowerCase().indexOf(q) !== -1;
            card.style.display = hit ? '' : 'none';
            if (hit) { shown++; }
        });

headings.forEach(function (heading) {
            var visible = sectionCards(heading).some(function (c) {
                return c.style.display !== 'none';
            });
            heading.style.display = visible ? '' : 'none';
            var chip = document.querySelector('#pys-hooks-toolbar nav a[href="#' + heading.id + '"]');
            if (chip) { chip.classList.toggle('pys-hooks-chip-empty', !visible); }
        });

counter.textContent = q
            ? 'Showing ' + shown + ' of ' + cards.length
            : cards.length + ' hooks and filters';
        if (empty) { empty.style.display = shown ? 'none' : ''; }
    }

input.addEventListener('input', apply);
    if (clear) {
        clear.addEventListener('click', function (e) {
            e.preventDefault();
            input.value = '';
            apply();
            input.focus();
        });
    }
    apply();
})();
</script>