onVisibilityChangedByTransparentServiceWeb

Receives events when the transparent service web container becomes visible or hidden. Requires a callbackId to identify the subscription, and returns a cleanup function.

Signature

import { onVisibilityChangedByTransparentServiceWeb } from '@apps-in-toss/web-framework';

declare function onVisibilityChangedByTransparentServiceWeb(eventParams: {
  options: {
    callbackId: string;
  };
  onEvent: (isVisible: boolean) => void;
  onError: (error: unknown) => void;
}): () => void;

Parameters

Name	Type	Required	Description
options.callbackId	string	✓	Unique ID for this subscription. Must be unique within the app.
onEvent	(isVisible: boolean) => void	✓	Called on visibility change. true = visible, false = hidden.
onError	(error: unknown) => void	✓	Called when an error occurs.

Returns

• () => void — cleanup function that unsubscribes. Use as the useEffect return value.

Permission

No permission required — onVisibilityChangedByTransparentServiceWeb is not bound to a PermissionName.

Examples

Minimal

import { onVisibilityChangedByTransparentServiceWeb } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

function Page() {
  const [isVisible, setIsVisible] = useState(false);

  useEffect(() => {
    const cleanup = onVisibilityChangedByTransparentServiceWeb({
      options: { callbackId: 'my-app-visibility' },
      onEvent: (visible) => {
        setIsVisible(visible);
      },
      onError: (error) => {
        console.error('Visibility event error:', error);
      },
    });
    return cleanup;
  }, []);

  return (
    <main>
      <p>Container: {isVisible ? 'visible' : 'hidden'}</p>
    </main>
  );
}

Realistic — pause media on hide

import { onVisibilityChangedByTransparentServiceWeb } from '@apps-in-toss/web-framework';
import { useEffect, useRef } from 'react';

function VideoPage() {
  const videoRef = useRef<HTMLVideoElement>(null);

  useEffect(() => {
    const cleanup = onVisibilityChangedByTransparentServiceWeb({
      options: { callbackId: 'video-page-visibility' },
      onEvent: (isVisible) => {
        if (videoRef.current) {
          if (isVisible) {
            videoRef.current.play();
          } else {
            videoRef.current.pause();
          }
        }
      },
      onError: (error) => {
        console.error('Visibility event error:', error);
      },
    });
    return cleanup;
  }, []);

  return (
    <main>
      <video ref={videoRef} src="/example.mp4" />
    </main>
  );
}

Try it live

→Open in sdk-example

Related APIs

• graniteEvent.addEventListener — subscribe to backEvent, homeEvent.
• tdsEvent.addEventListener — subscribe to TDS events.
• appsInTossEvent.addEventListener — subscribe to platform events.

Related guides

• Guides — Event subscription patterns — addEventListener shape, cleanup, comparison across the three domains, and anti-patterns.

External references

• @apps-in-toss/web-framework — SDK package. The actual exports are re-exported from @apps-in-toss/web-bridge.