Hybrid H5 Video Playback in a Hybrid Architecture: Autoplay, Fullscreen Adaptation, and Tracking in Practice

1. Tech Selection: When Should You Give Up Native <video>?

When integrating video capabilities into H5 pages in B2C products, we do not always default to the <video> tag. In some cases, a custom Canvas-based player is the better solution. This decision usually comes from the lack of control in native video across three dimensions:

UI layer: Positioning of the play button, progress bar styling, easing curves in fullscreen transitions, and even loading indicator design are constrained by browser-engine implementations. If your product requires strict visual consistency, native controls are often not enough.

Behavior layer: Should tapping the video area play/pause or enter fullscreen? Will swipe gestures for volume conflict with page gestures? There is no cross-platform standard for these interaction rules, only platform-specific “conventions,” and debugging is expensive.

State layer: Programmatic playback control frequently hits permission boundaries. Under stricter autoplay policies, predictability in business logic drops significantly.

So for short, visual-communication-first content such as tutorials and flow demos, a Canvas solution is worth considering. These scenarios often do not require audio and avoid audio-focus conflicts. In contrast, for long-form videos or content that must have sound, native <video> is still recommended, but you need a robust permission fallback strategy.

Canvas rendering pitfall: Before data loading finishes, Canvas is transparent. If the outer container has no background color, some WebViews may show a black background through it. Pre-set a placeholder image or background color that matches the first video frame to avoid visual flicker.

2. Five Major Challenges with Native <video>

2.1 Autoplay Policy and Graceful Fallback

Autoplay policy is the first technical barrier for H5 video:

Platform	Policy Highlights
iOS Safari	Muted autoplay is allowed; audio needs a user gesture
Chrome	Depends on Media Engagement Index (MEI); new users are more restricted
Others	May have additional limits; verify with real-device testing

Recommended fallback path: try unmuted playback first -> if it fails, retry muted -> if it still fails, wait for user tap.

See MDN for implementation details: HTMLMediaElement.play()

/**
 * Try playing a video with built-in fallback for autoplay restrictions.
 * @param elem - video element
 * @param isRetry - whether this is a retry call (internal use)
 */
function playVideo(elem: HTMLVideoElement, isRetry = false): Promise<void> {
  return new Promise((resolve, reject) => {
    const playPromise = elem.play();

    // Older browsers may return undefined.
    if (!playPromise) {
      resolve();
      return;
    }

    playPromise.then(resolve).catch((err) => {
      if (isRetry) {
        console.error("Playback failed, user interaction required:", err);
        reject(err);
        return;
      }

      // First failure: retry with muted playback.
      console.log("Autoplay blocked, downgrade to muted playback");
      elem.muted = true;
      playVideo(elem, true).then(resolve).catch(reject);
    });
  });
}

2.2 Tracking System: From Browser Events to Business Semantics

There is a semantic gap between native browser events and business states. Platform implementations also differ significantly, so the same event usually requires platform-specific logic:

Event Name	Trigger Timing	Detection Logic	Platform Differences
video_impression	Component mounted and enters viewport	Intersection Observer or trigger after page load	No major differences
video_play	First tap on poster starts playback	Call play() after user tap and currentTime < 0.3	No major differences
video_resume	Resume after pause	play event fires and currentTime > 0.3	No major differences
video_pause	User actively pauses in fullscreen	pause event fires and fullscreen is active	Android: check document.fullscreenElement iOS: check video.webkitDisplayingFullscreen
video_stop	Playback stops due to exiting fullscreen	pause event fires and fullscreen has exited	Same as above, inverted fullscreen state
video_complete	Video naturally reaches end	pause event fires and video.ended === true	No major differences
video_fullscreen_enter	Enter fullscreen playback	Trigger after fullscreen API call succeeds	Android: listen to fullscreenchange iOS: fire when webkitEnterFullscreen succeeds (no native event, requires business-layer flagging)
video_fullscreen_exit	Exit fullscreen	Transition from fullscreen to non-fullscreen	Android: fullscreenchange + empty fullscreenElement iOS: listen to webkitendfullscreen (private event) or poll webkitDisplayingFullscreen

Recommendation: use traditional function callbacks instead of arrow functions for event listeners, so you can directly access the video DOM via this.

State inference implementation:

// Play event: distinguish first play vs. resume.
video.addEventListener("play", function () {
  // currentTime > 0.5 is treated as resume (avoid initial buffering jitter).
  const eventType = this.currentTime > 0.5 ? "video_resume" : "video_play";
  track(eventType, getPayload(this));
});

// Pause event: infer business semantics from multiple dimensions.
video.addEventListener("pause", function () {
  if (this.ended) {
    track("video_complete", getPayload(this));
    return;
  }

  // Detect fullscreen state: webkitDisplayingFullscreen is iOS-private.
  const isExitingFullscreen =
    !document.fullscreenElement && !this.webkitDisplayingFullscreen;

  track(isExitingFullscreen ? "video_stop" : "video_pause", getPayload(this));
});

2.3 Fullscreen API Compatibility Governance

Fullscreen APIs vary significantly by platform, so you need an abstraction layer:

Platform	Enter Fullscreen	Exit Fullscreen	State Detection	Special Notes
Standard API	requestFullscreen()	exitFullscreen()	fullscreenElement	Not supported in iOS Safari
iOS Safari	webkitEnterFullscreen()	System-controlled	webkitDisplayingFullscreen	Check webkitSupportsFullscreen first

Cross-platform fullscreen wrapper:

/**
 * Cross-platform wrapper for entering fullscreen.
 */
function enterFullscreen(video: HTMLVideoElement): void {
  if (video.webkitSupportsFullscreen) {
    // iOS Safari native video fullscreen (not page fullscreen).
    video.webkitEnterFullscreen?.();
  } else if (video.requestFullscreen) {
    // Standard Fullscreen API.
    video.requestFullscreen({ navigationUI: "auto" });
  } else {
    // Fallback: simulate fullscreen with CSS (fixed-position overlay).
    video.classList.add("fullscreen-fallback");
  }
}

/**
 * Check whether the video is currently in fullscreen.
 */
function isVideoFullscreen(video: HTMLVideoElement): boolean {
  return (
    document.fullscreenElement === video ||
    document.webkitFullscreenElement === video ||
    video.webkitDisplayingFullscreen ||
    video.classList.contains("fullscreen-fallback")
  );
}

2.4 Engineering Trade-offs for Poster Images

As a native approach, the poster attribute has clear advantages: near-zero maintenance cost, best performance, and smooth state transitions. But for the following three scenarios, you should consider a custom poster implementation:

Scenario 1: flow hijacking requirements When the business requires a click on the poster to not play immediately, but to run pre-logic first (for example, landscape-viewing prompt, auth check, permission request), the default click behavior of poster cannot be intercepted. A custom poster (independent <img> or <div>) gives complete control over event dispatch.

Scenario 2: state overlay requirements Some states require you to overlay native controls. For example, after auto-entering fullscreen playback, the user exits fullscreen, video pauses, and native controls appear. The business may want to show a custom “Continue playback” button or guidance overlay. poster only exists before playback starts, so it cannot act as a mid-flow mask.

Scenario 3: style-constraint breakthroughs As an internal rendering layer of the video element, poster is not fully controllable by CSS:

• border-radius does not reliably apply to poster; with rounded containers, poster overflow can occur
• Visual effects such as box-shadow and filter do not apply
• Advanced styles such as mix-blend-mode are unsupported

When the design system requires full visual consistency between poster and container (for example, unified 16px rounded cards), a custom poster is the only viable option.

Custom poster approach:

// Structure: poster layer + video layer (hidden initially).
const VideoPlayer = () => {
  const [showVideo, setShowVideo] = useState(false);
  const videoRef = useRef<HTMLVideoElement>(null);

  const handlePosterClick = async () => {
    const video = videoRef.current;
    if (!video) return;

    setShowVideo(true);

    try {
      await playVideo(video);
      enterFullscreen(video);
    } catch (err) {
      // Playback failed: revert to poster state.
      setShowVideo(false);
    }
  };

  return (
    <div className="video-container">
      {!showVideo && (
        <img
          className="video-poster"
          src="/assets/poster.jpg"
          onClick={handlePosterClick}
          alt="Tap to play"
        />
      )}
      <video
        ref={videoRef}
        src="/assets/video.mp4"
        style={{ display: showVideo ? "block" : "none" }}
        muted
        preload="auto"
      />
    </div>
  );
};

2.5 Android Exit-Interaction Fallback

The system fullscreen-exit button in Android WebView has UX issues: it is small, fixed-position, and icon semantics are ambiguous, so users often get confused. On Android, it is recommended to add swipe-to-exit as a fallback interaction for fullscreen video:

• Swipe left to exit: aligns with Android’s horizontal “back” gesture habit
• Swipe up to exit: mimics iOS muscle memory of swiping up from the bottom to return to the home screen

Use a reasonable threshold in implementation (recommended: trigger only when swipe distance exceeds 100px) to avoid accidental exits.

3. Complete Implementation Example

Below is a production-style implementation based on Taro + React, integrating the strategies above:

import { View } from '@tarojs/components';
import './index.scss';
import { memo, useCallback, useEffect, useRef } from 'react';
import { getDeviceType } from '@/utils/device';
import { LogAction } from '@/firebase/logEvent';
import { CustomEventParamMap } from '@/firebase/type';
import { getTouchPosition } from '@/utils/gesture';

const deviceType = getDeviceType();
export const videoHref = 'x.mp4';

function isVideoInFullscreen() {
  return document.fullscreenElement?.nodeName === 'VIDEO';
}

function playVideo(elem: HTMLVideoElement, isFailed = false) {
  return new Promise((res, rej) => {
    const playPromise = elem.play();
    if (playPromise !== undefined) {
      playPromise.then(res, err => {
        if (isFailed) {
          rej(err);
          return;
        }
        console.log('Try muted playback');
        elem.muted = true;
        playVideo(elem, true).then(res).catch(rej);
      });
    }
  });
}

const toFix2 = (num: number): number => Math.round(num * 100) / 100;

function getReportPayload(
  dom: HTMLVideoElement
): CustomEventParamMap['education_video_play'] {
  // duration may be Infinity before the media request completes.
  const video_total_duration = toFix2(
      dom.duration !== Infinity ? dom.duration : NaN || 60
    ),
    video_played_duration = toFix2(dom.currentTime);

  return {
    video_id: 'education_intro_v1',
    video_played_duration,
    video_total_duration,
    video_played_ratio: toFix2(video_played_duration / video_total_duration),
  };
}

export const EducationVideo = memo(function EducationVideo() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const isClickedRef = useRef(false);
  const isPlaying = useRef(false);

  useEffect(() => {
    LogAction('education_video_impression');
  }, []);

  useEffect(() => {
    const videoDom = videoRef.current;
    if (!videoDom) return;

    const abortController = new AbortController();
    const signal = { signal: abortController.signal };
    let startX = 0, startY = 0;

    if (deviceType !== 'ios') {
      // iOS cannot listen to this event.
      document.addEventListener('fullscreenchange', () => {
        if (!document.fullscreenElement) {
          videoDom.pause();
        }
      }, signal);

      videoDom.addEventListener('touchstart', (ev) => {
        const { x, y } = getTouchPosition(ev);
        startX = x;
        startY = y;
      }, signal);

      videoDom.addEventListener('touchend', (ev) => {
        const { x, y } = getTouchPosition(ev);
        if (Math.abs(startX - x) > 100 || Math.abs(startY - y) > 100) {
          document.exitFullscreen();
        }
      }, signal);
    }

    videoDom.addEventListener('play', function () {
      if (this.currentTime > 0.3) {
        LogAction('education_video_resume', getReportPayload(this));
      }
    }, signal);

    videoDom.addEventListener('pause', function () {
      isPlaying.current = false;
      if (!this.ended) {
        if (videoDom?.webkitDisplayingFullscreen || document.fullscreenElement) {
          LogAction('education_video_pause', getReportPayload(this));
        } else {
          LogAction('education_video_stop', getReportPayload(this));
        }
      } else {
        // Playback completed (when loop is not enabled).
        LogAction('education_video_complete', getReportPayload(this));
      }
    }, signal);

    return () => abortController.abort();
  }, []);

  const onPosterClick = useCallback(() => {
    const elem = videoRef.current!;
    if (isPlaying.current || elem.webkitDisplayingFullscreen || isVideoInFullscreen()) {
      return;
    }

    isPlaying.current = true;
    elem.style.display = 'block';

    playVideo(elem)
      .then(() => {
        if (deviceType === 'ios') {
          if (elem.webkitSupportsFullscreen) {
            elem.webkitEnterFullscreen?.();
          } else {
            elem.webkitRequestFullscreen?.();
          }
        } else {
          elem.requestFullscreen({ navigationUI: 'auto' });
        }

        if (!isClickedRef.current) {
          LogAction('education_video_play', getReportPayload(elem));
          isClickedRef.current = true;
        }
      })
      .catch((rej) => {
        console.error('Playback error:', rej);
        // Keep this catch block to avoid unhandled rejection.
      });
  }, []);

  return (
    <View className="video-ctn">
      <img
        className="video-poster"
        src={require('x.jpg')}
        onClick={onPosterClick}
        alt="Video poster"
      />
      <View className="video-view">
        <video
          muted
          ref={videoRef}
          src={videoHref}
          controls={true}
          controlsList="nodownload"
          disablePictureInPicture
          disableRemotePlayback
          preload="auto"
        />
      </View>
    </View>
  );
});

---

Appendix: TypeScript Type Augmentation for WebKit Extension APIs

Safari / WebKit provides a set of video-related extension APIs, but these properties are not part of the standard DOM spec, so they are absent from TypeScript’s built-in lib.dom.d.ts. With declaration merging, you can add project-level type definitions to get complete type hints and checks:

// types/webkit-video.d.ts
declare global {
  interface HTMLVideoElement {
    /** Allows inline playback (common in iOS Safari). */
    webkitPlaysInline?: boolean;

    /** Whether the video is currently displayed in fullscreen (exists in some versions). */
    webkitDisplayingFullscreen?: boolean;

    /** Enter/exit fullscreen (varies by WebKit version). */
    webkitEnterFullscreen?: () => void;
    webkitExitFullscreen?: () => void;

    /** Media group settings (for AirPlay/media selection, etc.). */
    webkitMediaGroup?: string;

    /** AirPlay-related APIs. */
    webkitShowPlaybackTargetPicker?: () => void;
    webkitCurrentPlaybackTargetIsWireless?: boolean;

    /** Presentation mode (inline / fullscreen / picture-in-picture). */
    webkitPresentationMode?: "inline" | "fullscreen" | "picture-in-picture";
    webkitSetPresentationMode?: (
      mode: "inline" | "fullscreen" | "picture-in-picture",
    ) => void;
  }
}

export {};