@getdevteam/analytics-react-native

中文文档
0.13.0发布于 2026/11/13MITTypeScriptESM + CJS近 30 天下载 5万

React Native SDK for the DevTeam analytics and logging platform.

原始使用文档
文档目录5 节
  1. Install
  2. Use
  3. Errors
  4. Release identity
  5. User feedback

@getdevteam/analytics-react-native

React Native / Expo SDK for the DevTeam Analytics & Logging Platform.

Install

npm install @getdevteam/analytics-react-native @react-native-async-storage/async-storage

Use

import { createAnalytics } from "@getdevteam/analytics-react-native";

const key = process.env.EXPO_PUBLIC_DEVTEAM_ANALYTICS_INGEST_KEY;
const host = process.env.EXPO_PUBLIC_DEVTEAM_ANALYTICS_HOST;
// A build without either stays inert instead of failing.
export const analytics = key && host ? createAnalytics({ key, host }) : undefined;

analytics?.screen("Home", { tab: "featured" });   // screen view
analytics?.track("add_to_cart", { sku: "A-1" });
analytics?.log.info("checkout started", { items: 3 });

Hera's mobile builds set EXPO_PUBLIC_DEVTEAM_ANALYTICS_INGEST_KEY and EXPO_PUBLIC_DEVTEAM_ANALYTICS_HOST from the build environment's analytics values; an app built anywhere else (EAS, a local build) sets them itself. Write both references out literally, as above: Expo inlines EXPO_PUBLIC_ variables only for a literal process.env.EXPO_PUBLIC_... access in app code.

@react-native-async-storage/async-storage is a required peer that keeps identity across app restarts; install it alongside the SDK. The SDK auto-flushes when the app goes to the background. Every log line and caught error carries the name last passed to screen() as its screen attribute; until the app reports a screen, none is sent. On a physical device use your machine's LAN IP instead of localhost when pointing at a local backend.

Errors

From 0.10.0 the SDK reports what the app does not catch, on by default:

  • every error that reaches React Native's global handler (ErrorUtils) - from event handlers, timers, native callbacks and start-up code - with is_fatal; the app's previous handler still runs after the report;
  • in a release build, a fatal error's report is written to storage and sent before the previous handler ends the app, waiting at most one second, and a fatal error raised during that wait is handed on without a second report; development hands every error on at once;
  • on Hermes, every unhandled promise rejection, outside development only, where React Native's own warning stays in place.

From React 19 an error thrown while rendering goes to React Native without passing its global handler, so wrap the app's root in an error boundary that calls analytics.captureError(error, { source: "error_boundary" }). Each report arrives as a $error event and an error log with its stack. Call analytics.captureError(error, attributes) for errors the app catches itself. Pass autoCaptureErrors: false to turn the automatic capture off, for example when the app already installs its own global handler that reports through the SDK. Hermes keeps one promise rejection tracker, so the SDK's replaces one another library installed before it, and a later one replaces the SDK's. Crashes below JavaScript (Java, Kotlin, Swift or Objective-C) are not reported.

Release identity

Devteam sets DEVTEAM_RELEASE_VERSION and DEVTEAM_COMMIT_SHA on every deploy; expose them as EXPO_PUBLIC_ variables and pass them as release from your app code:

const analytics = createAnalytics({
  key: "dtp_your_public_key",
  host: "https://ingest.analytics.getdevteam.ai",
  release: {
    version: process.env.EXPO_PUBLIC_DEVTEAM_RELEASE_VERSION,
    commit: process.env.EXPO_PUBLIC_DEVTEAM_COMMIT_SHA,
  },
});

Write the two process.env.EXPO_PUBLIC_... references out literally like this: Expo inlines them only in app code, never inside node_modules and never for a computed or destructured access. Without release the SDK falls back to globalThis.__DEVTEAM_RELEASE__, then its own read of the same EXPO_PUBLIC_ variables (which finds a value only where the SDK is compiled as app code), then process.env.DEVTEAM_*, then the native app version from the optional expo-application peer. See Release identity for the full precedence and the synthetic-traffic flag.

User feedback

Create the client with allowUserFeedback: true and wrap your app in the exported provider:

import { createAnalytics, FeedbackProvider } from "@getdevteam/analytics-react-native";

const analytics = createAnalytics({
  key: "dtp_your_public_key",
  host: "https://ingest.analytics.getdevteam.ai",
  allowUserFeedback: true,
});

export default function App() {
  return (
    <FeedbackProvider client={analytics}>
      <RootNavigator />
    </FeedbackProvider>
  );
}

A floating button opens a modal with a screenshot of the app, drawing tools, and a comment box; submit sends it to the platform's feedback inbox. analytics.submitFeedback({ text, screenshot?, screenshotContentType?, pageUrl?, attachments?, feedbackId?, formOpenMs? }) sends feedback programmatically and resolves false instead of throwing on any failure. Pass the same feedbackId when retrying a send of the same draft, so a send whose response was lost is stored only once; without one, every call gets a fresh id. formOpenMs is how many milliseconds your form was open before the send, timed with performance.now(), as the modal does; the service marks a send faster than a person could write one as spam, and a call without it is never caught by that check. Each send also solves the invisible bot check (see the SDK README); analytics.prepareFeedbackSend() starts it ahead of time, which the modal does as it opens, so a send from your own form can call it when the form appears. A screenshot over 5 MiB is refused, like on the web. The modal keeps its own screenshot under that cap: an oversized PNG is re-captured as JPEG and then at 0.7x the size until it fits, and if nothing fits the feedback is sent without it. Customize with feedback: { colors, accentColor, buttonLabel, title, submitLabel, commentPlaceholder, successMessage, position, iconButton, shakeToReport, shakeHint }. iconButton: { size: 46 } draws the button as a round icon of that many points instead of the text pill: a white speech bubble with an exclamation mark on accentColor. While the screenshot is captured the same circle shows a spinner, reports busy to screen readers, and ignores further presses until the feedback sheet opens; buttonLabel (default Feedback) is what screen readers announce. It needs the react-native-svg peer; without it the text pill is drawn, and leaving iconButton out keeps the text pill. shakeToReport: true opens the sheet when the device is shaken, with no floating button, using the optional expo-sensors peer's accelerometer (read only while the app is in front, and a shake while a text field is focused is ignored, since iOS reads it as undo). Without expo-sensors - or in an app binary built before it was added - or on a device with no accelerometer, the button stays, dimmed, and can be dragged to any edge of the screen, where it is remembered. shakeHint (default Shake your phone to send feedback) is shown and announced once per device, the first time shaking is what opens the sheet. Call analytics.identify(user.id, { name: user.fullName }) after login and session restore so feedback says who sent it; the name goes with feedback only, never with events or logs, and reset() on logout forgets it. If the project accepts feedback only from signed-in users, also pass the signature your server made for that id: analytics.identify(user.id, { name: user.fullName }, { userSignature }). Without one the button is not shown and submitFeedback sends nothing, resolves false and reports why to onError - see Only signed-in users.

Screenshot and drawing come from two optional peers, and each degrades instead of breaking:

InstalledBehavior
react-native-view-shot + react-native-svgScreenshot, drawing tools, comment.
react-native-view-shot onlyScreenshot + comment, no drawing tools.
neitherComment-only feedback.
app not wrapped in FeedbackProvider, or flag offNo button or modal renders; a wrapped app stays mounted inside two full-screen Views, so turning the flag on or off keeps its state.

The optional peers are loaded with literal require calls, each inside a try/catch, in the CJS build. Metro takes that CJS build through the package's react-native export condition, whether the app imports or requires the SDK; that assumes Metro keeps transformer.allowOptionalDependencies enabled (the React Native and Expo template default, and it only covers string-literal requires inside a try/catch), so a missing optional peer never fails the bundle. Import-condition consumers (react-native-web, Node ESM) cannot load the optional peers and degrade to comment-only feedback. Native views (maps, video, web views) may come out blank in captures; a failed capture falls back to comment-only.

You need a public ingest key (dtp_...) and the ingest host URL for your environment - see Getting a key in the full SDK docs.

Full client API, config options, and release process: src/sdk README.

版本与发布记录

@getdevteam/analytics-react-native 共发布 21 个版本,首次发布于 2026/07/05;过去 12 个月发布了 21 个版本。

版本发布日期距今
0.13.0latest2026/11/133 天前
0.12.02026/11/106 天前
0.11.02026/11/097 天前
0.10.02026/11/0313 天前
0.9.02026/11/0213 天前
0.8.32026/10/2917 天前

其他发布通道:dev → 0.1.0-dev.2。

关于 @getdevteam/analytics-react-native 的常见问题

@getdevteam/analytics-react-native 是什么?

React Native SDK for the DevTeam analytics and logging platform.

如何安装 @getdevteam/analytics-react-native?

在项目目录运行 npm install @getdevteam/analytics-react-native,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=18)、react-native(>=0.72)、@react-native-async-storage/async-storage(>=1.19.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@getdevteam/analytics-react-native 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getdevteam/analytics-react-native 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@getdevteam/analytics-react-native 可以商用吗?

@getdevteam/analytics-react-native 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@getdevteam/analytics-react-native 的下载量有多少?

根据 npm 官方下载统计,@getdevteam/analytics-react-native 在 2026/10/17 – 2026/11/15 这 30 天内被下载 50,042 次,日均约 1,668 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getdevteam/analytics-react-native 还在维护吗?

最新版本 0.13.0 发布于 2026/11/13(3 天前);至今共发布 21 个版本,其中过去 12 个月发布了 21 个;首次发布于 2026/07/05。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。