# @ray-js/track

> 业务异常及 SDK 埋点 SDK

Latest version **0.1.2** (published 2026-04-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ray-js/track
pnpm add @ray-js/track
yarn add @ray-js/track
bun add @ray-js/track
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.2 |
| Published | 2026-04-27 |
| First published | 2026-04-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 42.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | tuyafe |

## Links

- npm: https://www.npmjs.com/package/@ray-js/track
- npm.io page: https://npm.io/package/@ray-js/track

## Recent versions

- 0.1.2 (latest) — 2026-04-27
- 0.1.2-beta.1 (beta) — 2026-04-24
- 0.1.1 — 2026-04-16
- 0.1.0 — 2026-04-16

## README

English | [简体中文](./README-zh_CN.md)

# @ray-js/track

[![latest](https://img.shields.io/npm/v/@ray-js/track/latest.svg)](https://www.npmjs.com/package/@ray-js/track) [![download](https://img.shields.io/npm/dt/@ray-js/track.svg)](https://www.npmjs.com/package/@ray-js/track)

> Business exception reporting & SDK usage tracking for MiniApp

## Installation

```sh
npm install @ray-js/track
# or
yarn add @ray-js/track
```

## Use Cases

1. SDK usage tracking
2. Common business exception monitoring via detectors
3. Custom business exception monitoring

## Important Notes

- External developer integration is not supported at this time; this package is intended for Tuya official developers only
- No data will be reported if the end user disables `Feature Experience Upgrade Plan` in the App privacy settings
- Do not use in child-oriented MiniApps
- Never report personal data such as phone numbers, emails, or real names through `msg`, `params`, or detector extension fields

## Quick Start

### SDK Usage Tracking (for SDK authors)

Embed in your SDK to track how many MiniApps are using it:

```ts
import { UsageTracker } from '@ray-js/track';

// Call once during SDK initialization
UsageTracker.report({
  sdkName: '@ray-js/your-sdk',
  sdkVersion: '1.0.0',
});
```

### Common Exception Monitoring (via detectors)

```ts
import { TrackSDK, I18nDetector } from '@ray-js/track';

// Create detectors before any business code runs
const i18nDetector = I18nDetector();

// Initialize SDK
const track = TrackSDK.init();

// Register detectors
track.use([i18nDetector]);
```

### Custom Business Exception Monitoring

```ts
import { TrackSDK } from '@ray-js/track';

const track = TrackSDK.init();

track.report({
  msg: 'Device connection timeout',
  level: 'error',
  params: { deviceId: 'xxx' },
});
```

---
_Source: https://npm.io/package/@ray-js/track · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._