@gocharles/axeptio-then-segment

Axeptio (CMP) + Segment (@segment/analytics-next) + Google Consent Mode defaults (denied until the CMP completes).

Uses @segment/analytics-consent-tools in opt-in mode (GDPR): unconsented device-mode destinations are blocked from initializing entirely. Category-to-destination mappings are configured in the Segment dashboard (Privacy → Consent Management) — no hardcoded destination list in code.

How it works

1. Google Consent Mode defaults are set to denied before anything loads.
2. Axeptio CMP is injected and displayed to the user.
3. Segment analytics.load() is called immediately, but the consent wrapper delays initialization until Axeptio fires cookies:complete (user accepts or refuses).
4. On consent, getCategories() returns the Axeptio choices as Record<string, boolean> (meta keys like $$googleConsentMode are stripped).
5. Consent-tools uses the category-to-destination mappings from the Segment CDN settings to block unconsented device-mode destinations from loading (e.g. Facebook Pixel scripts are never fetched if targeted_advertising is refused).
6. If the user re-opens the CMP and changes preferences, registerOnConsentChanged fires a Segment Consent Preference Updated event and destinations are re-evaluated.

Consumption (public npm)

Published as @gocharles/axeptio-then-segment on the public registry. No .npmrc or token is required to install.

Apps with a bundler (Vite, Gatsby, webpack, etc.)

npm install @gocharles/axeptio-then-segment

import { initAxeptioThenSegment } from '@gocharles/axeptio-then-segment'

CommonJS:

const { initAxeptioThenSegment } = require('@gocharles/axeptio-then-segment')

Types are included (dist/index.d.ts, dist/index.d.mts). Pin a semver range in package.json (e.g. ^4.1.0 vs exact version).

Browser only (no build step)

Load the IIFE from a CDN that mirrors npm (path inside the package: dist/axeptio-then-segment.iife.min.js).

jsDelivr (pin the version in production):

https://cdn.jsdelivr.net/npm/@gocharles/[email protected]/dist/axeptio-then-segment.iife.min.js

unpkg (equivalent):

https://unpkg.com/@gocharles/[email protected]/dist/axeptio-then-segment.iife.min.js

Then call the global (same options as initAxeptioThenSegment):

<script src="https://cdn.jsdelivr.net/npm/@gocharles/[email protected]/dist/axeptio-then-segment.iife.min.js" crossorigin="anonymous"></script>
<script>
  var analytics = AxeptioThenSegment.init({
    axeptioClientId: '…',
    segmentWriteKey: '…',
    cookiesVersion: '…',
    trackInitialPageView: true,
  })
  // `analytics` is the wrapped instance; `window.analytics` is the same object when using defaults.
</script>

Using @latest in the URL is possible but any new publish will immediately affect that URL; prefer a fixed version for production pages.

Alternatives

• GitHub Release asset (attached by CI on each version tag): https://github.com/gocharles/axeptio-then-segment/releases/latest/download/axeptio-then-segment.iife.min.js or a pinned URL under releases/download/vX.Y.Z/….

API

initAxeptioThenSegment(config) (and AxeptioThenSegment.init in the IIFE) returns the wrapped AnalyticsBrowser instance in the browser. In SSR (no window / document), it returns undefined.

The type AnalyticsBrowser is re-exported from @segment/analytics-next for convenience. Global Window is augmented with optional analytics when you import this package (see exposeOnWindow below).

| Option | Required | Description | |--------|----------|-------------| | axeptioClientId | yes | Your Axeptio client ID. | | segmentWriteKey | yes | Your Segment source write key. | | cookiesVersion | yes | Axeptio cookies / project configuration identifier from your Axeptio back-office. | | cookieDomain | no | Domain for the Axeptio consent cookie (e.g. .example.com). | | trackInitialPageView | no | Queue analytics.page() when Segment first loads after the CMP completes. Common on static HTML hosts. | | defaultGoogleConsentMode | no | Override the default Google Consent Mode payload (defaults to all denied). | | exposeOnWindow | no | Default true. After withAxeptio(analytics) and before analytics.load(...), assigns window.analytics = analytics so legacy window.analytics.track / identify / page / user() calls use the consent-aware wrapper. Set to false to leave window.analytics untouched. |

Migration v3 → v4 (and patch v4.0.x)

• v4 switches from the historical Segment snippet to @segment/analytics-next (AnalyticsBrowser) behind the same Axeptio + consent-tools flow (opt-in, device-mode blocking unchanged).
• In v4.0.x, initAxeptioThenSegment did not assign window.analytics, so code that gated on typeof window.analytics !== 'undefined' or called window.analytics.track(...) could silently stop sending events.
• From v4.1.0 onward, exposeOnWindow defaults to true, restoring the legacy global after the consent wrapper is applied and before load, without changing withAxeptio / createWrapper behavior.
• Recommended: rely on the returned instance (const analytics = initAxeptioThenSegment({...})) instead of the global, and use exposeOnWindow: false if you must avoid globals (multiple instances, tests, strict isolation).

Destination blocking

Destination blocking is enforced client-side by @segment/analytics-consent-tools:

• In opt-in mode (GDPR), device-mode destinations whose consent categories are not accepted by the user are never loaded — their scripts are not injected, no pixels fire, no network requests are made.
• Mappings between consent categories and destinations are managed in the Segment dashboard under Privacy → Consent Management. No code changes are needed when adding or removing destinations.
• To verify: open DevTools → Network after refusing all categories. You should see zero destination scripts (no fbevents.js, no Google Ads tags, etc.).

Local build

npm ci
npm run build

| Output | Role | |--------|------| | dist/index.mjs, dist/index.js | ESM / CJS | | dist/index.d.ts, dist/index.d.mts | Types | | dist/axeptio-then-segment.iife.min.js | Script tag / CDN (bundles analytics-next + consent-tools) |

Examples

See examples/.

Publishing (maintainers)

Automated (GitHub Actions)

1. In the GitHub repo Settings → Secrets and variables → Actions, add NPM_TOKEN: an npm access token able to publish @gocharles/axeptio-then-segment (e.g. Automation token, or Granular with Read and write on this package and Bypass 2FA if your account uses 2FA).
2. Ensure version in package.json matches the release you are about to tag.
3. Push a tag: git tag v4.1.0 && git push origin v4.1.0 (same version as in package.json, with a v prefix).

The release workflow runs npm publish --access public and creates a GitHub Release with the IIFE attached.

Manual

npm login
npm publish --access public

(prepublishOnly runs npm run build automatically.)

403 Forbidden — "Two-factor authentication or granular access token with bypass 2fa…"

npm blocks publish unless either:

1. You pass a one-time code (account with 2FA enabled):

   npm publish --access public --otp=123456

   Replace 123456 with the current code from your authenticator app (valid for a short time).

2. CI / token — use an Automation token, or a Granular token with Read and write on @gocharles/axeptio-then-segment and Bypass 2FA enabled (npm recommends Trusted Publishing long term).

Also ensure your npm user is a member of the @gocharles org with permission to publish this package.