如何检测MS Teams个人应用用户点击外部离开应用？

方案1：利用浏览器Page Visibility API #

当用户切换到Teams的其他模块（聊天、日历等）时，应用所在的iframe会进入隐藏状态，通过Page Visibility API可以捕获这个状态变化，从而计算停留时长。

实现步骤 #

• 在React组件中使用useEffect监听visibilitychange事件
• 当页面状态变为hidden时，计算从进入时间到当前时间的差值，作为本次停留时长并上报
• 当页面状态恢复为visible时，重置进入时间，开始新的计时周期

代码示例 #

import { useEffect, useState } from 'react';

const App = () => {
  const [entryTime, setEntryTime] = useState(Date.now());

  useEffect(() => {
    const handleVisibilityChange = () => {
      if (document.hidden) {
        // 用户离开应用，计算停留时长
        const stayDuration = Date.now() - entryTime;
        // 此处替换为实际的上报逻辑
        console.log(`用户停留时长：${stayDuration}ms`);
      } else {
        // 用户回到应用，重置进入时间
        setEntryTime(Date.now());
      }
    };

    document.addEventListener('visibilitychange', handleVisibilityChange);
    return () => {
      document.removeEventListener('visibilitychange', handleVisibilityChange);
    };
  }, [entryTime]);

  return (
    <div>MS Teams 个人应用内容</div>
  );
};

export default App;

方案2：使用Microsoft Teams JavaScript SDK事件 #

Teams SDK提供了贴合Teams环境的焦点监听事件，能更精准地捕获用户在应用内/外的切换行为。

实现步骤 #

1. 安装Teams SDK：npm install @microsoft/teams-js
2. 初始化SDK后，监听应用的焦点变化事件
3. 触发离开事件时计算并上报停留时长

代码示例 #

import { useEffect, useState } from 'react';
import * as microsoftTeams from '@microsoft/teams-js';

const App = () => {
  const [entryTime, setEntryTime] = useState(Date.now());

  useEffect(() => {
    // 初始化Teams SDK
    microsoftTeams.initialize();

    // 用户离开应用（失去焦点）
    const handleBlur = () => {
      const stayDuration = Date.now() - entryTime;
      console.log(`用户停留时长：${stayDuration}ms`);
      // 执行上报逻辑
    };

    // 用户回到应用（获得焦点）
    const handleFocus = () => {
      setEntryTime(Date.now());
    };

    microsoftTeams.registerOnFocusHandler(handleFocus);
    microsoftTeams.registerOnBlurHandler(handleBlur);

    return () => {
      // 清理事件监听
      microsoftTeams.registerOnFocusHandler(null);
      microsoftTeams.registerOnBlurHandler(null);
    };
  }, [entryTime]);

  return (
    <div>MS Teams 个人应用内容</div>
  );
};

export default App;

方案3：结合两种方案提升可靠性 #

不同Teams客户端（网页版、桌面版、移动端）对事件的支持存在差异，结合两种方案能覆盖更多场景，提升检测准确性。

代码示例 #

import { useEffect, useState } from 'react';
import * as microsoftTeams from '@microsoft/teams-js';

const App = () => {
  const [entryTime, setEntryTime] = useState(Date.now());
  const [isTeamsReady, setIsTeamsReady] = useState(false);

  useEffect(() => {
    // 初始化Teams SDK并确认环境
    microsoftTeams.initialize();
    microsoftTeams.getContext(() => setIsTeamsReady(true));

    const handleLeave = () => {
      const stayDuration = Date.now() - entryTime;
      console.log(`用户停留时长：${stayDuration}ms`);
      // 执行上报逻辑
    };

    const handleReturn = () => {
      setEntryTime(Date.now());
    };

    // 绑定Teams SDK事件
    if (isTeamsReady) {
      microsoftTeams.registerOnBlurHandler(handleLeave);
      microsoftTeams.registerOnFocusHandler(handleReturn);
    }

    // 绑定Page Visibility事件作为 fallback
    const handleVisibilityChange = () => {
      document.hidden ? handleLeave() : handleReturn();
    };
    document.addEventListener('visibilitychange', handleVisibilityChange);

    return () => {
      if (isTeamsReady) {
        microsoftTeams.registerOnBlurHandler(null);
        microsoftTeams.registerOnFocusHandler(null);
      }
      document.removeEventListener('visibilitychange', handleVisibilityChange);
    };
  }, [entryTime, isTeamsReady]);

  return (
    <div>MS Teams 个人应用内容</div>
  );
};

export default App;

注意事项 #

• 必须在Teams环境内测试，普通浏览器的事件表现与Teams iframe环境存在差异
• 上报数据建议添加防抖逻辑，避免用户快速切换时重复上报
• 移动端Teams应用需额外验证事件兼容性，部分场景可能需要调整监听逻辑

内容的提问来源于stack exchange，提问作者Sigar Dave