docs: improved analytics and tracking (#13671)

* docs: improved analytics and tracking * remove detailed feedback component * remove ignore build script for api reference * improvements * fix pathname
2025-10-03 13:33:48 +03:00
parent 50c1417378
commit 6ea97443de
32 changed files with 214 additions and 381 deletions
--- a/www/apps/api-reference/components/DetailedFeedback/index.tsx
+++ b/www/apps/api-reference/components/DetailedFeedback/index.tsx
@@ -1,83 +0,0 @@
-"use client"
-
-import { useState } from "react"
-import { Label, TextArea, useAnalytics, useModal, ModalFooter } from "docs-ui"
-
-const DetailedFeedback = () => {
-  const [improvementFeedback, setImprovementFeedback] = useState("")
-  const [positiveFeedback, setPositiveFeedback] = useState("")
-  const [additionalFeedback, setAdditionalFeedback] = useState("")
-  const { loaded, track } = useAnalytics()
-  const { closeModal } = useModal()
-
-  return (
-    <>
-      <div className="flex flex-col gap-1 overflow-auto py-1.5 px-2 lg:min-h-[400px]">
-        <div className="flex flex-col gap-1">
-          <Label>What should be improved in this API reference?</Label>
-          <TextArea
-            rows={4}
-            value={improvementFeedback}
-            onChange={(e) => setImprovementFeedback(e.target.value)}
-          />
-        </div>
-        <div className="flex flex-col gap-1">
-          <Label>Is there a feature you like in this API reference?</Label>
-          <TextArea
-            rows={4}
-            value={positiveFeedback}
-            onChange={(e) => setPositiveFeedback(e.target.value)}
-          />
-        </div>
-        <div className="flex flex-col gap-1">
-          <Label>Do you have any additional notes or feedback?</Label>
-          <TextArea
-            rows={4}
-            value={additionalFeedback}
-            onChange={(e) => setAdditionalFeedback(e.target.value)}
-          />
-        </div>
-      </div>
-      <ModalFooter
-        actions={[
-          {
-            children: "Save",
-            onClick: (e) => {
-              if (
-                !loaded ||
-                (!improvementFeedback &&
-                  !positiveFeedback &&
-                  !additionalFeedback)
-              ) {
-                return
-              }
-              const buttonElm = e.target as HTMLButtonElement
-              buttonElm.classList.add("cursor-not-allowed")
-              buttonElm.textContent = "Please wait"
-              track(
-                "api-ref-general-feedback",
-                {
-                  feedbackData: {
-                    improvementFeedback,
-                    positiveFeedback,
-                    additionalFeedback,
-                  },
-                },
-                function () {
-                  buttonElm.textContent = "Thank you!"
-                  setTimeout(() => {
-                    closeModal()
-                  }, 1000)
-                }
-              )
-            },
-            variant: "primary",
-          },
-        ]}
-        className="mt-1"
-      />
-    </>
-  )
-}
-
-export default DetailedFeedback
--- a/www/apps/api-reference/components/Feedback/index.tsx
+++ b/www/apps/api-reference/components/Feedback/index.tsx
@@ -0,0 +1,23 @@
+"use client"
+
+import { Feedback as UiFeedback, FeedbackProps } from "docs-ui"
+import { usePathname } from "next/navigation"
+import { useArea } from "../../providers/area"
+
+export const Feedback = (props: Partial<FeedbackProps>) => {
+  const pathname = usePathname()
+  const { area } = useArea()
+
+  return (
+    <UiFeedback
+      vertical={true}
+      {...props}
+      event="survey_api-ref"
+      extraData={{
+        area,
+        ...props.extraData,
+      }}
+      pathName={`/api/${pathname}`}
+    />
+  )
+}
--- a/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx
+++ b/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx
@@ -7,9 +7,7 @@ import type { TagsOperationDescriptionSectionResponsesProps } from "./Responses"
 import dynamic from "next/dynamic"
 import TagsOperationDescriptionSectionParameters from "./Parameters"
 import MDXContentClient from "@/components/MDXContent/Client"
-import { useArea } from "../../../../providers/area"
 import {
-  Feedback,
  Badge,
  Link,
  FeatureFlagNotice,
@@ -17,10 +15,10 @@ import {
  Tooltip,
  MarkdownContent,
 } from "docs-ui"
-import { usePathname } from "next/navigation"
 import { TagsOperationDescriptionSectionWorkflowBadgeProps } from "./WorkflowBadge"
 import { TagsOperationDescriptionSectionEventsProps } from "./Events"
 import { TagsOperationDescriptionSectionDeprecationNoticeProps } from "./DeprecationNotice"
+import { Feedback } from "@/components/Feedback"

 const TagsOperationDescriptionSectionSecurity =
  dynamic<TagsOperationDescriptionSectionSecurityProps>(
@@ -58,9 +56,6 @@ type TagsOperationDescriptionSectionProps = {
 const TagsOperationDescriptionSection = ({
  operation,
 }: TagsOperationDescriptionSectionProps) => {
-  const { area } = useArea()
-  const pathname = usePathname()
-
  return (
    <>
      <H2>
@@ -127,14 +122,10 @@ const TagsOperationDescriptionSection = ({
        </>
      )}
      <Feedback
-        event="survey_api-ref"
        extraData={{
-          area,
          section: operation.summary,
        }}
-        pathName={pathname}
        className="!my-2"
-        vertical={true}
        question="Did this API Route run successfully?"
      />
      {operation.security && (
--- a/www/apps/api-reference/components/Tags/Section/index.tsx
+++ b/www/apps/api-reference/components/Tags/Section/index.tsx
@@ -19,8 +19,8 @@ import SectionContainer from "../../Section/Container"
 import { useArea } from "@/providers/area"
 import SectionDivider from "../../Section/Divider"
 import clsx from "clsx"
-import { Feedback, Loading, Link } from "docs-ui"
-import { usePathname, useRouter } from "next/navigation"
+import { Loading, Link } from "docs-ui"
+import { useRouter } from "next/navigation"
 import { OpenAPI } from "types"
 import TagSectionSchema from "./Schema"
 import checkElementInViewport from "../../../utils/check-element-in-viewport"
@@ -29,6 +29,7 @@ import useSWR from "swr"
 import basePathUrl from "../../../utils/base-path-url"
 import { getSectionId } from "docs-utils"
 import { RoutesSummary } from "./RoutesSummary"
+import { Feedback } from "../../Feedback"

 export type TagSectionProps = {
  tag: OpenAPI.TagObject
@@ -51,7 +52,6 @@ const TagSectionComponent = ({ tag }: TagSectionProps) => {
  const [loadData, setLoadData] = useState(false)
  const slugTagName = useMemo(() => getSectionId([tag.name]), [tag])
  const { area } = useArea()
-  const pathname = usePathname()
  const { scrollableElement, scrollToTop } = useScrollController()
  const { isBrowser } = useIsBrowser()

@@ -163,13 +163,9 @@ const TagSectionComponent = ({ tag }: TagSectionProps) => {
                </p>
              )}
              <Feedback
-                event="survey_api-ref"
                extraData={{
-                  area,
                  section: tag.name,
                }}
-                pathName={pathname}
-                vertical
                question="Was this section helpful?"
              />
            </div>
--- a/www/apps/api-reference/instrumentation-client.ts
+++ b/www/apps/api-reference/instrumentation-client.ts
@@ -0,0 +1,7 @@
+import posthog from "posthog-js"
+
+posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
+  api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+  person_profiles: "always",
+  defaults: "2025-05-24",
+})
--- a/www/apps/api-reference/markdown/admin.mdx
+++ b/www/apps/api-reference/markdown/admin.mdx
@@ -1,4 +1,5 @@
-import { Feedback, CodeTabs, CodeTab, H1 } from "docs-ui"
+import { CodeTabs, CodeTab, H1 } from "docs-ui"
+import { Feedback } from "@/components/Feedback"
 import SectionContainer from "@/components/Section/Container"
 import DividedMarkdownLayout from "@/layouts/DividedMarkdown"
 import { 
@@ -24,14 +25,10 @@ This API reference includes Medusa v2's Admin APIs, which are REST APIs exposed
 All API Routes are prefixed with `/admin`. So, during development, the API Routes will be available under the path `http://localhost:9000/admin`. For production, replace `http://localhost:9000` with your Medusa application URL.

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "admin",
    section: "introduction"
  }}
-  pathName="/api/admin"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownContent>
@@ -391,14 +388,10 @@ fetch(`<BACKEND_URL>/admin/products`, {
 <DividedMarkdownLayout addYSpacing>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "admin",
    section: "authentication-cookie"
  }}
-  pathName="/api/admin"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -463,14 +456,10 @@ x-no-compression: false
 <DividedMarkdownLayout addYSpacing>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "admin",
    section: "http-compression"
  }}
-  pathName="/api/admin"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -648,14 +637,10 @@ sdk.admin.product.update("prod_123", {
 To remove a property from the `metadata`, pass the property in the request body with an empty string value. This will remove the property from the `metadata` without affecting other properties.

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "metadata"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownContent>
@@ -942,14 +927,10 @@ However, some API routes restrict the fields and relations you can retrieve. To
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "admin",
    section: "select-fields"
  }}
-  pathName="/api/admin"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -1315,14 +1296,10 @@ curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17&created
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "admin",
    section: "query-parameters"
  }}
-  pathName="/api/admin"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -1496,14 +1473,10 @@ This sorts the products by their `created_at` field in the descending order.
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "admin",
    section: "pagination"
  }}
-  pathName="/api/admin"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -1527,14 +1500,10 @@ This is useful if you want to extend an API route and pass additional data or pe
 Refer to [this guide](!docs!/learn/customization/extend-features/extend-create-product) to find an example of extending an API route.

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "admin",
    section: "workflows"
  }}
-  pathName="/api/admin"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownContent>
--- a/www/apps/api-reference/markdown/store.mdx
+++ b/www/apps/api-reference/markdown/store.mdx
@@ -5,7 +5,8 @@ import {
  DividedMarkdownCode
 } from "@/layouts/DividedMarkdown/Sections"
 import Section from "@/components/Section"
-import { Feedback, CodeTabs, CodeTab, H1 } from "docs-ui"
+import { CodeTabs, CodeTab, H1 } from "docs-ui"
+import { Feedback } from "@/components/Feedback"

 import ClientLibraries from "./client-libraries.mdx"

@@ -24,14 +25,10 @@ This API reference includes Medusa v2's Store APIs, which are REST APIs exposed
 All API Routes are prefixed with `/store`. So, during development, the API Routes will be available under the path `http://localhost:9000/store`. For production, replace `http://localhost:9000` with your Medusa application URL.

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "introduction"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownContent>
@@ -264,14 +261,10 @@ fetch(`<BACKEND_URL>/store/products`, {
 <DividedMarkdownLayout addYSpacing>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "authentication-cookie"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -349,14 +342,10 @@ Where `{your_publishable_api_key}` is the token of the publishable API key. When
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "publishable-api-key"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -421,14 +410,10 @@ x-no-compression: false
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "http-compression"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -624,14 +609,10 @@ sdk.store.cart.updateLineItem(
 To remove a property from the `metadata`, pass the property in the request body with an empty string value. This will remove the property from the `metadata` without affecting other properties.

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "metadata"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownContent>
@@ -925,14 +906,10 @@ However, some API routes restrict the fields and relations you can retrieve. To
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "select-fields"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -1289,14 +1266,10 @@ curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17&created
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "query-parameters"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -1468,14 +1441,10 @@ This sorts the products by their `created_at` field in the descending order.
 <DividedMarkdownLayout>

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "pagination"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownLayout>
@@ -1499,14 +1468,10 @@ This is useful if you want to extend an API route and pass additional data or pe
 Refer to [this guide](!docs!/learn/customization/extend-features/extend-create-product) to find an example of extending an API route.

 <Feedback
-  event="survey_api-ref"
  extraData={{
-    area: "store",
    section: "workflows"
  }}
-  pathName="/api/store"
  question="Was this section helpful?"
-  vertical={true}
 />

 </DividedMarkdownContent>
--- a/www/apps/api-reference/package.json
+++ b/www/apps/api-reference/package.json
@@ -34,6 +34,7 @@
    "openapi-sampler": "^1.3.1",
    "pluralize": "^8.0.0",
    "postcss": "8.4.27",
+    "posthog-js": "^1.269.1",
    "prism-react-renderer": "2.4.0",
    "react": "rc",
    "react-dom": "rc",
--- a/www/apps/api-reference/providers/index.tsx
+++ b/www/apps/api-reference/providers/index.tsx
@@ -19,8 +19,6 @@ const Providers = ({ children }: ProvidersProps) => {
    <AnalyticsProvider
      segmentWriteKey={process.env.NEXT_PUBLIC_SEGMENT_API_KEY}
      reoDevKey={process.env.NEXT_PUBLIC_REO_DEV_CLIENT_ID}
-      postHogKey={process.env.NEXT_PUBLIC_POSTHOG_KEY}
-      postHogApiHost={process.env.NEXT_PUBLIC_POSTHOG_HOST}
    >
      <SiteConfigProvider config={config}>
        <PageLoadingProvider>
--- a/www/apps/api-reference/vercel.json
+++ b/www/apps/api-reference/vercel.json
@@ -6,6 +6,5 @@
  "framework": "nextjs",
  "installCommand": "yarn install",
  "buildCommand": "turbo run build",
-  "outputDirectory": ".next",
-  "ignoreCommand": "bash ../../ignore-build-script.sh api-reference"
+  "outputDirectory": ".next"
 }