# @alvie-tech/react-native-tiktok-business-sdk 中文文档

规范地址：https://npmcn.com/package/%40alvie-tech/react-native-tiktok-business-sdk/

版本：1\.7\.2
npm 元数据更新时间：2026-11-05T12:12:24.481Z
中文译文更新时间：2026-11-05T23:33:22.262Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alvie-tech/react-native-tiktok-business-sdk
原文对照：https://npmcn.com/package/%40alvie-tech/react-native-tiktok-business-sdk/?lang=original
项目主页：https://github.com/alvie-tech/react-native-tiktok-business-sdk#readme
源码仓库：https://github.com/alvie-tech/react-native-tiktok-business-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：142 kB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：expo \>=50\.0\.0，react \*，react-native \*
- 首次发布：2026-06-02T13:33:20.827Z
- 最新版本发布：2026-11-05T12:12:24.293Z
- 近 30 天下载量：9404（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

TikTok 商业 SDK 的回放原生桥

## 安装

```sh
npm install @alvie-tech/react-native-tiktok-business-sdk
```

也可以使用：`pnpm add @alvie-tech/react-native-tiktok-business-sdk`、`yarn add @alvie-tech/react-native-tiktok-business-sdk`、`bun add @alvie-tech/react-native-tiktok-business-sdk`

## README

# @alvie-tech/ react-native-tiktok-business-sdk (中文(简体) )

[![npm version](https://img.shields.io/npm/v/@alvie-tech/react-native-tiktok-business-sdk.svg)](https://www.npmjs.com/package/@alvie-tech/react-native-tiktok-business-sdk) [![Build Status](https://img.shields.io/github/actions/workflow/status/alvie-tech/react-native-tiktok-business-sdk/ci.yml)](https://github.com/alvie-tech/react-native-tiktok-business-sdk/actions) [![npm downloads](https://img.shields.io/npm/dw/@alvie-tech/react-native-tiktok-business-sdk.svg)](https://www.npmjs.com/package/@alvie-tech/react-native-tiktok-business-sdk) [![License](https://img.shields.io/npm/l/@alvie-tech/react-native-tiktok-business-sdk.svg)](https://github.com/alvie-tech/react-native-tiktok-business-sdk/blob/main/LICENSE)

> 叉子为 [`react-native-tiktok-business-sdk`](https://github.com/mtebele/react-native-tiktok-business-sdk) 由马蒂亚斯·特贝莱撰写 `@alvie-tech` 范围,并添加了 Expo 配置插件.

TikTok 商业 SDK 的回放原生桥

这个库为TikTok Business SDK提供了一个基于承诺的现代界面,使JavaScript应用程序能够初始化SDK,识别用户,并跟踪各种事件(标准,内容和自定义事件),并配有完整的TypeScript支持和全面的错误处理.

## \* 特性

-   📱 **跨平台** - iOS和Android支持系统
-   🎯 **基于承诺的API** - 现代合成/等待支持
-   🔒 **类型脚本** - 全面安全和情报
-   🧪 **综合测试** - 100%的测试覆盖率,100+测试
-   📊 **事件跟踪** - 标准、内容、定制事件和广告收入跟踪
-   🛡️ **处理错误** - 用特定错误代码处理强力错误
-   🎨 **方便开发者** - 有详细文件的简单API

## 安装

使用 npm (或纱线) 安装软件包 :

```sh
npm install @alvie-tech/react-native-tiktok-business-sdk

yarn add @alvie-tech/react-native-tiktok-business-sdk
```

### 博览会/连续土著一代

如果您的应用程序使用 Expo( 管理或连续的土著世代) , 请添加捆绑的配置插件到 `app.json` 编号 : `app.config.ts` 在预建时间实现所需的本地编辑自动化 :

```json
{
  "expo": {
    "plugins": [
      [
        "@alvie-tech/react-native-tiktok-business-sdk",
        {
          "ios": {
            "tiktokAppId": "YOUR_IOS_TIKTOK_APP_ID",
            "skAdNetworkIds": ["abc1234567.skadnetwork"],
            "userTrackingPermission": "This identifier will be used to deliver personalized ads to you."
          },
          "android": {
            "tiktokAppId": "YOUR_ANDROID_TIKTOK_APP_ID"
          }
        }
      ]
    ]
  }
}
```

自动插件 :

-   附录 `22mmun2rn5.skadnetwork` (TikTok的 SKadNetwork 标识符) 到 `SKAdNetworkItems` 内 `Info.plist`
-   附录 `tiktok`, (中文(简体) ), `snssdk1233` 财务报告和审定财务报表 `snssdk1180` 改为 `LSApplicationQueriesSchemes` 内 `Info.plist`
-   写下 `TikTokAppID` 键入 `Info.plist` 何时 `ios.tiktokAppId` 提供
-   写作 `NSUserTrackingUsageDescription` 何时 `ios.userTrackingPermission` 提供——如果 `expo-tracking-transparency` 已经为您的应用程序管理过
-   添加 `com.tiktok.sdk.AppId` `<meta-data>` 条目为 `AndroidManifest.xml` 何时 `android.tiktokAppId` 提供

所有mods都是独家:运行 `expo prebuild` 多次不会重复条目。 更新配置后, 将本地项目重新生成 `npx expo prebuild --clean`。 。 。 .

### iOS 设置

1.  运行 pock 安装于您的 `ios` 目录 :

```sh
cd ios && pod install
```

2.  SDK会自动链接到TikTok Business SDK的依赖.
    
3.  **iOS 14+ — 应用跟踪透明**: TikTok SDK 需要用户跟踪权限来报告安装和其他自动事件. 将以下密钥添加到您的 `ios/<YourApp>/Info.plist`数字 :
    

```xml
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>
```

自定义字符串以匹配您的应用程序使用大小写 。 没有此条目,安装事件和其他自动跟踪可能无法在iOS 14+上正确运行.

### Android 设置

1.  SDK依赖通过Gradle自动包含.
    
2.  添加ProGuard规则以防止代码模糊(参见 [ProGuard 区域](https://npmcn.com/package/%40alvie-tech/react-native-tiktok-business-sdk/#readme-proguard-android) 页:1.
    

## 使用量

以下是如何使用被库所曝光的各种方法的例子.

### 导入图书馆

该套件暴露出一个主要对象TikTok Business,它将所有的方法和谜团集合在一起. 例如:

```js
import { TikTokBusiness } from '@alvie-tech/react-native-tiktok-business-sdk';
```

### 初始化 SDK

在使用任何事件跟踪方法之前,必须初始化SDK. 你可以打电话 `initializeSdk` 使用您的appId, tiktokAppId, accessToken, 以及可选设置调试模式 .

#### 单 TikTok App 标识

```js
async function initializeTikTokSDK() {
  try {
    await TikTokBusiness.initializeSdk(
      'YOUR_APP_ID',         // Your app ID (e.g., Android package name or iOS bundle ID)
      'YOUR_TIKTOK_APP_ID',  // Your TikTok App ID from TikTok Events Manager
      'YOUR_ACCESS_TOKEN',   // Your access token from TikTok Events Manager (REQUIRED)
      true                   // Enable debug mode (optional, defaults to false)
    );
    console.log('TikTok SDK initialized successfully!');
    // SDK is now initialized, and tracking is active.
  } catch (error) {
    console.error('Error initializing TikTok SDK:', error);
    // Handle initialization errors (network issues, invalid credentials, etc.)
  }
}

initializeTikTokSDK();
```

#### 多个 TikTok 应用程序ID

从 SDK v1.3. 1 开始, 您可以通过一个数组来跟踪多个 TikTok App ID 的事件 :

```js
async function initializeTikTokSDKWithMultipleAppIds() {
  try {
    await TikTokBusiness.initializeSdk(
      'YOUR_APP_ID',
      ['TIKTOK_APP_ID_1', 'TIKTOK_APP_ID_2', 'TIKTOK_APP_ID_3'],  // Array of TikTok App IDs
      'YOUR_ACCESS_TOKEN',
      true
    );
    console.log('TikTok SDK initialized with multiple App IDs!');
  } catch (error) {
    console.error('Error initializing TikTok SDK:', error);
  }
}
```

或者,您还可以使用逗号分隔的字符串格式 :

```js
await TikTokBusiness.initializeSdk(
  'YOUR_APP_ID',
  '11,22,33',  // Comma-separated App IDs (no spaces)
  'YOUR_ACCESS_TOKEN',
  true
);
```

**重要审定规则:**

-   App ID 必须是数字字符串
-   不允许以逗号分隔格式设置空格
-   没有跟踪或引导逗号
-   为更好的可读性和类型安全性推荐了阵列格式
-   所有 TikTok App ID 必须匹配您的 App ID( SDK 要求)

#### 禁用自动跟踪事件

默认情况下,TikTok SDK会自动报告安装,发射,2D-保留,以及应用中的购买事件. 您可以在初始化时通过一个可选选项来禁用其中的任何一个 `options` 对象 :

```js
import { TikTokBusiness } from '@alvie-tech/react-native-tiktok-business-sdk';
import type { TikTokSdkConfig } from '@alvie-tech/react-native-tiktok-business-sdk';

// Disable all automatic events
await TikTokBusiness.initializeSdk(
  'YOUR_APP_ID',
  'YOUR_TIKTOK_APP_ID',
  'YOUR_ACCESS_TOKEN',
  false,
  { disableAutoTracking: true }
);

// Or disable specific events
const options: TikTokSdkConfig = {
  disableInstallTracking: true,       // Don't report install event
  disableLaunchTracking: true,        // Don't report app launch event
  disableRetentionTracking: true,     // Don't report 2D-retention event
  disablePaymentTracking: true,       // Don't report automatic IAP event
  disableSKAdNetworkSupport: true,    // iOS only: disable automatic SKAdNetwork support
};

await TikTokBusiness.initializeSdk(
  'YOUR_APP_ID',
  'YOUR_TIKTOK_APP_ID',
  'YOUR_ACCESS_TOKEN',
  false,
  options
);
```

> **说明:** 所有现有的没有 `options` 论点继续维持不变.

### 识别用户

打电话 `identify` 报告用户信息的方法。 需要所有参数.

```js
async function identifyUser() {
  try {
    await TikTokBusiness.identify(
      'user_12345',           // External user ID (required)
      'john_doe',             // External user name (required)
      '+1234567890',          // Phone number (required)
      'john@example.com'      // Email address (required)
    );
    console.log('User identified successfully!');
  } catch (error) {
    console.error('Error identifying user:', error);
    // Handle identification errors
  }
}
```

### 注销

使用 `logout` 方法 :

```js
async function logoutUser() {
  try {
    await TikTokBusiness.logout();
    console.log('User logged out successfully!');
  } catch (error) {
    console.error('Error logging out:', error);
    // Handle logout errors
  }
}
```

### 跟踪标准事件

使用 `trackEvent` 报告标准事件。 您可以选择通过事件ID和附加属性.

```js
import { TikTokBusiness, TikTokEventName } from '@alvie-tech/react-native-tiktok-business-sdk';

async function trackStandardEvent() {
  try {
    // Simple event tracking
    await TikTokBusiness.trackEvent(TikTokEventName.REGISTRATION);
    
    // Event with custom ID and properties
    await TikTokBusiness.trackEvent(
      TikTokEventName.SEARCH,
      'search_001',                    // Optional event ID
      {                               // Optional properties
        query: 'coffee',
      }
    );
    
    console.log('Standard event tracked successfully!');
  } catch (error) {
    console.error('Error tracking standard event:', error);
  }
}
```

### 跟踪内容事件

对于需要内容细节的事件(如"ADD TO CART","CHECK OUT"等),使用 `trackContentEvent`。该方法接受事件类型字符串和参数对象.

```js
import { 
  TikTokBusiness, 
  TikTokContentEventName, 
  TikTokContentEventParameter, 
  TikTokContentEventContentsParameter 
} from '@alvie-tech/react-native-tiktok-business-sdk';

async function trackContentEvent() {
  try {
    await TikTokBusiness.trackContentEvent(TikTokContentEventName.PURCHASE, {
      [TikTokContentEventParameter.CURRENCY]: 'USD',
      [TikTokContentEventParameter.VALUE]: '29.99',
      [TikTokContentEventParameter.CONTENT_TYPE]: 'product',
      [TikTokContentEventParameter.DESCRIPTION]: 'Premium coffee purchase',
      [TikTokContentEventParameter.CONTENTS]: [
        {
          [TikTokContentEventContentsParameter.CONTENT_ID]: 'coffee_001',
          [TikTokContentEventContentsParameter.CONTENT_NAME]: 'Premium Coffee',
          [TikTokContentEventContentsParameter.BRAND]: 'Coffee Brand',
          [TikTokContentEventContentsParameter.PRICE]: 29.99,
          [TikTokContentEventContentsParameter.QUANTITY]: 1,
        },
      ],
    });
    
    console.log('Content event tracked successfully!');
  } catch (error) {
    console.error('Error tracking content event:', error);
  }
}
```

### 跟踪自定义事件

如果你需要报告一个不符合标准的事件,请使用 `trackCustomEvent` 并传递事件名称和属性对象.

```js
async function trackCustomEvent() {
  try {
    await TikTokBusiness.trackCustomEvent('user_achievement', {
      description: 'Level Completed!',
    });
    
    console.log('Custom event tracked successfully!');
  } catch (error) {
    console.error('Error tracking custom event:', error);
  }
}
```

### 跟踪税收事件

使用 `trackAdRevenueEvent` 方法。 这对使用AdMob,Unity,Iron Source等广告网络进行货币化跟踪很有用.

```js
import { TikTokBusiness, trackAdRevenueEvent } from '@alvie-tech/react-native-tiktok-business-sdk';
import type { AdRevenueData } from '@alvie-tech/react-native-tiktok-business-sdk';

async function trackAdRevenue() {
  try {
    const adRevenueData: AdRevenueData = {
      revenue: 0.05,              // Revenue amount
      currency: 'USD',            // Currency code
      adNetwork: 'AdMob',         // Ad network name
      adUnit: 'banner_main',      // Ad unit identifier
      adFormat: 'banner',         // Ad format (banner, interstitial, rewarded)
      placement: 'home_screen',   // Placement in your app
      country: 'US',              // Country code
      precision: 'exact',         // Precision level
    };

    // Track ad revenue with optional event ID
    await trackAdRevenueEvent(adRevenueData, 'ad-revenue-001');
    
    console.log('Ad revenue tracked successfully!');
  } catch (error) {
    console.error('Error tracking ad revenue:', error);
  }
}

// Alternative: Use standard event tracking
async function trackImpressionEvent() {
  try {
    await TikTokBusiness.trackEvent(TikTokEventName.IMPRESSION_LEVEL_AD_REVENUE);
    console.log('Impression event tracked successfully!');
  } catch (error) {
    console.error('Error tracking impression event:', error);
  }
}
```

### Flush 事件

手动将待决事件冲入 TikTok 服务器 。 如果您想要确保立即发送事件, 如在应用程序终止前, 这将会有用 .

```js
async function flushEvents() {
  try {
    await TikTokBusiness.flush();
    console.log('Events flushed successfully!');
  } catch (error) {
    console.error('Error flushing events:', error);
  }
}
```

> **说明:** 事件通常定期自动发送. 只当您需要即时同步时使用 .

## API 参考

### 可用方法

所有方法都返回承诺和支持同步/等待模式:

```typescript
// Initialize SDK (required before any other calls)
initializeSdk(appId: string, ttAppId: string | string[], accessToken: string, debug?: boolean): Promise<string>

// User management
identify(externalId: string, externalUserName: string, phoneNumber: string, email: string): Promise<string>
logout(): Promise<string>

// Event tracking
trackEvent(eventName: TikTokEventName, eventId?: string, properties?: object): Promise<string>
trackContentEvent(eventName: TikTokContentEventName, properties?: object): Promise<string>
trackCustomEvent(eventName: string, properties?: object): Promise<string>
trackAdRevenueEvent(adRevenueData: AdRevenueData, eventId?: string): Promise<string>

// Other
flush(): Promise<string>
```

### 类型

#### AdRevenueData 接口

```typescript
interface AdRevenueData {
  revenue?: number;        // Revenue amount in specified currency
  currency?: string;       // Currency code (e.g., 'USD', 'EUR')
  adNetwork?: string;      // Ad network name (e.g., 'AdMob', 'Unity', 'IronSource')
  adUnit?: string;         // Ad unit identifier
  adFormat?: string;       // Ad format (e.g., 'banner', 'interstitial', 'rewarded')
  placement?: string;      // Placement identifier in your app
  country?: string;        // Country code where ad was shown
  precision?: string;      // Precision level of revenue data
  [key: string]: string | number | boolean | undefined; // Additional custom properties
}
```

### 数字

图书馆输出以下语句,以确保报告活动的一致性:

-   **TikTokEvent 语法Name** - 标准事件名称(LOGIN、登记、PURCHASE等)
-   **TikTok 活动Name** - 内容事件名称(ADD TO CART,VIEW CONTENT等)
-   **TikTok 活动** - 内容活动的参数(CURRENCY、VALUE等)
-   **TikTok 活动** - 内容项目的参数(CONTENT ID、PICE等)

### 完整导入示例

```js
import {
  TikTokBusiness,
  trackAdRevenueEvent,
  TikTokEventName,
  TikTokContentEventName,
  TikTokContentEventParameter,
  TikTokContentEventContentsParameter,
} from '@alvie-tech/react-native-tiktok-business-sdk';
import type { AdRevenueData } from '@alvie-tech/react-native-tiktok-business-sdk';
```

## 处理错误

SDK以特定错误代码提供全面的错误处理:

```js
try {
  await TikTokBusiness.initializeSdk(appId, ttAppId, accessToken, debug);
} catch (error) {
  switch (error.code) {
    case 'INIT_ERROR':
      console.error('Failed to initialize SDK:', error.message);
      break;
    case 'IDENTIFY_ERROR':
      console.error('Failed to identify user:', error.message);
      break;
    case 'TRACK_EVENT_ERROR':
      console.error('Failed to track event:', error.message);
      break;
    default:
      console.error('Unknown error:', error.message);
  }
}
```

## 所需资源

-   反应原生0.60+
-   iOS 11.0+ (中文(简体) )
-   Android API 级别 16+

## ProGuard (Android) (英语)

如果你用"ProGuard"来混淆代码, 把这些规则加进你的 `proguard-rules.pro`数字 :

```java
-keep class com.tiktok.** { *; }
-keep class com.android.billingclient.api.** { *; }
-keep interface com.android.billingclient.api.* { *; }
-keep class androidx.lifecycle.** { *; }
-keep class com.android.installreferrer.** { *; }
```

## 解决问题

### 共同问题

1.  **"TikTok BusinessMudule. 初始化Sdk获得 X 参数,期望 Y"**
    
    -   确保您通过所有必要的参数,包括新参数 `accessToken`
    -   请检查access-date=中的日期值 (帮助)
2.  **"包裹似乎没有联系"**
    
    -   运行 `npx react-native clean` 重建您的项目
    -   对于iOS: `cd ios && pod install && cd ..`
    -   对于Android: `cd android && ./gradlew clean && cd ..`
3.  **TikTok 事件管理器中未出现的事件**
    
    -   检查您 `accessToken` 正确且有适当的权限
    -   检查您的应用程序 ID 和 TikTok App ID 配置正确
    -   启用调试模式以查看详细记录

## 捐款

见 [贡献指南](https://npmcn.com/package/%40alvie-tech/react-native-tiktok-business-sdk/CONTRIBUTING.md) 学习如何为储存库和我们的发展工作流程作出贡献.

## 许可证

麻省理工学院

* * *

## 更改日志

见 [变动情况](https://npmcn.com/package/%40alvie-tech/react-native-tiktok-business-sdk/CHANGELOG.md) 详细发布注释和版本历史.

## 常见问题

### @alvie-tech/react-native-tiktok-business-sdk 是什么？

TikTok 商业 SDK 的回放原生桥

### 如何安装 @alvie-tech/react-native-tiktok-business-sdk？

在项目目录运行 npm install @alvie-tech/react-native-tiktok-business-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alvie-tech/react-native-tiktok-business-sdk 支持 TypeScript 吗？

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

### @alvie-tech/react-native-tiktok-business-sdk 支持 ESM 还是 CommonJS？

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

### @alvie-tech/react-native-tiktok-business-sdk 可以商用吗？

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

### @alvie-tech/react-native-tiktok-business-sdk 的下载量有多少？

根据 npm 官方下载统计，@alvie-tech/react-native-tiktok-business-sdk 在 2026/10/06 – 2026/11/04 这 30 天内被下载 9,404 次，日均约 313 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alvie-tech/react-native-tiktok-business-sdk 还在维护吗？

最新版本 1\.7\.2 发布于 2026/11/05（今天）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/06/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。