feat(product tours): add tour wait period config

Author: adboio

.changeset/bumpy-words-stand.md

@@ -0,0 +1,5 @@
+---
+'posthog-js': minor
+---
+
+add product tour wait period support

packages/browser/src/__tests__/extensions/product-tours-utils.test.ts

@@ -3,8 +3,10 @@ import {
     getSpotlightStyle,
     renderTipTapContent,
     normalizeUrl,
+    hasTourWaitPeriodPassed,
 } from '../../extensions/product-tours/product-tours-utils'
 import { doesTourActivateByEvent, doesTourActivateByAction } from '../../utils/product-tour-utils'
+import { LAST_SEEN_TOUR_DATE_KEY_PREFIX } from '../../extensions/product-tours/constants'
 
 describe('calculateTooltipPosition', () => {
     const mockWindow = {
@@ -248,3 +250,43 @@ describe('doesTourActivateByAction', () => {
         expect(doesTourActivateByAction(tour)).toBe(false)
     })
 })
+
+describe('hasTourWaitPeriodPassed', () => {
+    beforeEach(() => localStorage.clear())
+
+    const setLastSeen = (type: string, daysAgo: number) => {
+        const date = new Date()
+        date.setDate(date.getDate() - daysAgo)
+        localStorage.setItem(`${LAST_SEEN_TOUR_DATE_KEY_PREFIX}${type}`, JSON.stringify(date.toISOString()))
+    }
+
+    it.each([
+        ['no config', undefined, true],
+        ['days is 0', { days: 0, types: ['tour' as const] }, true],
+        ['empty types', { days: 7, types: [] }, true],
+        ['no stored date', { days: 7, types: ['tour' as const] }, true],
+    ])('returns true when %s', (_desc, config, expected) => {
+        expect(hasTourWaitPeriodPassed(config)).toBe(expected)
+    })
+
+    it('returns false when within the wait period', () => {
+        setLastSeen('tour', 0)
+        expect(hasTourWaitPeriodPassed({ days: 7, types: ['tour'] })).toBe(false)
+    })
+
+    it('returns true when past the wait period', () => {
+        setLastSeen('tour', 10)
+        expect(hasTourWaitPeriodPassed({ days: 7, types: ['tour'] })).toBe(true)
+    })
+
+    it('ignores types not in the config', () => {
+        setLastSeen('announcement', 0)
+        expect(hasTourWaitPeriodPassed({ days: 7, types: ['tour'] })).toBe(true)
+    })
+
+    it('uses the most recent date across multiple types', () => {
+        setLastSeen('tour', 10)
+        setLastSeen('announcement', 0)
+        expect(hasTourWaitPeriodPassed({ days: 7, types: ['tour', 'announcement'] })).toBe(false)
+    })
+})

packages/browser/src/__tests__/posthog-core.test.ts

@@ -2,6 +2,7 @@ import { defaultPostHog } from './helpers/posthog-instance'
 import type { PostHogConfig } from '../types'
 import { uuidv7 } from '../uuidv7'
 import { SurveyEventName, SurveyEventProperties } from '../posthog-surveys-types'
+import { ProductTourEventName, ProductTourEventProperties } from '../posthog-product-tours-types'
 import { SURVEY_SEEN_PREFIX } from '../utils/survey-utils'
 import { beforeEach } from '@jest/globals'
 
@@ -376,6 +377,52 @@ describe('posthog core', () => {
         })
     })
 
+    describe('product tour capture()', () => {
+        const setup = (config: Partial<PostHogConfig> = {}, token: string = uuidv7()) => {
+            const beforeSendMock = jest.fn().mockImplementation((e) => e)
+            const posthog = defaultPostHog().init(token, { ...config, before_send: beforeSendMock }, token)!
+            return { posthog, beforeSendMock }
+        }
+
+        it('sending product tour shown events with tour_type should set type-specific last seen date property', () => {
+            // arrange
+            const { posthog, beforeSendMock } = setup({ debug: false })
+
+            // act
+            posthog.capture(ProductTourEventName.SHOWN, {
+                [ProductTourEventProperties.TOUR_ID]: 'testTour1',
+                [ProductTourEventProperties.TOUR_NAME]: 'Test Tour',
+                [ProductTourEventProperties.TOUR_TYPE]: 'tour',
+            })
+
+            // assert
+            const capturedEvent = beforeSendMock.mock.calls[0][0]
+            expect(capturedEvent.$set).toBeDefined()
+            const typeSpecificKey = `${ProductTourEventProperties.TOUR_LAST_SEEN_DATE}/tour`
+            expect(capturedEvent.$set[typeSpecificKey]).toBeDefined()
+            // Verify it's a valid ISO date string
+            expect(new Date(capturedEvent.$set[typeSpecificKey]).toISOString()).toBe(
+                capturedEvent.$set[typeSpecificKey]
+            )
+        })
+
+        it('sending product tour shown events without tour_type should not set last seen date property', () => {
+            // arrange
+            const { posthog, beforeSendMock } = setup({ debug: false })
+
+            // act
+            posthog.capture(ProductTourEventName.SHOWN, {
+                [ProductTourEventProperties.TOUR_ID]: 'testTour1',
+                [ProductTourEventProperties.TOUR_NAME]: 'Test Tour',
+            })
+
+            // assert
+            const capturedEvent = beforeSendMock.mock.calls[0][0]
+            // No $set should be added when tour_type is missing
+            expect(capturedEvent.$set).toBeUndefined()
+        })
+    })
+
     describe('setInternalOrTestUser()', () => {
         const setup = (config: Partial<PostHogConfig> = {}, token: string = uuidv7()) => {
             const beforeSendMock = jest.fn().mockImplementation((e) => e)

packages/browser/src/extensions/product-tours/constants.ts

@@ -2,3 +2,4 @@ export const TOUR_SHOWN_KEY_PREFIX = 'ph_product_tour_shown_'
 export const TOUR_COMPLETED_KEY_PREFIX = 'ph_product_tour_completed_'
 export const TOUR_DISMISSED_KEY_PREFIX = 'ph_product_tour_dismissed_'
 export const ACTIVE_TOUR_SESSION_KEY = 'ph_active_product_tour'
+export const LAST_SEEN_TOUR_DATE_KEY_PREFIX = 'ph_last_seen_tour_date_'

packages/browser/src/extensions/product-tours/product-tours-utils.ts

@@ -6,11 +6,14 @@ import {
     ProductTourSelectorError,
     ProductTourStep,
     DEFAULT_PRODUCT_TOUR_APPEARANCE,
+    ProductTourWaitPeriod,
 } from '../../posthog-product-tours-types'
 import { findElement } from './element-inference'
 import { prepareStylesheet } from '../utils/stylesheet-loader'
 import { document as _document, window as _window } from '../../utils/globals'
 import { getFontFamily, getContrastingTextColor, hexToRgba } from '../surveys/surveys-extension-utils'
+import { localStore } from '../../storage'
+import { LAST_SEEN_TOUR_DATE_KEY_PREFIX } from './constants'
 
 import productTourStyles from './product-tour.css'
 
@@ -309,3 +312,40 @@ export function getStepHtml(step: ProductTourStep): string {
     // backwards compat, will be deprecated
     return renderTipTapContent(step.content)
 }
+
+export function hasTourWaitPeriodPassed(seenTourWaitPeriod?: ProductTourWaitPeriod): boolean {
+    if (!seenTourWaitPeriod) {
+        return true
+    }
+
+    const { days, types } = seenTourWaitPeriod
+    if (!days || !types || types.length === 0) {
+        return true
+    }
+
+    let mostRecentDate: Date | null = null
+
+    for (const type of types) {
+        const raw = localStore._get(`${LAST_SEEN_TOUR_DATE_KEY_PREFIX}${type}`)
+        if (raw) {
+            try {
+                const stored = JSON.parse(raw)
+                const date = new Date(stored)
+                if (!isNaN(date.getTime()) && (!mostRecentDate || date > mostRecentDate)) {
+                    mostRecentDate = date
+                }
+            } catch {
+                // ignore malformed entries
+            }
+        }
+    }
+
+    if (!mostRecentDate) {
+        return true
+    }
+
+    const now = new Date()
+    const diffMs = Math.abs(now.getTime() - mostRecentDate.getTime())
+    const diffDays = Math.ceil(diffMs / (1000 * 3600 * 24))
+    return diffDays > days
+}

packages/browser/src/extensions/product-tours/product-tours.tsx

@@ -20,6 +20,7 @@ import {
     getProductTourStylesheet,
     getStepImageUrls,
     hasElementTarget,
+    hasTourWaitPeriodPassed,
     normalizeUrl,
 } from './product-tours-utils'
 import { ProductTourTooltip } from './components/ProductTourTooltip'
@@ -35,6 +36,7 @@ import {
     TOUR_COMPLETED_KEY_PREFIX,
     TOUR_DISMISSED_KEY_PREFIX,
     ACTIVE_TOUR_SESSION_KEY,
+    LAST_SEEN_TOUR_DATE_KEY_PREFIX,
 } from './constants'
 import { doesTourActivateByAction, doesTourActivateByEvent } from '../../utils/product-tour-utils'
 import { TOOLBAR_ID } from '../../constants'
@@ -436,6 +438,13 @@ export class ProductTourManager {
                 break
         }
 
+        if (!hasTourWaitPeriodPassed(tour.conditions?.seenTourWaitPeriod)) {
+            logger.info(
+                `Cannot show tour ${tour.id} until user has not seen any ${tour.conditions?.seenTourWaitPeriod?.types} within ${tour.conditions?.seenTourWaitPeriod?.days} days.`
+            )
+            return false
+        }
+
         if (!this._isProductToursFeatureFlagEnabled({ flagKey: tour.internal_targeting_flag_key })) {
             logger.info(`Tour ${tour.id} failed feature flag check: ${tour.internal_targeting_flag_key}`)
             return false
@@ -470,10 +479,12 @@ export class ProductTourManager {
                 [ProductTourEventProperties.TOUR_NAME]: tour.name,
                 [ProductTourEventProperties.TOUR_ITERATION]: tour.current_iteration || 1,
                 [ProductTourEventProperties.TOUR_RENDER_REASON]: renderReason,
+                [ProductTourEventProperties.TOUR_TYPE]: tour.tour_type,
             })
 
             if (!this._isPreviewMode) {
                 localStore._set(`${TOUR_SHOWN_KEY_PREFIX}${tour.id}`, true)
+                localStore._set(`${LAST_SEEN_TOUR_DATE_KEY_PREFIX}${tour.tour_type}`, new Date().toISOString())
 
                 this._instance.capture('$set', {
                     $set: { [`$product_tour_shown/${tour.id}`]: true },
@@ -1053,7 +1064,8 @@ export class ProductTourManager {
             if (
                 key?.startsWith(TOUR_SHOWN_KEY_PREFIX) ||
                 key?.startsWith(TOUR_COMPLETED_KEY_PREFIX) ||
-                key?.startsWith(TOUR_DISMISSED_KEY_PREFIX)
+                key?.startsWith(TOUR_DISMISSED_KEY_PREFIX) ||
+                key?.startsWith(LAST_SEEN_TOUR_DATE_KEY_PREFIX)
             ) {
                 keysToRemove.push(key)
             }

packages/browser/src/posthog-core.ts

@@ -34,6 +34,7 @@ import {
     SurveyEventProperties,
     SurveyRenderReason,
 } from './posthog-surveys-types'
+import { ProductTourEventName, ProductTourEventProperties } from './posthog-product-tours-types'
 import { PostHogLogs } from './posthog-logs'
 import { RateLimiter } from './rate-limiter'
 import { RemoteConfigLoader } from './remote-config'
@@ -1219,6 +1220,16 @@ export class PostHog implements PostHogInterface {
             }
         }
 
+        if (event_name === ProductTourEventName.SHOWN) {
+            const tourType = properties?.[ProductTourEventProperties.TOUR_TYPE]
+            if (tourType) {
+                data.$set = {
+                    ...data.$set,
+                    [`${ProductTourEventProperties.TOUR_LAST_SEEN_DATE}/${tourType}`]: new Date().toISOString(),
+                }
+            }
+        }
+
         // Top-level $set overriding values from the one from properties is taken from the plugin-server normalizeEvent
         // This doesn't handle $set_once, because posthog-people doesn't either
         const finalSet = { ...data.properties['$set'], ...data['$set'] }

packages/browser/src/posthog-product-tours-types.ts

@@ -86,6 +86,14 @@ export interface ProductTourStep {
     bannerConfig?: ProductTourBannerConfig
 }
 
+/** maps to main repo EffectiveProductTourType */
+export type ProductTourType = 'tour' | 'announcement' | 'banner'
+
+export interface ProductTourWaitPeriod {
+    days: number
+    types: ProductTourType[]
+}
+
 export interface ProductTourConditions {
     url?: string
     urlMatchType?: PropertyMatchType
@@ -101,6 +109,7 @@ export interface ProductTourConditions {
         values: SurveyActionType[]
     } | null
     linkedFlagVariant?: string
+    seenTourWaitPeriod?: ProductTourWaitPeriod
 }
 
 export interface ProductTourAppearance {
@@ -125,7 +134,7 @@ export interface ProductTour {
     id: string
     name: string
     description?: string
-    type: 'product_tour'
+    tour_type: ProductTourType // inferred in API based on tour content
     auto_launch?: boolean
     start_date: string | null
     end_date: string | null
@@ -212,4 +221,6 @@ export enum ProductTourEventProperties {
     TOUR_LINKED_SURVEY_ID = '$product_tour_linked_survey_id',
     USE_MANUAL_SELECTOR = '$use_manual_selector',
     INFERENCE_DATA_PRESENT = '$inference_data_present',
+    TOUR_LAST_SEEN_DATE = '$product_tour_last_seen_date',
+    TOUR_TYPE = '$product_tour_type',
 }