Hexo

Hexo 5 and later have an injector API that adds HTML to the <head> of every generated page from a small file in scripts/, so you do not have to edit a theme.

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 Hexo

Add the ID to the site's root _config.yml (not the theme's config):
_config.yml
```
onyxmetric:
  site_id: "YOUR_SITE_ID"
```

Create scripts/onyxmetric.js. Hexo runs every file in that folder at startup with hexo in scope:

scripts/onyxmetric.js

const { site_id: siteId } = hexo.config.onyxmetric || {};

if (siteId) {
  hexo.extend.injector.register(
    "head_end",
    `<script src="https://app.onyxmetric.com/api/script.js?siteId=${siteId}" async></script>`
  );
}

head_end places the tag just before </head> on every page type.

Paste the tag before </head> in your theme's head partial. For the default Landscape theme that is themes/landscape/layout/_partial/head.ejs; other themes have an equivalent file.

themes/landscape/layout/_partial/head.ejs

  ...
  <script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>
</head>

Theme updates overwrite this file, so use the injector when your Hexo version supports it.

Regenerate and deploy public/:

hexo clean && hexo generate

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.js returns 200 and 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

hexo.extend.injector is undefined: the API arrived in Hexo 5.0. Check hexo version, upgrade, or use the theme method.
Tag missing after adding the script: run hexo clean first. Hexo caches rendered output in db.json and can serve stale pages.
Previews are tracked: hexo server runs the same injector. Keep site_id empty in your local _config.yml if you want to avoid that.
Wrong config file: hexo.config reads the root _config.yml, not themes/<name>/_config.yml.

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.

Copy your tracking snippet

Add the snippet to Hexo

Check that it works

Troubleshooting

Next steps

On this page