@axeptio/react-native-sdk

中文文档

2.4.0发布于 2026/08/19MITTypeScriptESM + CJS零依赖近 30 天下载 1899

Axeptio 反应本地 sdk 向用户提交 cookie 同意

文档目录17 节

目录
GitHub 访问托肯设置
设置
在应用程序启动时启动 SDK
ATT(跟踪透明度) 整合说明:
责任:移动App vs SDK
获取存储同意
在需求时显示同意弹出
与其他网页视图共享协议
iOS Webview 同意同步
理解iOS Cookie 隔离问题
基于脚本的同步
优化网络视频配置
解决问题和诊断
清除用户同意选择
活动
事件源识别

被否决:这个SDK不再维持. 请使用 Axeptio 无头CMP客户端相反,它提供了一个反应土著的实施。见反应本地示例要开始.

Axeptio 反应原生 SDK 集成

该存储库演示如何执行 Axeptio 反应原生 SDK 输入您的移动应用程序,处理用户同意遵守GDPR和其他隐私条例的问题.

SDK既适用于品牌,也适用于出版商,这取决于您的使用情况和要求.

GitHub 访问托肯设置

当设置您的项目或访问某些 GitHub 服务时, 您可能会被提示创建 GitHub Access Token 。请注意,产生这一标志要求:

一个有效的 GitHub 账户。。。 .
双要素认证(2FA) 启用 .

为了避免设置过程中的认证问题,我们建议审查官方 GitHub 访问托肯文档或关于如何创建令牌和确保2FA正确配置的详细指示. 遵循这些步骤将有助于你平稳地生成一个符号并减少登机摩擦.

设置

安装

安装 Axeptio 反应原生 SDK,运行以下命令之一:

使用 npm :

npm install --save @axeptio/react-native-sdk

使用线条 :

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] 瞄准镜需要 [读:包装,回

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。。。 .
运行以下命令以安装依赖性 :

npx pod-install

您可以在示例文件夹请检查文件夹中是否有更详细的执行实例.

在应用程序启动时启动 SDK

以初始化 Axeptio 反应原生 SDK 在您的应用程序中,您需要设置当您的应用程序启动时。 SDK可以被配置为不同的使用案例,例如品牌或出版商,使用 AxeptioService um. 这使得您可以根据自己的具体需要定制SDK(例如处理品牌或出版商的GDPR同意).

以下是如何初始化SDK的分步指南:

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许可 应该共存.

苹果准则

您的应用程序必须遵从苹果公司的准则用于披露您的应用程序所收集的数据,并请求用户允许进行跟踪.

为了管理ATT,你可以使用反应-内在跟踪-透明部件.

ATT 流量:确保ATT提示在您在 Axeptio CMP 中请求同意之前显示给用户. 这确保了您遵守苹果公司的隐私要求.
苹果的ATT准则: 确保您遵循苹果的ATT准则适当执行.

纳入武器贸易条约的步骤:

安装库数字 : 你需要安装 react-native-tracking-transparency 用于处理ATT请求的库.

使用 npm :

   npm install --save react-native-tracking-transparency

或用纱线:

yarn add react-native-tracking-transparency

更新 Info.plist数字 : 将以下密钥添加到您的 Info.plist 解释为什么您的应用程序需要用户跟踪的文件 :

<key>NSUserTrackingUsageDescription</key>
<string>Explain why you need user tracking</string>

管理ATT弹出数字 : 在显示 Axeptio CMP UI 之前,您需要请求ATT 许可并处理用户的响应. 这是你如何管理ATT弹出:

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可以访问和检索同意数据.

// Example for retrieving consents in iOS
let consentStatus = UserDefaults.standard.string(forKey: "axeptioConsentStatus")

Android (共享首选项)

对Android来说,同意被存储在 共享优先级您可以使用该标准访问它们 SharedPreferences API 获取存储的同意状态 .

// Example for retrieving consents in Android
SharedPreferences prefs = context.getSharedPreferences("axeptio", Context.MODE_PRIVATE);
String consentStatus = prefs.getString("axeptioConsentStatus", "default_value");

// 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上使用类似库反应 - 内在 - 默认偏好。。。 .

您可以在应用程序的生命周期内随时触发同意弹出打开. 要显示同意弹出,请使用下列方法:

AxeptioSdk.showConsentScreen();

该功能仅供 出版商 服务.

SDK 提供了辅助函数来附加 axeptio_token 查询参数到任意 URL。您可以使用存储在 SDK 中的当前用户令牌, 或者通过自定义令牌 .

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 14开始,Apple的WKWebView使用孤立的cookie存储器,不可靠地与本地应用的cookie存储器同步(Apple)NSHTTPCookieStorage) (中文(简体) ). 这影响到下列各方之间的同意状态同步:

原生 SDK 同意弹出(AxeptioSDK.showConsentScreen()(中文(简体) )
基于 WebView 的安装, 装入 Axeptio 部件

症状:

通过在WebView中不承认的本地弹出表示同意
在WebView中作出的、未经当地SDK承认的同意
元件不出现在物理 iOS 设备( 模拟器中的工作)
带有双重WebView/本土执行功能的不正确弹出行为

基于脚本的同步

建议的解决方案是基于符号的同步,而不是依赖cookie:

基本用途

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
<WebView
  source={{ uri: 'https://your-website.com' }}
  injectedJavaScript={injectionScript}
  onMessage={(event) => {
    const result = AxeptioSDK.validateWebViewSyncResult(event.nativeEvent.data);
    if (result.success) {
      console.log('Consent synchronized successfully');
    }
  }}
/>;

基于 URL 的托肯同步

对于JavaScript注射不足的情况:

// Add token parameters to URL
const tokenizedUrl = await AxeptioSDK.syncConsentWithWebView(
  'https://your-website.com'
);

<WebView source={{ uri: tokenizedUrl }} />;

优化网络视频配置

使用iOS优化的WebView配置,以最大限度地实现同意同步可靠性:

自动配置

import AxeptioSDK from '@axeptio/react-native-sdk';

// Apply all recommended iOS settings automatically
<WebView
  {...AxeptioSDK.getWebViewProps()}
  source={{ uri: 'https://your-website.com' }}
/>;

手动配置

import { IOSConfigUtils } from '@axeptio/react-native-sdk';

const config = IOSConfigUtils.getOptimizedWebViewConfig();

<WebView
  incognito={config.incognito} // false - enable cookie sharing
  cacheEnabled={config.cacheEnabled} // false - prevent stale consent state
  sharedCookiesEnabled={config.sharedCookiesEnabled} // true - attempt cookie sync
  source={{ uri: 'https://your-website.com' }}
/>;

解决问题和诊断

运行诊断测试

// 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 功能的注入能力测试脚本 :

const capabilityScript = AxeptioSDK.getWebViewCapabilityTestScript();

<WebView
  source={{ uri: 'https://your-website.com' }}
  injectedJavaScript={capabilityScript}
  onMessage={(event) => {
    const data = JSON.parse(event.nativeEvent.data);
    if (data.type === 'axeptio_webview_capability_test') {
      console.log('WebView capabilities:', data.results);
    }
  }}
/>;

共同解决方案

未出现在 iOS 物理设备上的部件 :

// 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
}

Dual Webview/ Natural 冲突:

// Remove custom WebView implementations, use SDK methods only
await AxeptioSDK.initialize(/* ... */);
await AxeptioSDK.setupUI();
AxeptioSDK.showConsentScreen(); // Native popup only

反应版本相容性问题 : 确保所有组件使用相容的反应版本 :
- 应用:反应19.x
- SDK:反应19.x
- 部件客户端: React 19.x (如果使用WebView)

为了清除SDK存储的同意选择,使用下列方法:

AxeptioSdk.clearConsent();

这将删除所有存储的同意数据 .

活动

Axeptio SDK在用户采取与同意相关的行动时会触发各种事件通知应用程序.

要处理这些事件,你可以添加一个 AxeptioEventListener。这使得您可以对诸如同意弹出关闭或更新到 Google 同意模式等事件作出反应.

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 文档。。。 . 我们希望这个指南能帮助你开始使用 Axeptio React Industrial SDK. 祝你们融合顺利,谢谢你们选择了Axeptio!

版本与发布记录

@axeptio/react-native-sdk 共发布 23 个版本，首次发布于 2024/05/23；过去 12 个月发布了 6 个版本。

版本	发布日期	距今
`2.4.0`latest	2026/08/19	2 个月前
`2.2.0-beta.1`beta	2026/04/30	6 个月前
`2.1.0`	2026/02/16	8 个月前
`2.1.0-beta.4`	2026/01/28	9 个月前
`2.1.0-beta.3`	2026/01/27	9 个月前
`2.1.0-beta.2`	2026/01/27	9 个月前

关于 @axeptio/react-native-sdk 的常见问题

@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 和提交记录判断。

npm install @axeptio/react-native-sdk

pnpmpnpm add @axeptio/react-native-sdk
yarnyarn add @axeptio/react-native-sdk
bunbun add @axeptio/react-native-sdk

peer 依赖react *react-native *

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

1,899

约 1899 次日均 63 次

统计周期 2026/10/08 – 2026/11/06
数据来自 npm 官方下载统计，1 天前更新

最新版本2.4.0发布于 2 个月前

开源许可MIT宽松许可

包体积157 kB49 个文件 · 解压后

运行依赖0 个另有 2 个 peer 依赖

模块格式ESM + CJS

TypeScript自带类型

发布版本23 个近 12 个月 6 个

首次发布2024/05/232 年前

元数据更新2026/09/14

每一个软件包背后，
都有分享与创造的人。

@axeptio/react-native-sdk

Axeptio 反应原生 SDK 集成

目录

GitHub 访问托肯设置

设置

安装

使用 npm :

使用线条 :

Android 设置

iOS 设置

在应用程序启动时启动 SDK

参数:

ATT(跟踪透明度) 整合说明:

苹果准则

纳入武器贸易条约的步骤:

责任:移动App vs SDK

移动应用程序责任:

Axeptio SDK 责任 :

获取存储同意

iOS (用户默认)

Android (共享首选项)

获取 SDK 的同意状态

在需求时显示同意弹出

与其他网页视图共享协议

iOS Webview 同意同步

理解iOS Cookie 隔离问题

基于脚本的同步

基本用途

基于 URL 的托肯同步

优化网络视频配置

自动配置

手动配置

解决问题和诊断

运行诊断测试

WebView 能力测试

共同解决方案

清除用户同意选择

活动

事件源识别

版本与发布记录

关于 @axeptio/react-native-sdk 的常见问题

@axeptio/react-native-sdk 是什么？

如何安装 @axeptio/react-native-sdk？

@axeptio/react-native-sdk 支持 TypeScript 吗？

@axeptio/react-native-sdk 支持 ESM 还是 CommonJS？

@axeptio/react-native-sdk 可以商用吗？

@axeptio/react-native-sdk 的下载量有多少？

@axeptio/react-native-sdk 还在维护吗？