@devix-technologies/react-gjirafa-vp-player 1.0.31-beta.11 → 1.0.31-beta.13

package/README.md

@@ -160,8 +160,9 @@ The player fills its container (100% width/height). Control sizing with a wrappe
 | Prop | Horizontal | Vertical | Description |
 |------|:----------:|:--------:|-------------|
 | `onReady` | ✓ | ✓ | Player initialized |
-| `onPlay` | ✓ | ✓ | Playback started |
-| `onPause` | ✓ | ✓ | Playback paused |
+| `onPlay` | ✓ | ✓ | Playback started (initial play) |
+| `onPause` | ✓ | ✓ | Playback paused (user-initiated) |
+| `onResume` | ✗ | ✓ | Playback resumed after pause (vertical only) |
 | `onComplete` | ✓ | ✗ | Video completed (horizontal only) |
 | `onError` | ✓ | ✓ | Error occurred |
 | `onVideoStarted` | ✓ | ✓ | Video metadata available (returns `CurrentVideoData`) |
@@ -177,19 +178,42 @@ The player fills its container (100% width/height). Control sizing with a wrappe
 
 #### Event Implementation Notes
 
-**Horizontal Player** uses standard VP Player SDK events:
+**Horizontal Player** uses standard VP Player SDK events via `.on()` listener:
 - `ready`, `play`, `pause`, `complete`, `video-started`, `video-state`, `time`, `playlistItem`, `error`
 - Quartiles: `analytics-25%-completed`, `analytics-50%-completed`, `analytics-75%-completed`
 
-**Vertical Player** uses VP Vertical Player SDK events (different naming):
-- `vp-ready`, `playing`, `pause`, `vp-video-started`, `vp-video-state`, `vp-time`, `vp-video-switch`, `error`
+**Vertical Player** uses a combination of `.on()` listener and the global `vp-event` handler:
+
+Standard events via `.on()`:
+- `vp-first-frame`, `vp-video-started`, `vp-video-state`, `vp-time`, `vp-video-switch`, `error`
 - Quartiles: `analytics-25%-completed`, `analytics-50%-completed`, `analytics-75%-completed`
-- Direction detection: Uses `player._switchDirection` property (via `queueMicrotask`) to differentiate `onNext` vs `onPrevious`
+
+**Special handling via `vp-event` handler** (not exposed via standard `.on()`):
+
+The following events are intercepted from the global `vp-event` emission because the VP Vertical Player SDK doesn't expose them via the standard `.on()` listener:
+
+| Event | SDK Event | Special Logic |
+|-------|-----------|---------------|
+| `onPlay` | `vp-state-playing` | Fires on initial play (when not resuming from pause) |
+| `onPause` | `vp-state-paused` | Only fires on **user-initiated** pause (not on video loop/end) |
+| `onResume` | `vp-state-playing` | Fires when resuming after **user-initiated** pause |
+
+**User Interaction Tracking:**
+
+To distinguish between user actions and automatic playback events (like video loops), we track the `vp-user-interaction` event:
+- When `vp-user-interaction` fires before `vp-state-paused` → user clicked pause → `onPause` fires
+- When `vp-user-interaction` fires before `vp-state-playing` (after pause) → user clicked play → `onResume` fires
+- When `vp-state-paused` fires without prior user interaction → video ended/looped → no `onPause` (silent)
+- When `vp-state-playing` fires without prior pause → initial play or loop restart → `onPlay` fires
+
+This ensures analytics events like `player_pause` and `player_resume` only fire for actual user actions, not automatic video looping.
 
 **Key Differences:**
-- `onComplete` - Only available on horizontal player (vertical auto-advances)
+- `onComplete` - Only available on horizontal player (vertical auto-advances to next video)
+- `onResume` - Only available on vertical player (horizontal has no pause/resume distinction)
 - `onPrevious` - Only available on vertical player (horizontal has no direction detection)
 - `onNext` on horizontal fires for ANY playlist change (next button, auto-advance after complete)
+- Direction detection on vertical uses `player._switchDirection` property (via `queueMicrotask`) to differentiate `onNext` vs `onPrevious`
 
 ## URL Helpers