Everframe

Everframe SDK

Everframe SDK 的开源项目主页，包含报告 SDK、共享协议和 SDK 核心、开发者工具及示例应用。

Everframe 可帮助用户在应用内报告问题，并提供复现问题所需的上下文：屏幕截图和批注、会话证据、操作记录、设备和应用元数据，以及捕获的错误。

选择 SDK

平台	SDK	文档	示例
Web 和与框架无关的 JavaScript	@everframe/web	Web SDK	Vue、Smart TV
React	@everframe/react	React SDK	React web
React Native、Apple TV 和 Android TV	@everframe/react-native	React Native SDK	React Native
适用于 Android、iOS 和 Web 的 Flutter	everframe_flutter	Flutter SDK	Android probe、iOS probe、web probe
适用于 Android、iOS 和 Kotlin/JS 的 Kotlin Multiplatform	dev.everframe:kmp	KMP SDK	Android probe、iOS probes、browser canvas probe
Android 和 Android TV	dev.everframe Maven 模块	Android SDK	Compose、Views
iOS、iPadOS 和 tvOS	Everframe Swift 包	Apple SDK	iOS、tvOS replay
服务端身份识别	@everframe/identity	Identity helper	包文档中包含针对特定运行时的方案

各 SDK 的 README 是安装、配置、隐私控制、平台支持及当前限制的权威指南。

共享软件包与工具

• @everframe/protocol 定义了所有 SDK 共用的带版本报告封装，并提供原生实现使用的生成版 JSON Schema。
• @everframe/sdk-core 包含平台无关的 TypeScript 报告运行时，以及 Web、React 和 React Native SDK 共用的实用工具。
• Babel 和 SWC 插件可在优化构建中保留 React 组件名称。
• packages/sdk-android 和 packages/sdk-ios 包含原生 SDK 源代码、平台测试和发布工具。

使用 SDK

为应用安装相应的软件包，并遵循对应平台的指南。例如，JavaScript 项目：

pnpm add @everframe/web
# or
pnpm add @everframe/react
# or
pnpm add @everframe/react-native
# Flutter apps use pub.dev:
flutter pub add everframe_flutter

Android SDK 以 dev.everframe Maven 模块的形式通过 Maven Central 分发。带标签的 Apple 版本可通过 Swift Package Manager 从此代码库获取。相关文档包含最新的坐标、产品和设置说明。

示例

examples 目录包含适用于受支持平台和集成方式、可运行的宿主程序：

示例	演示内容
react-web	React Web 集成和 SSR/CSP 测试样例
vue-web	从 Vue 集成与框架无关的 SDK
smarttv-tester	基于浏览器的 Smart TV 行为
react-native	React Native 桥接集成
flutter-android-probe	Flutter Android 源码与隐私探测
flutter-ios-probe	Flutter iOS 源码与隐私探测
android-compose	使用 Jetpack Compose 的原生 Android
android-views	使用 Views 系统的原生 Android
ios-native	原生 iOS 集成
tvos-replay	无需凭据的 tvOS 回放和遥控焦点冒烟测试

连接到 Everframe 的示例会从生成的、已忽略的配置中读取开发凭据。请从已提交的模板开始：

cp .env.example .env

仅填写所运行示例所需的值。切勿提交 SDK 密钥、身份机密、生成的平台配置或生产数据。

参与贡献

JavaScript 开发需要 Node.js 22 和 pnpm 9.15。Android 开发还需要兼容的 JDK 和 Android SDK；Apple 开发需要 Xcode。

git clone https://github.com/scriptx-com/everframe.git
cd everframe
corepack enable
pnpm install --frozen-lockfile

运行 CI 使用的相同 JavaScript 工作区检查：

pnpm test:boundary
pnpm check:boundary
pnpm build:packages
pnpm test:packages
pnpm typecheck:packages
pnpm build:examples
pnpm test:examples
pnpm typecheck:examples
pnpm check:publish

在各自的平台项目中运行原生检查：

# Android
cd packages/sdk-android/android
./gradlew test assembleRelease

# Apple, from the repository root
EVERFRAME_DEV_INGEST_URL=http://127.0.0.1:9 \
  swift test --package-path packages/sdk-ios --no-parallel

有关贡献和许可规则，请参阅 CONTRIBUTING.md。

发布

JavaScript 包发布到 npm，Flutter 插件发布到 pub.dev，Android 构件以 Maven 包的形式发布，带标签的 Apple 版本则为 Swift Package Manager 用户提供二进制 XCFramework。

Android 和 KMP Maven 构件共用一个版本号，并通过一次 Central Portal 上传发布。设置好 SIGNING_KEY 和 SIGNING_PASSWORD 后，运行 pnpm build:mobile-maven-bundle，以构建并验证已签名的包。使用 pnpm build:mobile-maven-bundle --prepare 可在签名前检查未签名的包；此 ZIP 无法上传到 Maven Central。

根目录中的 Package.swift 是供 Apple SDK 用户使用的二进制清单。源码开发和测试使用 packages/sdk-ios/Package.swift。

安全

请按照 SECURITY.md 中的说明私下报告漏洞。仓库的发布门禁会在发布前检查允许公开的文件范围、SPDX 元数据、已提交内容和 Git 历史记录。

许可证

ScriptX 所有的源代码采用 MIT 许可证。捆绑的上游文件保留其原始许可证；请参阅 LICENSES 和 REUSE.toml。