@playpilot/tpi 8.9.2 → 8.10.0

package/events.md

@@ -26,6 +26,10 @@ Events related to titles share an additional set of data (referred to below as `
 
 Events may have additional data in their payload.
 
+If user tracking is allowed the following is added to all events:
+- `user_id`: A unique id per user that is saved in localStorage
+- `region`: Region derived from the users ip
+
 ### General
 Event | Action | Info | Payload
 --- | --- | --- | ---
@@ -44,8 +48,8 @@ Event | Action | Info | Payload
 `ali_title_modal_save_click` | _Currently unused, there is no save functionality._ | | `Title`
 `ali_participant_modal_view` | _Fires any time a title modal is viewed_ | The title modal opens when viewing a participant modal both on desktop and mobile | `participant` (name of the participant)
 `ali_participant_modal_close` | _Fires any time a title modal is closed_ | | `participant` (name of the participant) `time_spent` (time between modal_view and modal_close milliseconds)
-'ali_similar_title_click' | _Fires any time a similar titles rail item is clicked_ | Title | `title_source` (original name of the title the rail item was clicked in)
-'ali_participant_click' | _Fires any time a participants rail item is clicked_ | null | `title_source` (original name of the title the rail item was clicked in), `participant` (name of the clicked participant)
+`ali_similar_title_click` | _Fires any time a similar titles rail item is clicked_ | Title | `title_source` (original name of the title the rail item was clicked in)
+`ali_participant_click` | _Fires any time a participants rail item is clicked_ | null | `title_source` (original name of the title the rail item was clicked in), `participant` (name of the clicked participant)
 
 ### Popover
 Event | Action | Info | Payload
@@ -109,12 +113,14 @@ Event | Action | Info | Payload
 ### Explore
 Event | Action | Info | Payload
 --- | --- | --- | ---
-`explore_page_view` | _Fires any time explore is loaded_ | This always fires when explore is first shown, regardless of if anything loads | | -
-`explore_title_click` | _Fires any time a title is clicked on explore_ | Includes both desktop and mobile titles | `Title`
-`explore_show_more` | _Fires when "show more" is clicked on explore_ | | `page` (The current page number) |
-`explore_set_filter` | _Fires when any filter is set on the explore page._ | This includes any filter type, including sorting. | `key` (the name of the current filter being set), `value`, `total_filter` (all currently active filter items)
-`explore_search` | _Fires any time the user searches for something_ | | `query`
+`venus_page_view` | _Fires any time explore is loaded_ | This always fires when explore is first shown, regardless of if anything loads | | -
+`venus_title_click` | _Fires any time a title is clicked on explore_ | Includes both desktop and mobile titles | `Title`
+`venus_show_more` | _Fires when "show more" is clicked on explore_ | | `page` (The current page number) |
+`venus_set_filter` | _Fires when any filter is set on the explore page._ | This includes any filter type, including sorting. | `key` (the name of the current filter being set), `value`, `total_filter` (all currently active filter items)
+`venus_search` | _Fires any time the user searches for something_ | | `query`
 `venus_title_rail_modal_view` | _Fires any time a title is clicked in a rail, opening the rail modal_ | | `rail` (heading key of the rail)
 `venus_title_rail_expand_click` | _Fires any time a title is expanded in a rail directly via a click_ | Does not fire when a title opens automatically on load or navigate | `Title`, `rail` (heading key of the rail)
 `venus_title_rail_set_index` | _Fires when navigating in the titles rail modal, either via arrows, swipe, or clicking titles_ | | `Title`, `index` (index of the new position of the slider)
 `venus_navigate` | _Fires when navigating on the explore page_ | Does not fire on initial load | `route` (the key of the given route)
+`venus_any_click` | _Fires on any click anywhere_ | | `selector` (parent > child selector of the clicked element), `text` (direct text content of the clicked element, limited to 30 characters)
+`venus_scroll_distance` | _Fires on increments of scroll distance_ | 25%, 50%, 75%, 100% | `scroll_percentage` (percentage of the explore element the user has seen)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@playpilot/tpi",
-	"version": "8.9.2",
+	"version": "8.10.0",
 	"type": "module",
 	"scripts": {
 		"dev": "vite dev",

package/src/lib/enums/TrackingEvent.ts

@@ -77,6 +77,8 @@ export const TrackingEvent = {
   ExploreTitleRailExpandClick: 'venus_title_rail_expand_click',
   ExploreTitleRailSetIndex: 'venus_title_rail_set_index',
   ExploreNavigate: 'venus_navigate',
+  ExploreAnyClick: 'venus_any_click',
+  ExploreScrollDistance: 'venus_scroll_distance',
 } as const
 
 export const MetaEvent = {

package/src/lib/tracking.ts

@@ -39,6 +39,7 @@ export async function track(event: string, title: TitleData | null = null, paylo
 
   if (isUserTrackingAllowed()) {
     payload.user_id = getUserId()
+    payload.region = window.PlayPilotLinkInjections.region
   }
 
   payload.version = __SCRIPT_VERSION__

package/src/lib/user.ts

@@ -1,3 +1,4 @@
+import { hasConsentedTo } from './consent'
 import { generateRandomHash } from './hash'
 
 export const localStorageUserKey = 'playpilot_user_id'
@@ -17,5 +18,5 @@ export function getUserId(): string | null {
 }
 
 export function isUserTrackingAllowed(): boolean {
-  return !!window.PlayPilotLinkInjections?.config?.allow_user_id_tracking
+  return !!window.PlayPilotLinkInjections?.config?.allow_user_id_tracking && hasConsentedTo('tracking')
 }

package/src/routes/components/Explore/ExploreLayout.svelte

@@ -9,6 +9,8 @@
   import { onMount, type Snippet } from 'svelte'
   import Search from './Filter/Search.svelte'
   import Filter from './Filter/Filter.svelte'
+  import TrackAnyClick from '../TrackAnyClick.svelte'
+  import TrackScrollDistance from '../TrackScrollDistance.svelte'
 
   interface Props {
     navigate?: (key: string) => void
@@ -70,6 +72,9 @@
   {@render children()}
 </div>
 
+<TrackAnyClick />
+<TrackScrollDistance {element} />
+
 <style lang="scss">
   .explore {
     background: theme(explore-background, light);

package/src/routes/components/TrackAnyClick.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+  import { TrackingEvent } from '$lib/enums/TrackingEvent'
+  import { track } from '$lib/tracking'
+
+  interface Props {
+    trackingEvent?: string
+  }
+
+  const { trackingEvent = TrackingEvent.ExploreAnyClick }: Props = $props()
+
+  function onclick(event: MouseEvent): void {
+    const target = event.target as Element
+    const parent = target.parentElement as Element
+
+    if (target === document.body) return
+
+    const parentSelector = `${parent?.nodeName.toLowerCase()}${getClasslistAsString(parent)}`
+    const targetSelector = `${target?.nodeName.toLowerCase()}${getClasslistAsString(target)}`
+    const selector = `${parentSelector} > ${targetSelector}`
+
+    const hasDirectTextContent = Array.from(target.childNodes).some(node => node.nodeName === '#text' && !!node.nodeValue?.trim())
+    const text = hasDirectTextContent ? target.textContent.slice(0, 30) : ''
+
+    track(trackingEvent, null, { selector, text })
+  }
+
+  function getClasslistAsString(element: Element): string {
+    if (!element) return ''
+
+    const classnames = Array.from(element.classList).filter(classname => !classname.startsWith('s-'))
+
+    if (!classnames.length) return ''
+
+    return '.' + classnames.join('.')
+  }
+</script>
+
+<svelte:window {onclick} />

package/src/routes/components/TrackScrollDistance.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+  import { TrackingEvent } from '$lib/enums/TrackingEvent'
+  import { track } from '$lib/tracking'
+
+  interface Props {
+    element: Element
+    trackingEvent?: string
+  }
+
+  const { element, trackingEvent = TrackingEvent.ExploreScrollDistance }: Props = $props()
+
+  const visibilityTrackingPercentages: Record<string, boolean> = {
+    '25': false,
+    '50': false,
+    '75': false,
+    '100': false,
+  }
+
+  function onscroll(): void {
+    const scrollDistance = window.scrollY
+    const windowHeight = window.innerHeight
+    const elementHeight = element.clientHeight
+    const elementBottomDistance = elementHeight + scrollDistance + element.getBoundingClientRect().top
+
+    const totalVisibilityPercentage = 100 / elementBottomDistance * (scrollDistance + windowHeight)
+
+    for (const percentage in visibilityTrackingPercentages) {
+      if (visibilityTrackingPercentages[percentage]) continue
+      if (totalVisibilityPercentage < parseInt(percentage)) continue
+
+      visibilityTrackingPercentages[percentage] = true
+
+      track(trackingEvent, null, { scroll_percentage: percentage + '%' })
+    }
+  }
+</script>
+
+<svelte:window {onscroll} />

package/src/tests/lib/user.test.js

@@ -1,5 +1,10 @@
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
 import { getUserId, isUserTrackingAllowed, localStorageUserKey } from '$lib/user'
+import { hasConsentedTo } from '$lib/consent'
+
+vi.mock('$lib/consent', () => ({
+  hasConsentedTo: vi.fn(() => true),
+}))
 
 describe('user.ts', () => {
   describe('getUserId', () => {
@@ -10,6 +15,8 @@ describe('user.ts', () => {
           allow_user_id_tracking: true,
         },
       }
+
+      vi.mocked(hasConsentedTo).mockImplementation(() => true)
     })
 
     it('Should return random hash by default', () => {
@@ -53,5 +60,12 @@ describe('user.ts', () => {
     it('Should return false if user tracking is not allowed', () => {
       expect(isUserTrackingAllowed()).toBe(false)
     })
+
+    it('Should return false if user tracking is allowed but user has not consented', () => {
+      window.PlayPilotLinkInjections.config = { allow_user_id_tracking: true }
+      vi.mocked(hasConsentedTo).mockImplementationOnce(() => false)
+
+      expect(isUserTrackingAllowed()).toBe(false)
+    })
   })
 })

package/src/tests/routes/components/TrackAnyClick.test.js

@@ -0,0 +1,107 @@
+import { render, fireEvent } from '@testing-library/svelte'
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { track } from '$lib/tracking'
+import { TrackingEvent } from '$lib/enums/TrackingEvent'
+import ClickTracking from '../../../routes/components/TrackAnyClick.svelte'
+
+vi.mock('$lib/tracking', () => ({
+  track: vi.fn(),
+}))
+
+describe('TrackAnyClick.svelte', () => {
+  beforeEach(() => {
+    document.body.innerHTML = ''
+    vi.resetAllMocks()
+  })
+
+  it('Should call track with the correct selector and text content on click', async () => {
+    document.body.innerHTML = '<button class="some-button">Some button</button>'
+
+    const { getByRole } = render(ClickTracking)
+
+    await fireEvent.click(getByRole('button'))
+
+    expect(track).toHaveBeenCalledWith(TrackingEvent.ExploreAnyClick, null, { selector: 'body > button.some-button', text: 'Some button' })
+  })
+
+  it('Should not call track when body is clicked', async () => {
+    // @ts-ignore
+    await fireEvent.click(document.querySelector('body'))
+
+    expect(track).not.toHaveBeenCalled()
+  })
+
+  it('Should limit text to 30 characters', async () => {
+    document.body.innerHTML = '<button class="some-button">This is a very long text that exceeds thirty characters</button>'
+
+    const { getByRole } = render(ClickTracking)
+
+    await fireEvent.click(getByRole('button'))
+
+    expect(track).toHaveBeenCalledWith(
+      TrackingEvent.ExploreAnyClick,
+      null,
+      expect.objectContaining({
+        text: 'This is a very long text that ',
+      }),
+    )
+  })
+
+  it('Should not include text when element has no direct text node', async () => {
+    document.body.innerHTML = '<button><span>Some text</span></button>'
+
+    const { getByRole } = render(ClickTracking)
+
+    await fireEvent.click(getByRole('button'))
+
+    expect(track).toHaveBeenCalledWith(
+      TrackingEvent.ExploreAnyClick,
+      null,
+      expect.objectContaining({
+        text: '',
+      }),
+    )
+  })
+
+  it('Should include class names in the selector', async () => {
+    document.body.innerHTML = '<div class="some element"><button class="some button">Some text</button></div>'
+
+    const { getByRole } = render(ClickTracking)
+
+    await fireEvent.click(getByRole('button'))
+
+    expect(track).toHaveBeenCalledWith(
+      TrackingEvent.ExploreAnyClick,
+      null,
+      expect.objectContaining({
+        selector: 'div.some.element > button.some.button',
+      }),
+    )
+  })
+
+  it('Should filter out svelte-generated s- classes from selector', async () => {
+    document.body.innerHTML = '<div class="some element s-abc"><button class="some button s-123">Some text</button></div>'
+
+    const { getByRole } = render(ClickTracking)
+
+    await fireEvent.click(getByRole('button'))
+
+    expect(track).toHaveBeenCalledWith(
+      TrackingEvent.ExploreAnyClick,
+      null,
+      expect.objectContaining({
+        selector: 'div.some.element > button.some.button',
+      }),
+    )
+  })
+
+  it('Should build selector without classes when element has none', async () => {
+    document.body.innerHTML = '<section><p>Some text</p></section>'
+
+    const { getByRole } = render(ClickTracking)
+
+    await fireEvent.click(getByRole('paragraph'))
+
+    expect(track).toHaveBeenCalledWith(TrackingEvent.ExploreAnyClick, null, expect.objectContaining({ selector: 'section > p' }))
+  })
+})