add-react-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add React Analytics

为React应用添加分析功能

Integrate Temps analytics SDK into React applications with full tracking capabilities.

将Temps分析SDK集成到React应用中，实现完整的跟踪功能。

Installation

安装

bash

npm install @temps-sdk/react-analytics

bash

npm install @temps-sdk/react-analytics

or: yarn add / pnpm add / bun add

undefined

undefined

Framework Setup

框架设置

Detect the user's framework and apply the appropriate setup:

检测用户使用的框架并应用相应的配置：

Next.js App Router (13+)

Next.js App Router（13+）

tsx

// app/layout.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TempsAnalyticsProvider basePath="/api/_temps">
          {children}
        </TempsAnalyticsProvider>
      </body>
    </html>
  );
}

tsx

// app/layout.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TempsAnalyticsProvider basePath="/api/_temps">
          {children}
        </TempsAnalyticsProvider>
      </body>
    </html>
  );
}

Next.js Pages Router

tsx

// pages/_app.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <TempsAnalyticsProvider basePath="/api/_temps">
      <Component {...pageProps} />
    </TempsAnalyticsProvider>
  );
}

tsx

// pages/_app.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <TempsAnalyticsProvider basePath="/api/_temps">
      <Component {...pageProps} />
    </TempsAnalyticsProvider>
  );
}

Vite / Create React App

tsx

// src/main.tsx or src/index.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <TempsAnalyticsProvider basePath="/api/_temps">
    <App />
  </TempsAnalyticsProvider>
);

tsx

// src/main.tsx or src/index.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <TempsAnalyticsProvider basePath="/api/_temps">
    <App />
  </TempsAnalyticsProvider>
);

Remix

tsx

// app/root.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

export default function App() {
  return (
    <html lang="en">
      <body>
        <TempsAnalyticsProvider basePath="/api/_temps">
          <Outlet />
        </TempsAnalyticsProvider>
      </body>
    </html>
  );
}

tsx

// app/root.tsx
import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

export default function App() {
  return (
    <html lang="en">
      <body>
        <TempsAnalyticsProvider basePath="/api/_temps">
          <Outlet />
        </TempsAnalyticsProvider>
      </body>
    </html>
  );
}

Provider Configuration

Provider配置

tsx

<TempsAnalyticsProvider
  basePath="/api/_temps"
  autoTrack={{
    pageviews: true,       // Auto-track page views
    pageLeave: true,       // Track time on page
    speedAnalytics: true,  // Track Web Vitals
    engagement: true,      // Track engagement
    engagementInterval: 30000,
  }}
  debug={process.env.NODE_ENV === 'development'}
>
  {children}
</TempsAnalyticsProvider>

tsx

<TempsAnalyticsProvider
  basePath="/api/_temps"
  autoTrack={{
    pageviews: true,       // 自动追踪页面浏览
    pageLeave: true,       // 统计页面停留时间
    speedAnalytics: true,  // 追踪Web Vitals
    engagement: true,      // 追踪用户参与度
    engagementInterval: 30000,
  }}
  debug={process.env.NODE_ENV === 'development'}
>
  {children}
</TempsAnalyticsProvider>

Available Hooks

可用Hooks

For detailed API reference, see HOOKS_REFERENCE.md.

如需详细API参考，请查看HOOKS_REFERENCE.md。

Quick Reference

快速参考

Hook	Purpose
`useTrackEvent`	Track custom events
`useAnalytics`	Access analytics context, identify users
`useScrollVisibility`	Track element visibility on scroll
`usePageLeave`	Track page leave and time on page
`useEngagementTracking`	Heartbeat engagement monitoring
`useSpeedAnalytics`	Web Vitals (LCP, FCP, CLS, TTFB, INP)
`useTrackPageview`	Manual page view tracking

Hook	用途
`useTrackEvent`	追踪自定义事件
`useAnalytics`	访问分析上下文、标识用户
`useScrollVisibility`	滚动时追踪元素可见性
`usePageLeave`	追踪页面离开事件及停留时间
`useEngagementTracking`	心跳式用户参与度监控
`useSpeedAnalytics`	监测Web Vitals（LCP、FCP、CLS、TTFB、INP）
`useTrackPageview`	手动追踪页面浏览

Track Custom Events

追踪自定义事件

tsx

'use client';
import { useTrackEvent } from '@temps-sdk/react-analytics';

function MyComponent() {
  const trackEvent = useTrackEvent();

  const handleClick = () => {
    trackEvent('button_click', {
      button_id: 'subscribe',
      plan: 'premium'
    });
  };

  return <button onClick={handleClick}>Subscribe</button>;
}

tsx

'use client';
import { useTrackEvent } from '@temps-sdk/react-analytics';

function MyComponent() {
  const trackEvent = useTrackEvent();

  const handleClick = () => {
    trackEvent('button_click', {
      button_id: 'subscribe',
      plan: 'premium'
    });
  };

  return <button onClick={handleClick}>Subscribe</button>;
}

Identify Users

用户标识

tsx

'use client';
import { useAnalytics } from '@temps-sdk/react-analytics';
import { useEffect } from 'react';

function UserProfile({ user }) {
  const { identify } = useAnalytics();

  useEffect(() => {
    if (user) {
      identify(user.id, {
        email: user.email,
        name: user.name,
        plan: user.subscription?.plan
      });
    }
  }, [user, identify]);

  return <div>Profile</div>;
}

tsx

'use client';
import { useAnalytics } from '@temps-sdk/react-analytics';
import { useEffect } from 'react';

function UserProfile({ user }) {
  const { identify } = useAnalytics();

  useEffect(() => {
    if (user) {
      identify(user.id, {
        email: user.email,
        name: user.name,
        plan: user.subscription?.plan
      });
    }
  }, [user, identify]);

  return <div>Profile</div>;
}

Session Recording

会话录制

For privacy-aware session replay, see SESSION_RECORDING.md.

tsx

import { SessionRecordingProvider } from '@temps-sdk/react-analytics';

<SessionRecordingProvider
  enabled={true}
  maskAllInputs={true}
  blockClass="sensitive"
>
  {children}
</SessionRecordingProvider>

如需了解隐私友好型会话回放，请查看SESSION_RECORDING.md。

tsx

import { SessionRecordingProvider } from '@temps-sdk/react-analytics';

<SessionRecordingProvider
  enabled={true}
  maskAllInputs={true}
  blockClass="sensitive"
>
  {children}
</SessionRecordingProvider>

Verification Checklist

验证清单

After implementation:

Check browser DevTools Network tab for
```
/api/_temps
```
requests
Verify events appear in Temps dashboard
Test session recording playback
Confirm Web Vitals are being captured

完成集成后：

在浏览器开发者工具的网络标签中检查
```
/api/_temps
```
请求
验证事件是否显示在Temps控制台中
测试会话录制回放功能
确认Web Vitals数据已被捕获