@posthog/react 1.7.0 → 1.8.0

package/src/hooks/__tests__/useThumbSurvey.test.tsx

@@ -0,0 +1,105 @@
+import * as React from 'react'
+import { renderHook, act } from '@testing-library/react'
+import { PostHogProvider, PostHog } from '../../context'
+import { useThumbSurvey } from '../useThumbSurvey'
+import { SurveyEventName, SurveyEventProperties } from 'posthog-js'
+import { isUndefined } from '../../utils/type-utils'
+
+jest.useFakeTimers()
+
+describe('useThumbSurvey hook', () => {
+    let posthog: PostHog
+    let captureMock: jest.Mock
+    let displaySurveyMock: jest.Mock
+    let wrapper: React.FC<{ children: React.ReactNode }>
+
+    beforeEach(() => {
+        captureMock = jest.fn()
+        displaySurveyMock = jest.fn()
+
+        posthog = {
+            capture: captureMock,
+            get_session_replay_url: () => 'https://app.posthog.com/replay/123',
+            surveys: { displaySurvey: displaySurveyMock },
+        } as unknown as PostHog
+
+        wrapper = ({ children }) => <PostHogProvider client={posthog}>{children}</PostHogProvider>
+    })
+
+    describe('survey shown tracking', () => {
+        it.each([
+            [false, true, false], // disableAutoShownTracking, shouldAutoTrack, shouldExposeTrackShown
+            [true, false, true],
+        ])(
+            'disableAutoShownTracking=%s: auto-tracks=%s, exposes trackShown=%s',
+            (disableAutoShownTracking, shouldAutoTrack, shouldExposeTrackShown) => {
+                const { result } = renderHook(
+                    () => useThumbSurvey({ surveyId: 'test-survey', disableAutoShownTracking }),
+                    { wrapper }
+                )
+
+                expect(captureMock).toHaveBeenCalledTimes(shouldAutoTrack ? 1 : 0)
+                expect(!isUndefined(result.current.trackShown)).toBe(shouldExposeTrackShown)
+            }
+        )
+
+        it('should only emit survey shown once when trackShown is called multiple times', () => {
+            const { result } = renderHook(
+                () => useThumbSurvey({ surveyId: 'test-survey', disableAutoShownTracking: true }),
+                { wrapper }
+            )
+
+            act(() => {
+                result.current.trackShown?.()
+                result.current.trackShown?.()
+            })
+
+            expect(captureMock).toHaveBeenCalledTimes(1)
+            expect(captureMock).toHaveBeenCalledWith(SurveyEventName.SHOWN, {
+                [SurveyEventProperties.SURVEY_ID]: 'test-survey',
+                sessionRecordingUrl: 'https://app.posthog.com/replay/123',
+            })
+        })
+    })
+
+    describe('respond', () => {
+        it.each([
+            ['up', 1],
+            ['down', 2],
+        ] as const)('respond("%s") calls displaySurvey with initialResponses: { 0: %d }', (value, expectedResponse) => {
+            const { result } = renderHook(() => useThumbSurvey({ surveyId: 'test-survey' }), { wrapper })
+
+            act(() => {
+                result.current.respond(value)
+            })
+
+            expect(displaySurveyMock).toHaveBeenCalledWith(
+                'test-survey',
+                expect.objectContaining({ initialResponses: { 0: expectedResponse } })
+            )
+        })
+
+        it('should only allow one response', () => {
+            const { result } = renderHook(() => useThumbSurvey({ surveyId: 'test-survey' }), { wrapper })
+
+            act(() => {
+                result.current.respond('up')
+                result.current.respond('down')
+            })
+
+            expect(displaySurveyMock).toHaveBeenCalledTimes(1)
+            expect(result.current.response).toBe('up')
+        })
+
+        it('should call onResponse callback', () => {
+            const onResponse = jest.fn()
+            const { result } = renderHook(() => useThumbSurvey({ surveyId: 'test-survey', onResponse }), { wrapper })
+
+            act(() => {
+                result.current.respond('down')
+            })
+
+            expect(onResponse).toHaveBeenCalledWith('down')
+        })
+    })
+})

package/src/hooks/index.ts

@@ -1,5 +1,6 @@
 export * from './useFeatureFlagEnabled'
 export * from './useFeatureFlagPayload'
+export * from './useFeatureFlagResult'
 export * from './useActiveFeatureFlags'
 export * from './useFeatureFlagVariantKey'
 export * from './usePostHog'

package/src/hooks/useFeatureFlagResult.ts

@@ -0,0 +1,31 @@
+import { FeatureFlagResult } from 'posthog-js'
+import { useContext, useEffect, useState } from 'react'
+import { PostHogContext } from '../context'
+import { isUndefined } from '../utils/type-utils'
+
+export function useFeatureFlagResult(flag: string): FeatureFlagResult | undefined {
+    const { client, bootstrap } = useContext(PostHogContext)
+
+    const [result, setResult] = useState<FeatureFlagResult | undefined>(() => client.getFeatureFlagResult(flag))
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setResult(client.getFeatureFlagResult(flag))
+        })
+    }, [client, flag])
+
+    if (!client?.featureFlags?.hasLoadedFlags && bootstrap?.featureFlags) {
+        const bootstrappedValue = bootstrap.featureFlags[flag]
+        if (isUndefined(bootstrappedValue)) {
+            return undefined
+        }
+        return {
+            key: flag,
+            enabled: typeof bootstrappedValue === 'string' ? true : !!bootstrappedValue,
+            variant: typeof bootstrappedValue === 'string' ? bootstrappedValue : undefined,
+            payload: bootstrap.featureFlagPayloads?.[flag],
+        }
+    }
+
+    return result
+}

package/src/hooks/useThumbSurvey.ts

@@ -1,6 +1,6 @@
-import { useState, useCallback, useRef, useMemo, type RefCallback } from 'react'
+import { useState, useCallback, useRef, useMemo, type RefCallback, useEffect } from 'react'
 import { usePostHog } from './usePostHog'
-import { DisplaySurveyType, SurveyPosition } from 'posthog-js'
+import { DisplaySurveyType, SurveyEventName, SurveyEventProperties, SurveyPosition } from 'posthog-js'
 
 export interface UseThumbSurveyOptions {
     /** ID of the target PostHog survey */
@@ -11,6 +11,8 @@ export interface UseThumbSurveyOptions {
     properties?: Record<string, any>
     /** Callback on thumb button click */
     onResponse?: (response: 'up' | 'down') => void
+    /** Disable automatically emitting `survey shown` on hook mount. Defaults to false. */
+    disableAutoShownTracking?: boolean
 }
 
 export interface UseThumbSurveyResult {
@@ -20,6 +22,8 @@ export interface UseThumbSurveyResult {
     response: 'up' | 'down' | null
     /** Ref to attach to the trigger element for positioning the followup survey popup */
     triggerRef: RefCallback<HTMLElement>
+    /** Method to manually trigger a `survey shown` event. Only available when disableAutoShownTracking is true. */
+    trackShown?: () => void
 }
 
 const TRIGGER_ATTR = 'data-ph-thumb-survey-trigger'
@@ -60,6 +64,8 @@ const TRIGGER_ATTR = 'data-ph-thumb-survey-trigger'
  * Notes:
  * - The thumbs up/down response will ALWAYS be recorded, whether your survey is set to collect partial responses or not.
  * - By default, followup questions will be displayed as a pop-up next to the triggerRef. Use options.position to change the position.
+ * - By default, `survey shown` is emitted automatically on hook mount. To prevent this behavior, set `disableAutoShownTracking: true`,
+ *   and manually call `trackShown()` when you want to emit this event.
  *
  * @param options UseThumbSurveyOptions
  * @returns UseThumbSurveyResult
@@ -69,6 +75,7 @@ export function useThumbSurvey({
     displayPosition = SurveyPosition.NextToTrigger,
     properties,
     onResponse,
+    disableAutoShownTracking,
 }: UseThumbSurveyOptions): UseThumbSurveyResult {
     const posthog = usePostHog()
     const [responded, setResponded] = useState<'up' | 'down' | null>(null)
@@ -89,9 +96,29 @@ export function useThumbSurvey({
         [triggerValue]
     )
 
+    const shownRef = useRef(false)
+    const respondedRef = useRef(false)
+
+    const trackShown = useCallback(() => {
+        if (shownRef.current || !posthog) return
+        shownRef.current = true
+        posthog.capture(SurveyEventName.SHOWN, {
+            [SurveyEventProperties.SURVEY_ID]: surveyId,
+            sessionRecordingUrl: posthog.get_session_replay_url?.(),
+            ...properties,
+        })
+    }, [posthog, surveyId, properties])
+
+    useEffect(() => {
+        if (!disableAutoShownTracking) {
+            trackShown()
+        }
+    }, [trackShown, disableAutoShownTracking])
+
     const respond = useCallback(
         (value: 'up' | 'down') => {
-            if (!posthog?.surveys || responded) return
+            if (!posthog?.surveys || respondedRef.current) return
+            respondedRef.current = true
 
             setResponded(value)
             onResponse?.(value)
@@ -104,10 +131,16 @@ export function useThumbSurvey({
                 initialResponses: { 0: value === 'up' ? 1 : 2 },
                 position: displayPosition,
                 selector: `[${TRIGGER_ATTR}="${triggerValue}"]`,
+                skipShownEvent: true,
             })
         },
-        [posthog, surveyId, displayPosition, properties, responded, onResponse, triggerValue]
+        [posthog, surveyId, displayPosition, properties, onResponse, triggerValue]
     )
 
-    return { respond, response: responded, triggerRef }
+    return {
+        respond,
+        response: responded,
+        triggerRef,
+        ...(disableAutoShownTracking && { trackShown }),
+    }
 }