WordPress
Add OnyxMetric analytics to your WordPress site
WordPress has no built-in header-code setting. Add the tag with a plugin such as WPCode, or through your theme's functions.php or header.php.
Copy your tracking snippet
In OnyxMetric, open your site's Site Settings and copy the tracking script. It looks like this:
<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>YOUR_SITE_ID is the numeric ID of your site.
Add the snippet to WordPress
If you edit theme files, edit a child theme. Changes to a parent theme's functions.php or header.php are lost on the next theme update.
WPCode (formerly Insert Headers and Footers) is the easiest option. It survives theme updates and works with page builders.
- Go to Plugins > Add New, search for "WPCode", then install and activate it.
- Go to Code Snippets > Header & Footer.
- Paste the snippet into the Header box and click Save Changes.
- Go to Appearance > Theme File Editor and open your child theme's
functions.php. - Add this at the end, replacing
YOUR_SITE_ID:
function onyxmetric_add_tracking_script() {
?>
<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>
<?php
}
add_action( 'wp_head', 'onyxmetric_add_tracking_script' );- Save the file.
- Go to Appearance > Theme File Editor and open your child theme's
header.php. - Paste the snippet just before the closing
</head>tag:
<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>
</head>- Save the file.
A one-file plugin keeps the tag in place through theme changes without touching theme files.
- Over SFTP or a file manager, create the folder
/wp-content/plugins/onyxmetric-analytics/. - Inside it, create
onyxmetric-analytics.php:
<?php
/**
* Plugin Name: OnyxMetric Analytics
* Description: Adds the OnyxMetric tracking script to every page
* Version: 1.0
*/
function onyxmetric_add_tracking_script() {
?>
<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>
<?php
}
add_action( 'wp_head', 'onyxmetric_add_tracking_script' );- Go to Plugins and activate OnyxMetric Analytics.
Running WooCommerce? See the WooCommerce guide for purchase and add-to-cart events.
Check that it works
Load your live site and click through a few pages. Pageviews show up in the OnyxMetric dashboard within seconds.
If nothing arrives:
- View the page source and search for
script.js?siteId=to confirm the tag is present. - In the browser's Network tab, check that
script.jsreturns200and that requests go to/api/track. - Turn off ad blockers, or proxy the script through your own domain.
- Read script troubleshooting for other causes.
Troubleshooting
- Caching plugins: purge WP Super Cache, W3 Total Cache, LiteSpeed Cache, or whichever you run, plus any CDN cache, after saving the snippet.
- Script optimizers: "Delay JavaScript execution" options in WP Rocket, Perfmatters, and FlyingPress rebuild script tags and can drop attributes. Exclude
onyxmetric.comfrom them. - Page builders (Elementor, Divi, WPBakery, Beaver Builder): use WPCode rather than a builder's custom HTML block, since builders sanitize HTML.
- Security plugins: Wordfence, Sucuri, and similar tools can block external scripts. Allow
app.onyxmetric.com. - WordPress.com plans: Free, Personal, and Premium plans cannot add custom JavaScript. Upgrade to Business or eCommerce and use WPCode.
Next steps
- Track custom events such as signups, purchases, and clicks.
- Identify users to tie sessions to accounts.
- Proxy the script through your own domain to get past ad blockers.
- Script attributes let you skip or mask URLs and tag events.