# @axeptio/react-native-sdk 中文文档 规范地址：https://npmcn.com/package/%40axeptio/react-native-sdk/ 版本：2\.4\.0 npm 元数据更新时间：2026-09-14T10:07:24.851Z 中文译文更新时间：2026-11-08T03:55:49.194Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40axeptio/react-native-sdk 原文对照：https://npmcn.com/package/%40axeptio/react-native-sdk/?lang=original 项目主页：https://github.com/axeptio/react-native-sdk#readme 源码仓库：https://github.com/axeptio/react-native-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：157 kB，49 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：react \*，react-native \* - 首次发布：2024-05-23T07:32:08.716Z - 最新版本发布：2026-08-19T11:35:56.955Z - 近 30 天下载量：1899（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：23（近 12 个月 6 个） ## 中文简介 Axeptio 反应本地 sdk 向用户提交 cookie 同意 ## 安装 ```sh npm install @axeptio/react-native-sdk ``` 也可以使用：`pnpm add @axeptio/react-native-sdk`、`yarn add @axeptio/react-native-sdk`、`bun add @axeptio/react-native-sdk` ## README ![](https://github.com/user-attachments/assets/09c669ea-3187-4fc2-8763-c209d8f4cde4) > **被否决**:这个SDK不再维持. 请使用 [Axeptio 无头CMP客户端](https://github.com/axeptio/headless-cmp-client) 相反,它提供了一个反应土著的实施。 见 [反应本地示例](https://github.com/axeptio/headless-cmp-client/tree/main/examples/react-native) 要开始. # Axeptio 反应原生 SDK 集成 ![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg) ![React Native Compatibility](https://img.shields.io/badge/React%20Native-%3E%3D%20065-blue) ![Android SDK](https://img.shields.io/badge/Android%20SDK-%3E%3D%2026-blue) ![iOS Version](https://img.shields.io/badge/iOS%20Versions-%3E%3D%2015-blue) 该存储库演示如何执行 **Axeptio 反应原生 SDK** 输入您的移动应用程序,处理用户同意遵守GDPR和其他隐私条例的问题. SDK既适用于品牌,也适用于出版商,这取决于您的使用情况和要求. ## 目录 1. [GitHub 访问托肯设置](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-github-access-token-setup) 2. [设置](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-setup) - [安装](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-installation) - [Android 设置](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-android-setup) - [iOS 设置](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-ios-setup) 3. [初始化应用程序启动的 SDK](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-initialize-the-sdk-on-app-startup) 4. [ATT(App跟踪透明度) 整合说明](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-att-app-tracking-transparency-integration-note) 5. [责任:移动App vs SDK](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-responsibilities-mobile-app-vs-sdk) 6. [获取存储同意](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-get-stored-consents) 7. [在需求时显示同意弹出](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-show-consent-popup-on-demand) 8. [与其他网页视图共享协议](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-sharing-consents-with-other-web-views) 9. [iOS Webview 同意同步](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-ios-webview-consent-synchronization) - [理解iOS Cookie 隔离问题](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-understanding-the-ios-cookie-isolation-issue) - [基于脚本的同步](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-token-based-synchronization) - [优化网络视频配置](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-optimized-webview-configuration) - [解决问题和诊断](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-troubleshooting-and-diagnostics) 10. [清除用户同意选择](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-clear-users-consent-choices) 11. [活动](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-events) - [事件源识别](https://npmcn.com/package/%40axeptio/react-native-sdk/#readme-event-source-identification) ## GitHub 访问托肯设置 当设置您的项目或访问某些 GitHub 服务时, 您可能会被提示创建 GitHub Access Token 。 请注意,产生这一标志要求: - 一个有效的 **GitHub 账户**。 。 。 . - **双要素认证(2FA)** 启用 . 为了避免设置过程中的认证问题,我们建议审查 [官方 GitHub 访问托肯文档](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 或关于如何创建令牌和确保2FA正确配置的详细指示. 遵循这些步骤将有助于你平稳地生成一个符号并减少登机摩擦. ## 设置 #### 安装 安装 **Axeptio 反应原生 SDK**,运行以下命令之一: ###### 使用 npm : ```bash npm install --save @axeptio/react-native-sdk ``` ###### 使用线条 : ```bash yarn add @axeptio/react-native-sdk ``` #### Android 设置 - **最小 SDK 版本**: 26 (英语). - 添加数据 **Maven GitHub 仓库** 财务报告和审定财务报表 **全权证书** 给您的 **应用程序** `android/build.gradle` (位于您 `.gradle` 存档). 下面的片段是添加到您的 `android/build.gradle` 文档,在仓库块。 它配置了Gradle从一个私人的GitHub寄存器中取出Axeptio Android SDK. - \[GITHUB TOKEN\] 瞄准镜需要 \[读:包装,回 ```gradle allprojects { repositories { google() mavenCentral() maven { url = uri("https://maven.pkg.github.com/axeptio/axeptio-android-sdk") credentials { username = "[GITHUB_USERNAME]" password = "[GITHUB_TOKEN]" } } } } ``` #### iOS 设置 - 我们支持 **iOS版本 QQ 15**。 。 。 . - 运行以下命令以安装依赖性 : ```bash npx pod-install ``` 您可以在 [示例文件夹](https://github.com/axeptio/react-native-sdk/tree/master/example)请检查文件夹中是否有更详细的执行实例. ## 在应用程序启动时启动 SDK 以初始化 **Axeptio 反应原生 SDK** 在您的应用程序中,您需要设置当您的应用程序启动时。 SDK可以被配置为不同的使用案例,例如品牌或出版商,使用 `AxeptioService` um. 这使得您可以根据自己的具体需要定制SDK(例如处理品牌或出版商的GDPR同意). 以下是如何初始化SDK的分步指南: ```javascript import AxeptioSDK, { AxeptioService } from '@axeptio/react-native-sdk'; async function init() { try { // Initialize the SDK with the desired service (brands or publishers) await AxeptioSDK.initialize( AxeptioService.brands, // Choose between AxeptioService.brands or AxeptioService.tcfPublishers [your_client_id], // Replace with your client ID (as provided by Axeptio) [your_cookies_version], // Replace with your current cookies version (as defined by your platform) [optional_consent_token] // Optional: If available, provide an existing consent token to restore previous consent choices ); // Setup the user interface for consent management await AxeptioSDK.setupUI(); console.log('Axeptio SDK initialized successfully!'); } catch (error) { console.error('Error initializing Axeptio SDK:', error); } } ``` ##### 参数: - `AxeptioService`:本条目定义您正在使用的服务类型 : - `AxeptioService.brands`:用于品牌和广告商. 这种设置一般用于遵守GDPR和其他隐私条例来跟踪用户同意. - `AxeptioService.tcfPublishers`: 给出版社使用。 它有助于管理用户同意 **透明度和同意框架(TCF)** 在数字出版方面处理GDPR同意是常见的. - `your_client_id`: 将此替换为您的独有 **客户端标识** 由Axeptio提供 当你的账户。 此身份识别您的组织或应用程序 . - `your_cookies_version`: 这是您饼干的版本标识符 。 它有助于管理不同的饼干政策和一段时间后的同意流动。 当您的 cookie 策略改变时, 此值应该递增 . - `optional_consent_token`: 此符号( 如果可用) 允许您通过一个先前存储的同意符号来恢复用户先前的同意选择 。 这是可选的,如果不需要,你可以跳过. ## ATT(跟踪透明度) 整合说明: Axeptio SDK 不处理用户在 **App 跟踪透明度(ATT)** 框架。 您的应用程序有责任管理此许可,并决定如何 **Axeptio 同意管理平台(CMP)** 编辑 **ATT许可** 应该共存. ###### 苹果准则 您的应用程序必须遵从 [苹果公司的准则](https://developer.apple.com/app-store/review/guidelines/#5.1.2) 用于披露您的应用程序所收集的数据,并请求用户允许进行跟踪. 为了管理ATT,你可以使用 [反应-内在跟踪-透明](https://www.npmjs.com/package/react-native-tracking-transparency) 部件. - **ATT 流量**:确保ATT提示在您在 Axeptio CMP 中请求同意之前显示给用户. 这确保了您遵守苹果公司的隐私要求. - **苹果的ATT准则**: 确保您遵循 [苹果的ATT准则](https://developer.apple.com/documentation/apptrackingtransparency) 适当执行. ##### 纳入武器贸易条约的步骤: 1. **安装库**数字 : 你需要安装 `react-native-tracking-transparency` 用于处理ATT请求的库. 使用 npm : ```bash npm install --save react-native-tracking-transparency ``` 或用纱线: ```yarn yarn add react-native-tracking-transparency ``` 2. **更新 `Info.plist`**数字 : 将以下密钥添加到您的 `Info.plist` 解释为什么您的应用程序需要用户跟踪的文件 : ```xml NSUserTrackingUsageDescription Explain why you need user tracking ``` 3. **管理ATT弹出**数字 : 在显示 Axeptio CMP UI 之前,您需要请求ATT 许可并处理用户的响应. 这是你如何管理ATT弹出: ```javascript import { getTrackingStatus, requestTrackingPermission, } from 'react-native-tracking-transparency'; async function handleATT() { // Check the current tracking status let trackingStatus = await getTrackingStatus(); // If status is not determined, request permission if (trackingStatus === 'not-determined') { trackingStatus = await requestTrackingPermission(); } // If tracking is denied, update the Axeptio SDK with the user's decision if (trackingStatus === 'denied') { await AxeptioSDK.setUserDeniedTracking(); } else { // If tracking is allowed, initialize the Axeptio SDK UI await AxeptioSDK.setupUI(); } } ``` ## 责任:移动App vs SDK 这个 **Axeptio SDK 软件** 以及您的移动应用程序在管理用户同意和跟踪方面有明确的责任: ##### 移动应用程序责任: - 执行和管理联合国 **App 跟踪透明度(ATT)** 允许流. - 决定何时显示 **ATT 美洲热带木材组织** 相对于 **《议定书》缔约方会议**。 。 。 . - 正确申报数据收集做法 **App 存储隐私标签**。 。 。 . - 处理SDK事件并基于用户同意更新应用行为. ##### Axeptio SDK 责任 : - 显示同意管理平台(**《议定书》/《公约》缔约方会议**)接口. - 管理和储存用户同意选择. - 通过API发送同意状态. > **重要**: SDK 会的 **没有** 自动处理 **ATT 权限**如上文执行实例所示,这些内容必须由主机应用程序明确管理. ## 获取存储同意 您可以获取存储在 **Axeptio SDK 软件** 内 **用户过失** (iOS)或 (iOS) 或 (iOS) **共享优先级** (Android) (英语). 这允许您的应用程序在应用程序关闭并重新开放后访问同意状态. #### iOS (用户默认) 对于iOS,同意存储在 **用户过失** 系统。 您可以使用标准 `UserDefaults` API可以访问和检索同意数据. ```swift // Example for retrieving consents in iOS let consentStatus = UserDefaults.standard.string(forKey: "axeptioConsentStatus") ``` #### Android (共享首选项) 对Android来说,同意被存储在 **共享优先级**您可以使用该标准访问它们 `SharedPreferences` API 获取存储的同意状态 . ```java // Example for retrieving consents in Android SharedPreferences prefs = context.getSharedPreferences("axeptio", Context.MODE_PRIVATE); String consentStatus = prefs.getString("axeptioConsentStatus", "default_value"); ``` #### 获取 SDK 的同意状态 ```javascript // Get the stored consent status const consentStatus = await AxeptioSDK.getConsentStatus(); console.log('Consent status:', consentStatus); // Returns null if no consent has been set yet if (consentStatus === null) { console.log('No consent data available'); } ``` 这个 `getConsentStatus()` 方法获取 Axeptio SDK 存储的同意状态字符串。 这可以在iOS和Android平台上使用,而不需要额外的依赖性. 高级调试或获取更多与同意有关的数据: - iOS:使用特定平台的 TCF API 如 `getVendorConsents()`, (中文(简体) ), `getConsentedVendors()`等 (中文(简体) ). - 安卓: 使用 `getConsentDebugInfo()` 以获取所有共享首选数据 对于手动访问特定平台存储(仅高级使用),您仍然可以从 `UserDefaults` 在iOS上或 `SharedPreferences` 在Android上使用类似库 [反应 - 内在 - 默认偏好](https://github.com/kevinresol/react-native-default-preference)。 。 。 . ## 在需求时显示同意弹出 您可以在应用程序的生命周期内随时触发同意弹出打开. 要显示同意弹出,请使用下列方法: ```java AxeptioSdk.showConsentScreen(); ``` ## 与其他网页视图共享协议 该功能仅供 **出版商** 服务. SDK 提供了辅助函数来附加 `axeptio_token` 查询参数到任意 URL。 您可以使用存储在 SDK 中的当前用户令牌, 或者通过自定义令牌 . ```java const token = await AxeptioSdk.getAxeptioToken(); const url = await AxeptioSdk.appendAxeptioTokenURL( 'https://myurl.com', token ); // The resulting URL will be: // https://myurl.com?axeptio_token=[token] ``` ## iOS Webview 同意同步 ### 理解iOS Cookie 隔离问题 从iOS 14开始,Apple的WKWebView使用孤立的cookie存储器,不可靠地与本地应用的cookie存储器同步(Apple)`NSHTTPCookieStorage`) (中文(简体) ). 这影响到下列各方之间的同意状态同步: - 原生 SDK 同意弹出(`AxeptioSDK.showConsentScreen()`(中文(简体) ) - 基于 WebView 的安装, 装入 Axeptio 部件 **症状:** - 通过在WebView中不承认的本地弹出表示同意 - 在WebView中作出的、未经当地SDK承认的同意 - 元件不出现在物理 iOS 设备( 模拟器中的工作) - 带有双重WebView/本土执行功能的不正确弹出行为 ### 基于脚本的同步 建议的解决方案是基于符号的同步,而不是依赖cookie: #### 基本用途 ```javascript import AxeptioSDK from '@axeptio/react-native-sdk'; // Get consent data for WebView synchronization const consentData = await AxeptioSDK.getConsentDataForWebView(); // Generate JavaScript injection code const injectionScript = await AxeptioSDK.getWebViewInjectionScript(); // Use with WebView { const result = AxeptioSDK.validateWebViewSyncResult(event.nativeEvent.data); if (result.success) { console.log('Consent synchronized successfully'); } }} />; ``` #### 基于 URL 的托肯同步 对于JavaScript注射不足的情况: ```javascript // Add token parameters to URL const tokenizedUrl = await AxeptioSDK.syncConsentWithWebView( 'https://your-website.com' ); ; ``` ### 优化网络视频配置 使用iOS优化的WebView配置,以最大限度地实现同意同步可靠性: #### 自动配置 ```javascript import AxeptioSDK from '@axeptio/react-native-sdk'; // Apply all recommended iOS settings automatically ; ``` #### 手动配置 ```javascript import { IOSConfigUtils } from '@axeptio/react-native-sdk'; const config = IOSConfigUtils.getOptimizedWebViewConfig(); ; ``` ### 解决问题和诊断 #### 运行诊断测试 ```javascript // Get comprehensive diagnostic information const diagnostics = await AxeptioSDK.getDiagnosticInfo(); console.log(diagnostics); // Test WebView cookie synchronization capability const testResult = await AxeptioSDK.testWebViewCookieSync(); console.log('Test passed:', testResult.passed); console.log('Details:', testResult.details); console.log('Recommendations:', testResult.recommendations); ``` #### WebView 能力测试 用于验证 WebView 功能的注入能力测试脚本 : ```javascript const capabilityScript = AxeptioSDK.getWebViewCapabilityTestScript(); { const data = JSON.parse(event.nativeEvent.data); if (data.type === 'axeptio_webview_capability_test') { console.log('WebView capabilities:', data.results); } }} />; ``` #### 共同解决方案 1. **未出现在 iOS 物理设备上的部件 :** ```javascript // Use native-only approach on problematic iOS versions import { IOSConfigUtils } from '@axeptio/react-native-sdk'; if (IOSConfigUtils.isProblematicIOSVersion()) { // Show native popup instead AxeptioSDK.showConsentScreen(); } else { // Use WebView with proper sync const script = await AxeptioSDK.getWebViewInjectionScript(); // ... configure WebView with script } ``` 2. **Dual Webview/ Natural 冲突:** ```javascript // Remove custom WebView implementations, use SDK methods only await AxeptioSDK.initialize(/* ... */); await AxeptioSDK.setupUI(); AxeptioSDK.showConsentScreen(); // Native popup only ``` 3. **反应版本相容性问题 :** 确保所有组件使用相容的反应版本 : - 应用:反应19.x - SDK:反应19.x - 部件客户端: React 19.x (如果使用WebView) ## 清除用户同意选择 为了清除SDK存储的同意选择,使用下列方法: ```java AxeptioSdk.clearConsent(); ``` 这将删除所有存储的同意数据 . ## 活动 Axeptio SDK在用户采取与同意相关的行动时会触发各种事件通知应用程序. 要处理这些事件,你可以添加一个 `AxeptioEventListener`。这使得您可以对诸如同意弹出关闭或更新到 Google 同意模式等事件作出反应. ```java const listener: AxeptioEventListener = { onPopupClosedEvent: () => { // Retrieve consents from UserDefaults/SharedPreferences // Check user preferences // Run external processes/services based on user consents }, onGoogleConsentModeUpdate: (_consents) => { // Handle Google Consent V2 status update // You can take further actions based on the consent state }, }; // Add the listener to the Axeptio SDK AxeptioSDK.addListener(listener); ``` ### 事件源识别 SDK发送的事件(包括通过内部WebView触发的事件)包括: `event_source` 用于区分 App 和 Web 上下文的值。 这确保了分析学和KPI在Axeptio后台的正确归属. 使用的数值如下: - `sdk-app-tcf`:TCF弹出在移动应用程序内部. - `sdk-web-tcf`: TCF弹出于网页浏览器. - `sdk-app-brands`: 应用中装入的品牌部件 . - `sdk-web`: 网站上的品牌部件. 这种标记由反应原生模块中在引擎盖下使用的原生SDK组件自动处理. 详情请访问 [Axeptio 文档](https://support.axeptio.eu/hc/en-gb)。 。 。 . 我们希望这个指南能帮助你开始使用 Axeptio React Industrial SDK. 祝你们融合顺利,谢谢你们选择了Axeptio! ## 常见问题 ### @axeptio/react-native-sdk 是什么？ Axeptio 反应本地 sdk 向用户提交 cookie 同意 ### 如何安装 @axeptio/react-native-sdk？ 在项目目录运行 npm install @axeptio/react-native-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @axeptio/react-native-sdk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @axeptio/react-native-sdk 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @axeptio/react-native-sdk 可以商用吗？ @axeptio/react-native-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @axeptio/react-native-sdk 的下载量有多少？ 根据 npm 官方下载统计，@axeptio/react-native-sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,899 次，日均约 63 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @axeptio/react-native-sdk 还在维护吗？ 最新版本 2\.4\.0 发布于 2026/08/19（2 个月前）；至今共发布 23 个版本，其中过去 12 个月发布了 6 个；首次发布于 2024/05/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。