@alvie-tech/ react-native-tiktok-business-sdk (中文(简体) )
叉子为
react-native-tiktok-business-sdk由马蒂亚斯·特贝莱撰写@alvie-tech范围,并添加了 Expo 配置插件.
TikTok 商业 SDK 的回放原生桥
这个库为TikTok Business SDK提供了一个基于承诺的现代界面,使JavaScript应用程序能够初始化SDK,识别用户,并跟踪各种事件(标准,内容和自定义事件),并配有完整的TypeScript支持和全面的错误处理.
* 特性
- 📱 跨平台 - iOS和Android支持系统
- 🎯 基于承诺的API - 现代合成/等待支持
- 🔒 类型脚本 - 全面安全和情报
- 🧪 综合测试 - 100%的测试覆盖率,100+测试
- 📊 事件跟踪 - 标准、内容、定制事件和广告收入跟踪
- 🛡️ 处理错误 - 用特定错误代码处理强力错误
- 🎨 方便开发者 - 有详细文件的简单API
安装
使用 npm (或纱线) 安装软件包 :
npm install @alvie-tech/react-native-tiktok-business-sdk
yarn add @alvie-tech/react-native-tiktok-business-sdk
博览会/连续土著一代
如果您的应用程序使用 Expo( 管理或连续的土著世代) , 请添加捆绑的配置插件到 app.json 编号 : app.config.ts 在预建时间实现所需的本地编辑自动化 :
{
"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 设置
- 运行 pock 安装于您的
ios目录 :
cd ios && pod install
-
SDK会自动链接到TikTok Business SDK的依赖.
-
iOS 14+ — 应用跟踪透明: TikTok SDK 需要用户跟踪权限来报告安装和其他自动事件. 将以下密钥添加到您的
ios/<YourApp>/Info.plist数字 :
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>
自定义字符串以匹配您的应用程序使用大小写 。 没有此条目,安装事件和其他自动跟踪可能无法在iOS 14+上正确运行.
Android 设置
-
SDK依赖通过Gradle自动包含.
-
添加ProGuard规则以防止代码模糊(参见 ProGuard 区域 页:1.
使用量
以下是如何使用被库所曝光的各种方法的例子.
导入图书馆
该套件暴露出一个主要对象TikTok Business,它将所有的方法和谜团集合在一起. 例如:
import { TikTokBusiness } from '@alvie-tech/react-native-tiktok-business-sdk';
初始化 SDK
在使用任何事件跟踪方法之前,必须初始化SDK. 你可以打电话 initializeSdk 使用您的appId, tiktokAppId, accessToken, 以及可选设置调试模式 .
单 TikTok App 标识
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 的事件 :
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);
}
}
或者,您还可以使用逗号分隔的字符串格式 :
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 对象 :
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 报告用户信息的方法。 需要所有参数.
async function identifyUser() {
try {
await TikTokBusiness.identify(
'user_12345', // External user ID (required)
'john_doe', // External user name (required)
'+1234567890', // Phone number (required)
'[email protected]' // Email address (required)
);
console.log('User identified successfully!');
} catch (error) {
console.error('Error identifying user:', error);
// Handle identification errors
}
}
注销
使用 logout 方法 :
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和附加属性.
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。该方法接受事件类型字符串和参数对象.
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 并传递事件名称和属性对象.
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等广告网络进行货币化跟踪很有用.
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 服务器 。 如果您想要确保立即发送事件, 如在应用程序终止前, 这将会有用 .
async function flushEvents() {
try {
await TikTokBusiness.flush();
console.log('Events flushed successfully!');
} catch (error) {
console.error('Error flushing events:', error);
}
}
说明: 事件通常定期自动发送. 只当您需要即时同步时使用 .
API 参考
可用方法
所有方法都返回承诺和支持同步/等待模式:
// 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 接口
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等)
完整导入示例
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以特定错误代码提供全面的错误处理:
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数字 :
-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.** { *; }
解决问题
共同问题
-
"TikTok BusinessMudule. 初始化Sdk获得 X 参数,期望 Y"
- 确保您通过所有必要的参数,包括新参数
accessToken - 请检查access-date=中的日期值 (帮助)
- 确保您通过所有必要的参数,包括新参数
-
"包裹似乎没有联系"
- 运行
npx react-native clean重建您的项目 - 对于iOS:
cd ios && pod install && cd .. - 对于Android:
cd android && ./gradlew clean && cd ..
- 运行
-
TikTok 事件管理器中未出现的事件
- 检查您
accessToken正确且有适当的权限 - 检查您的应用程序 ID 和 TikTok App ID 配置正确
- 启用调试模式以查看详细记录
- 检查您
捐款
见 贡献指南 学习如何为储存库和我们的发展工作流程作出贡献.
许可证
麻省理工学院
更改日志
见 变动情况 详细发布注释和版本历史.