add analytics to docs definition (#1250)

fern/apis/fdr/definition/docs/v1/commons/commons.yml

@@ -39,6 +39,14 @@ types:
       - ts
       - js
 
+  AnalyticsConfig:
+    properties:
+      segment: optional<SegmentConfig>
+
+  SegmentConfig:
+    properties:
+      writeKey: string
+
   DocsLayoutConfig:
     properties:
       pageWidth: optional<PageWidthSizeConfig>

fern/apis/fdr/definition/docs/v1/db/__package__.yml

@@ -50,6 +50,8 @@ types:
       title: optional<string>
       defaultLanguage: optional<commons.ProgrammingLanguage>
 
+      analyticsConfig: optional<commons.AnalyticsConfig>
+
       # navigation
       navigation: NavigationConfig
       navbarLinks: optional<list<commons.NavbarLink>>

fern/apis/fdr/definition/docs/v1/read/__package__.yml

@@ -87,6 +87,8 @@ types:
       title: optional<string>
       defaultLanguage: optional<commons.ProgrammingLanguage>
 
+      analyticsConfig: optional<commons.AnalyticsConfig>
+
       # navigation
       navigation: NavigationConfig
       navbarLinks: optional<list<commons.NavbarLink>>

fern/apis/fdr/definition/docs/v1/write/__package__.yml

@@ -83,6 +83,8 @@ types:
       title: optional<string>
       defaultLanguage: optional<commons.ProgrammingLanguage>
 
+      analyticsConfig: optional<commons.AnalyticsConfig>
+
       # navigation
       navigation: NavigationConfig
       navbarLinks: optional<list<commons.NavbarLink>>

packages/fdr-sdk/src/converters/db/convertDocsDefinitionToDb.ts

@@ -108,6 +108,7 @@ export function convertDocsDefinitionToDb({
             redirects: writeShape.config.redirects,
             integrations: writeShape.config.integrations,
             defaultLanguage: writeShape.config.defaultLanguage,
+            analyticsConfig: writeShape.config.analyticsConfig,
         },
         pages: writeShape.pages,
         jsFiles: writeShape.jsFiles,

packages/fdr-sdk/src/converters/read/convertDbDocsConfigToRead.ts

@@ -28,6 +28,7 @@ export function convertDbDocsConfigToRead({
         redirects: dbShape.redirects,
         integrations: dbShape.integrations,
         defaultLanguage: dbShape.defaultLanguage,
+        analyticsConfig: dbShape.analyticsConfig,
     };
 }
 

packages/ui/app/src/analytics/CustomerAnalytics.tsx

@@ -2,16 +2,28 @@ import { GoogleAnalytics } from "@next/third-parties/google";
 import { useAtomValue } from "jotai";
 import { selectAtom } from "jotai/utils";
 import { isEqual } from "lodash-es";
+import Script from "next/script";
 import { ReactElement, memo } from "react";
-import { DOCS_ATOM } from "../atoms";
+import { DOCS_ATOM, DOMAIN_ATOM } from "../atoms";
 import { GoogleTagManager } from "./GoogleTagManager";
+import { renderSegmentSnippet } from "./segment";
 
 const ANALYTICS_ATOM = selectAtom(DOCS_ATOM, (docs) => docs.analytics ?? {}, isEqual);
+const ANALYTICS_CONFIG_ATOM = selectAtom(DOCS_ATOM, (docs) => docs.analyticsConfig ?? {}, isEqual);
 
 export const CustomerAnalytics = memo(function CustomerAnalytics(): ReactElement | null {
+    const domain = useAtomValue(DOMAIN_ATOM);
     const { ga4, gtm } = useAtomValue(ANALYTICS_ATOM);
+    const { segment } = useAtomValue(ANALYTICS_CONFIG_ATOM);
     return (
         <>
+            {/* renders either segment with our write key or segment with the customer's write key */}
+            <Script
+                id="segment-script"
+                dangerouslySetInnerHTML={{
+                    __html: renderSegmentSnippet(domain, segment?.writeKey),
+                }}
+            />
             {ga4 != null && <GoogleAnalytics gaId={ga4.measurementId} />}
             {gtm != null && <GoogleTagManager {...gtm} />}
         </>

packages/ui/app/src/analytics/segment.ts

@@ -1,10 +1,11 @@
 import * as snippet from "@segment/snippet";
+
 const DOMAINS_TO_SKIP = ["privategpt.docs.buildwithfern.com"];
 
-export function renderSegmentSnippet(domain: string): string {
+export function renderSegmentSnippet(domain: string, customSegmentWriteKey?: string): string {
     const apiKey = process.env.NEXT_PUBLIC_SEGMENT_API_KEY?.trim();
     const opts = {
-        apiKey,
+        apiKey: customSegmentWriteKey ? customSegmentWriteKey : apiKey,
         page: true,
     };
     // Skip rendering the snippet for certain domains

packages/ui/app/src/atoms/docs.ts

@@ -64,6 +64,7 @@ const EMPTY_DOCS_STATE: DocsProps = {
     theme: "default",
     user: undefined,
     defaultLang: "curl",
+    analyticsConfig: {},
 };
 
 export const DOCS_ATOM = atomWithReducer<DocsProps, DocsProps>(EMPTY_DOCS_STATE, (_, next) => {

packages/ui/app/src/atoms/types.ts

@@ -52,7 +52,8 @@ export interface DocsProps {
     featureFlags: FeatureFlags;
     apis: FdrAPI.ApiDefinitionId[];
     seo: NextSeoProps;
-    analytics: CustomerAnalytics | undefined;
+    analytics: CustomerAnalytics | undefined; // deprecated
+    analyticsConfig: DocsV1Read.AnalyticsConfig | undefined;
     fallback: Record<string, any>;
     theme: FernTheme;
     user: FernUser | undefined;

packages/ui/app/src/next-app/utils/JavascriptProvider.tsx

@@ -3,15 +3,13 @@ import Head from "next/head";
 import Script from "next/script";
 import { memo } from "react";
 import { CustomerAnalytics } from "../../analytics/CustomerAnalytics";
-import { renderSegmentSnippet } from "../../analytics/segment";
-import { DOCS_ATOM, DOMAIN_ATOM, FILES_ATOM } from "../../atoms";
+import { DOCS_ATOM, FILES_ATOM } from "../../atoms";
 
 const JS_ATOM = atom((get) => get(DOCS_ATOM).js);
 
 export const JavascriptProvider = memo(() => {
     const files = useAtomValue(FILES_ATOM);
     const js = useAtomValue(JS_ATOM);
-    const domain = useAtomValue(DOMAIN_ATOM);
 
     return (
         <>
@@ -37,7 +35,6 @@ export const JavascriptProvider = memo(() => {
                 />
             ))}
             {js?.remote?.map((remote) => <Script key={remote.url} src={remote.url} strategy={remote.strategy} />)}
-            <Script id="segment-script" dangerouslySetInnerHTML={{ __html: renderSegmentSnippet(domain) }} />
             <CustomerAnalytics />
         </>
     );

packages/ui/docs-bundle/src/utils/getDocsPageProps.ts

@@ -367,6 +367,7 @@ async function convertDocsToDocsPageProps({
         fallback: {},
         analytics: await getCustomerAnalytics(docs.baseUrl.domain, docs.baseUrl.basePath),
         theme: docs.baseUrl.domain.includes("cohere") ? "cohere" : "default",
+        analyticsConfig: docs.definition.config.analyticsConfig,
         defaultLang: docs.definition.config.defaultLanguage ?? "curl",
     };
 

packages/ui/local-preview-bundle/src/utils/getDocsPageProps.ts

@@ -146,6 +146,7 @@ export async function getDocsPageProps(
         ),
         fallback: {},
         analytics: undefined,
+        analyticsConfig: docs.definition.config.analyticsConfig,
         theme: docs.baseUrl.domain.includes("cohere") ? "cohere" : "default",
         user: undefined,
         defaultLang: docs.definition.config.defaultLanguage ?? "curl",

servers/fdr/fern/fern.config.json

@@ -1,4 +1,4 @@
 {
   "organization": "fern",
-  "version": "0.16.36"
+  "version": "0.37.14"
 }