CLItrail Docs

Add CLItrail to Mintlify

Where the CLItrail tag goes in Mintlify, in its own idiom, with the consent, CSP and client-side routing details and how to check it works.

Written for Mintlify (hosted docs)

#Where the tag goes

Edit clitrail.js in your docs folder (next to docs.json). Put the tag on every page that shows your install command; site-wide is best, after your existing analytics tags.

// Mintlify runs every .js file in the docs folder on every page.
(() => {
  if (document.getElementById('clitrail')) return;
  const tag = document.createElement('script');
  tag.id = 'clitrail';
  tag.src = 'https://YOUR_SERVICE/browser.js';
  tag.dataset.website = 'YOUR_WEBSITE_ID';
  document.head.append(tag);
})();

Use this file instead of the one above: it defines startClitrail(), which adds the tag once your consent manager reports consent.

// Loads CLItrail only after the visitor agrees. Call startClitrail() from your
// consent manager's "accepted" callback; nothing is fetched or stored before that.
window.startClitrail = () => {
  if (document.getElementById('clitrail')) return;
  const tag = document.createElement('script');
  tag.id = 'clitrail';
  tag.src = 'https://YOUR_SERVICE/browser.js';
  tag.dataset.website = 'YOUR_WEBSITE_ID';
  document.head.append(tag);
};

#Client-side routing

Mintlify runs custom scripts once the page becomes interactive. The script adds the tag once, so the first page a visitor opens is recorded: the landing page, which carries the campaign.

#Content Security Policy

Mintlify serves the pages. If you put a Content-Security-Policy in front of them (for example through your own proxy), add https://YOUR_SERVICE to script-src and connect-src, and blob: to worker-src (only Safari before 26 needs that one).

script-src 'self' https://YOUR_SERVICE;
connect-src 'self' https://YOUR_SERVICE;
worker-src 'self' blob:;

#Verify it works

  1. Deploy the docs (or run mint dev, http://localhost:3000).
  2. Open a page with the tag in Chrome or Firefox (accept analytics first if you gate CLItrail on consent), open the developer console and run await InstallAttribution.ready. It resolves to { ok: true, urlId, hasAnalyticsContext, expiresAt }.
  3. In the CLItrail dashboard, open Visits & identities: the visit is listed.
  4. Anything else names the cause: disabled (no consent yet, or data-enabled="false"), opfs_unavailable (the page is not served over https or from localhost), Error (the service refused the visit: add the page's origin, including a development origin such as http://localhost:3000, under Settings → Additional domains). If InstallAttribution is undefined, the tag did not load: check the Network tab and your Content-Security-Policy.

Then run your installer on the same computer and check Install events, or run the hook with --doctor.

#If a visit is not recorded

Start the SDK yourself: this adds the tag without data-website and calls InstallAttribution.init once it loads.

Manual start

(() => {
  if (window.InstallAttribution) return;
  const tag = document.createElement('script');
  tag.src = 'https://YOUR_SERVICE/browser.js';
  tag.onload = () => {
    const sdk = window.InstallAttribution;
    sdk.ready = sdk.init({ service: 'https://YOUR_SERVICE', project: 'YOUR_WEBSITE_ID' });
  };
  document.head.append(tag);
})();

#Notes

  • Mintlify cannot put attributes on a <script> in <head>, so the file creates the tag itself, with data-website.
  • Mintlify runs .js files in no guaranteed order: keep CLItrail in one file.

Mintlify documentation: www.mintlify.com/docs/customize/custom-scripts

Using other install paths or destinations? The setup generator puts this snippet together with your hooks and destination checklist.