Skip to navigation

Analytics and integrations

View as Markdown

Fern’s built-in web analytics reports aggregated site usage without configuration. The integrations on this page connect your documentation to external analytics, session recording, support, and developer tools. Fern forwards a set of analytics events to the providers you configure.

Supported providers

Analytics

Session recording and support

Developer tools

Configure providers

Define your provider configuration in docs.yml. Include only the providers you want to connect.

docs.yml
analytics:
posthog:
api-key: ${POSTHOG_API_KEY}
endpoint: https://self.hosted.posthog.com/
segment:
write-key: ${SEGMENT_WRITE_KEY}
intercom:
app-id: ${INTERCOM_APP_ID}
endpoint: https://intercom.custom-instance.com/
fullstory:
org-id: ${FULLSTORY_ORG_ID}

Environment variables

If your docs configuration is public, don’t add secret values directly to docs.yml. Instead, reference an environment variable by using the syntax ${VARIABLE_NAME}.

If you use GitHub Workflows to trigger docs generation, the environment variables must be available during the workflow run.

- name: Publish Docs
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
POSTHOG_API_KEY: ${{ secrets.POSTHOG_PROJECT_API_KEY }}
run: |
npm install -g fern-api
fern generate --docs

Set settings.require-analytics-consent in docs.yml to keep PostHog analytics off until a visitor consents through a consent manager such as Ketch or OneTrust. The setting covers Fern’s built-in PostHog analytics and your own PostHog integration; other analytics providers aren’t gated by it. Unlike settings.disable-analytics, which turns analytics off for every visitor, this setting keeps analytics on for visitors who consent. Requires Fern CLI version 5.169.0 or later.

docs.yml
settings:
require-analytics-consent: true

Until the visitor consents, PostHog doesn’t load: no cookies or browser storage, no feature flag requests, no session recording, and no events. Events triggered before consent are dropped, not queued.

Your page reports consent by setting window.fernAnalyticsConsent and dispatching a fern-analytics-consent event on window, typically from your consent manager’s callback in a custom JavaScript file loaded with strategy: beforeInteractive. This example uses Ketch:

custom.js
window.fernAnalyticsConsent = false;
ketch("on", "consent", function (consent) {
window.fernAnalyticsConsent = consent.purposes.analytics === true;
window.dispatchEvent(new Event("fern-analytics-consent"));
});
docs.yml
js:
- path: ./custom.js
strategy: beforeInteractive
  • Grant: Setting window.fernAnalyticsConsent to true and dispatching the event starts PostHog and records a page view for the current page.
  • Revoke: Setting it to any other value and dispatching the event turns PostHog off for the rest of the page and removes PostHog’s ph_* and __ph_* cookies and storage keys. A later grant on the same page is ignored, and consent is read again on the next full page load. If the visitor revokes before PostHog has started, the next grant starts it as usual.

Sites without require-analytics-consent ignore window.fernAnalyticsConsent and the fern-analytics-consent event.

Connect other integrations via custom JavaScript

Enterprise feature

This feature is available only for the Enterprise plan. To get started, reach out to support@buildwithfern.com.

You can integrate third-party tools that Fern doesn’t natively support in docs.yml using custom JavaScript, as long as they support HTML tag-based installation. This works with tools like:

  • Analytics: Amplitude, Heap, Plausible
  • Session recording: Hotjar, LogRocket, Microsoft Clarity
  • Support and chat: Zendesk, Crisp, Drift
  • Tag managers: Adobe Launch, Tealium

Paste the vendor’s <script> snippet into a custom JS file and reference it in your docs.yml:

docs.yml
js: ./custom.js