react-native-quicktracking-analytics-module 2.0.2 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 @钰昭
+Copyright (c) 2025 yuzhao
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

package/QuicktrackingAnalyticsModule.podspec

@@ -0,0 +1,29 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "QuicktrackingAnalyticsModule"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://www.github.com/rn_qt_analytics.git.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm}"
+
+  s.dependency "React-Core"
+  s.dependency "QTCommon", "~> 1.7.1.PX"
+  s.dependency "UMCommonLog"
+
+# Use install_modules_dependencies helper to install the dependencies if React Native version >=0.71.0.
+# See https://github.com/facebook/react-native/blob/febf6b7f33fdb4904669f99d795eba4c0f95d7bf/scripts/cocoapods/new_architecture.rb#L79.
+if respond_to?(:install_modules_dependencies, true)
+  install_modules_dependencies(s)
+else
+  s.dependency "React-Core"
+end
+end

package/README.md

@@ -15,18 +15,22 @@ pnpm add react-native-quicktracking-analytics-module
 ```
 ## 引入SDK环境变量
 ```tsx
-import { QT } from "react-native-quicktracking-analytics-module";
+import * as QT from "react-native-quicktracking-analytics-module";
 ```
-## Android 基座集成
+
+## AppKey和收数域名获取
 ### 进入控制台
-进入QT后台，点击“管理控制台”
-![image.png](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/220937/1646903919683-276177f8-42a7-4f6e-87aa-fff88ae87a77.png#clientId=u468f5541-19bf-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=790&id=VqtE7&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1580&originWidth=2878&originalType=binary&ratio=1&rotation=0&showTitle=false&size=2103957&status=done&style=none&taskId=ua2f5b36f-3995-47d2-909b-a42abba8f55&title=&width=1439)
+进入QT后台，点击“管理控制台”<br>
+
+![alt text](image.png)
+
 
 ### 集成应用
-找到需要集成埋点的应用：进入“应用列表”，选择所需组织，点击操作中的“详情或者去集成”
-![image.png](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/64356327/1668567046473-aab9b13d-38fe-4e33-bd03-e5bedc69b0e4.png#clientId=uf7b76841-8b1b-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=602&id=ub77f00bf&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1204&originWidth=2562&originalType=binary&ratio=1&rotation=0&showTitle=false&size=646074&status=done&style=none&taskId=ube368388-293d-4ce2-a7ad-9aca1566a87&title=&width=1281)
+找到需要集成埋点的应用：进入“应用列表”，选择所需组织，点击操作中的“详情或者去集成”<br>
 
-### Maven地址配置
+![alt text](image-1.png)
+
+## Android 基座配置
 在工程 build.gradle 配置脚本中 buildscript 和 allprojects 段中添加 sdk maven 仓库地址
 ```groovy
 buildscript {
@@ -50,16 +54,6 @@ allprojects {
 }
 ```
 
-### 组件引用
-在工程app对应build.gradle配置脚本dependencies段中，添加集成所需要的依赖
-```groovy
-dependencies {
-  implementation fileTree(include:['*.jar'], dir:'libs')
-
-  implementation "com.umeng.umsdk:qt-px-common:1.4.0.PX"
-}
-```
-
 ### 埋点验证配置
 在Android.manifest中，找到MainActivity对应的activity标签，并将以下代码粘贴进去，appkey换成自己的
 ```xml
@@ -101,6 +95,9 @@ dependencies {
 -keep class com.umeng.** {*;}
 -keep class org.repackage.** {*;}
 
+-keep class com.quick.qt.** {*;}
+-keep class rpk.quick.qt.** {*;}
+
 -keepclassmembers class * {
    public <init> (org.json.JSONObject);
 }
@@ -117,96 +114,21 @@ SDK需要引用导入工程的资源文件，通过了反射机制得到资源
 }
 ```
 
-### 初始化SDK
-
-1. 域名设置
-
-务必在初始化之前设置私有化环境收数域名。
-```java
-/**
-* 设置上传统计日志的主域名和备用域名。SDK会优先将统计数据上报到主域名，失败的情况下会再尝试将数据上报到备用域名。
-* 主域名primaryDomain或不能传入null或者空串，否则会抛出SdkDomainUndefined运行时异常。
-*/
-
-QtConfigure.setCustomDomain("收数域名", null);
-```
-
-2. 预初始化
-
-请在宿主App的Application.onCreate函数中调用基础组件库初始化函数。
-```java
-// SDK预初始化函数不会采集设备信息，也不会向友盟后台上报数据。
-//  preInit预初始化函数耗时极少，不会影响App首次冷启动用户体验
-
-QtConfigure.preInit(this,"appkey","Channel");
-```
-
-
-## iOS 基座集成
+## iOS 基座配置
 ### 使用CocoaPods集成
 进入iOS工程目录
 ```shell
- cd ios && pod install && cd ..
-```
-### SDK初始化并集成appKey
-为保证您的App在集成统计SDK之后，能够满足工信部相关合规要求，您应确保App首次冷启动时，在用户阅读您的《隐私政策》并取得用户授权之后，才调用正式初始化函数初始化统计SDK，此时SDK才会真正采集设备信息并上报数据。反之，如果用户不同意《隐私政策》授权，则不能调用初始化函数
-```objectivec
-- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
-{
-  ...
-  /** 初始化所有组件产品
-     @param appKey 开发者在QT申请的appkey.
-     @param channel 渠道标识，可设置nil表示"App Store".
- */
-  [QTConfigure initWithAppkey:@"应用的appKey" channel:@"安装渠道"];
-  ...
-  return YES;
-}
-```
-一旦App获取到《隐私政策》的用户授权，后续的App冷启动，开发者应该保证调用到初始化函数。
-### 配置收数域名
-```objectivec
-#import <QTCommon/UMConfigure.h>
-
-- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
-{
-  ...
-  /** 设置上报统计日志的主域名和备用域名。此函数必须在SDK初始化函数调用之前调用。
-    @param primaryDomain 传日志的主域名收数地址,参数不能为null或者空串。例如：https://www.umeng.com
-    @param standbyDomain 上传日志备用域名收数地址,参数可以为null或者空串，若此参数为空，SDK内部会自动将主域名设置为备用域名。
-  */
-
-  [QTConfigure setCustomDomain:@"主收数域名" standbyDomain:@"备用收数域名"];
-  ...
-  return YES;
-}
-```
-### 按需引入日志组件
-引入统计所需组件库（在更新SDK时，您可以直接使用 pod update 命令进行直接更新）
-```objectivec
-pod 'UMCCommonLog'
+ cd ios && pod install 
 ```
-Podfile示例
-![image.png](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/281773/1668518339815-d4ccb536-a399-4341-ba2c-902dcf24b1da.png#clientId=uf686b11a-7b20-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=564&id=u6a3e4c24&margin=%5Bobject%20Object%5D&name=image.png&originHeight=571&originWidth=751&originalType=binary&ratio=1&rotation=0&showTitle=false&size=80695&status=done&style=none&taskId=ub00bc826-f430-4519-9921-c4040b208a7&title=&width=741.5)
-开启日志打印
-```objectivec
-#import <QTCommon/UMConfigure.h>
-#import <UMCommonLog/UMCommonLogHeaders.h>
 
-- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
-{
-  ...
-  [UMCommonLogManager setUpUMCommonLogManager];
-  [QTConfigure setLogEnabled:YES];
-  ...
-  return YES;
-}
-```
 ### 埋点验证配置
 添加您的 URL Scheme 到项目中，URL Scheme 位于项目设置 target -> 选项卡 Info - > URL Types。
-填入的scheme：atm.yourappkey。
-![image.png](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/281773/1668518096477-d9471acb-e7d0-4bba-8590-15891559b6b6.png#clientId=uf686b11a-7b20-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=412&id=ub7bbb0cc&margin=%5Bobject%20Object%5D&name=image.png&originHeight=823&originWidth=1366&originalType=binary&ratio=1&rotation=0&showTitle=false&size=127257&status=done&style=none&taskId=u9c88f1a5-85f6-4db1-a079-1dbef87724e&title=&width=683)
+填入的scheme：atm.yourappkey。<br>
+
+![image.png](https://intranetproxy.alipay.com/skylark/lark/0/2022/png/281773/1668518096477-d9471acb-e7d0-4bba-8590-15891559b6b6.png#clientId=uf686b11a-7b20-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=412&id=ub7bbb0cc&margin=%5Bobject%20Object%5D&name=image.png&originHeight=823&originWidth=1366&originalType=binary&ratio=1&rotation=0&showTitle=false&size=127257&status=done&style=none&taskId=u9c88f1a5-85f6-4db1-a079-1dbef87724e&title=&width=683)<br>
+
 在AppDelegate中调用函数[QTMobClick handleUrl:url]来接收 URL
+
 ```objectivec
 - (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
 {
@@ -218,8 +140,72 @@ Podfile示例
 
 ```
 # 埋点API
-## SDK初始化
-### 正式初始化
+## SDK初始化 
+注意初始化方法要放在App.tsx中，保证最先被执行到
+
+### 示例
+```typescript
+import * as QT from 'react-native-quicktracking-analytics-module';
+import { Platform } from 'react-native';
+
+// 初始化相关代码写在此处
+QT.setTrackDomain(
+  '收数域名',
+  '备用收数域名（可以传空）'
+);
+if (Platform.OS === 'android') {
+  QT.preInit('appkey', '应用商店名称');
+  QT.init('appkey', '应用商店名称');
+} else {
+  QT.init('appkey', 'App Store');
+}
+
+export default function App() {
+  return (
+    ...
+  );
+}
+
+```
+
+## 设置收数域名
+调用初始化SDK能力之前，需要调用 setTrackDomain 方法设置收数域名
+```typescript
+function setTrackDomain(mainTrackDomain: string, subTrackDomain: string): void;
+```
+
+| 参数 | 含义 |
+| --- | --- |
+| mainTrackDomain | 收数域名 |
+| chsubTrackDomainannel | 备用收数域 |
+
+### 示例
+```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
+QT.setTrackDomain(
+  '收数域名',
+  '备用收数域名（如果没有可以传空''）'
+);
+```
+
+## 预初始化
+仅Android端需要预初始化方法
+```typescript
+function preInit(appKey: string, channel: string): void;
+```
+| 参数 | 含义 |
+| --- | --- |
+| appKey | QT后台提供的唯一应用key值 |
+| channel | 下载渠道 |
+
+```typescript
+if (Platform.OS === 'android') {
+  QT.preInit('appkey', '应用商店名称');
+} 
+```
+
+## 正式初始化
 务必调用，请务必在用户同意隐私政策后，再初始化SDK。
 ```typescript
 function init(appKey: string, channel: string): void
@@ -231,8 +217,28 @@ function init(appKey: string, channel: string): void
 
 ### 示例
 ```tsx
-QT.init('appkey', 'quicktracking');
+import * as QT from "react-native-quicktracking-analytics-module";
+
+QT.init('appkey', '应用商店名称');
+```
+
+## 日志开关（按需开启， 上线的时候记得关闭）
+
+```typescript
+function enableLog(enable: boolean): void;
+```
+
+| 参数 | 含义 |
+| --- | --- |
+| enable | true打开 false关闭 |
+
+### 示例
+```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
+QT.enableLog(true);
 ```
+
 ## 用户账号上报
 ### 用户登录
 该值的上传对应产品中“登录用户”：计算“登录用户”数，就是计算下述API上传值的去重数
@@ -252,13 +258,15 @@ function profileSignIn(ID: string, provider?: string): void
 function profileSignOff(): void
 ```
 
-### 示例
+#### 示例
 ```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
 QT.profileSignIn('用户ID');
 QT.profileSignOff();
 ```
 
-## 用户属性上传
+### 用户属性上传
 使用事件编码固定为"$$_user_profile"的自定义事件上传，该事件所携带的事件属性会被作为用户属性放在用户表中。
 ```typescript
 function sendEvent(eventId: string, params: any): void
@@ -270,8 +278,10 @@ function sendEvent(eventId: string, params: any): void
 
 注：用户属性上传一定要在用户账号上报后。
 
-示例：
-```java
+#### 示例
+```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
 QT.onProfileSignIn("张三");
 
 const user = {
@@ -298,8 +308,10 @@ function registerGlobalProperty(globalProperty: any): void
 3. 在Android中，对于全局属性值为null或undefined的场景，底层Android sdk会过滤这个全局属性字段，如需要空值分析场景，需自定义默认空值
 4. 在iOS中，全局属性值不支持null和undefined，需要手动过滤。
 
-示例：
+#### 示例
 ```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
 QT.registerGlobalProperty({
     name: 'MyApp',
     description: 'this is a app',
@@ -318,41 +330,50 @@ function unregisterGlobalProperty(propertyName: string): void
 | --- | --- |
 | propertyName | 要删除的全局属性名 |
 
-示例：
+#### 示例
 ```typescript
- QT.unregisterGlobalProperty('name'); // 删除全局属性name
+import * as QT from "react-native-quicktracking-analytics-module";
+
+QT.unregisterGlobalProperty('name'); // 删除全局属性name
 ```
 
 ### 获取特定的全局属性
-```java
- async function getGlobalProperty(propertyName: string): Promise<any>
+```typescript
+const getGlobalProperty(propertyName: string): Promise<any>
 ```
 | 参数 | 含义 |
 | --- | --- |
 | propertyName | 要获取的全局属性名 |
 
-示例：
+#### 示例
 ```typescript
- await QT.getGlobalProperty('name'); // 获取全局属性name，返回 {name: "MyApp"}
+import * as QT from "react-native-quicktracking-analytics-module";
+
+const nameValue = await QT.getGlobalProperty('name');
+console.log('getGlobalProperty 调用成功', nameValue);
 ```
 
 ### 获取所有全局属性
 ```java
- async function getGlobalProperties(propertyName: string): Promise<any>
+const getGlobalProperties: () => Promise<any>;
 ```
 
-示例：
+#### 示例
 ```typescript
- await QT.getGlobalProperties(); // 获取所有全局属性
-```
+import * as QT from "react-native-quicktracking-analytics-module";
 
+const globalProperties = await QT.getGlobalProperties();
+console.log('getGlobalProperties 调用成功', globalProperties);
+```
 
 ### 清除所有全局属性
-```java
+```typescript
 function clearGlobalProperties(): void
 ```
-示例：
+#### 示例
 ```tsx
+import * as QT from "react-native-quicktracking-analytics-module";
+
 QT.clearGlobalProperties(); // 所有全局属性都被清除（慎用）
 ```
 
@@ -367,8 +388,10 @@ function onPageEnd(pageName: string): void
 | --- | --- |
 | pageName | 页面编码 |
 
-示例：
+### 示例
 ```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
 QT.onPageStart('MainPage');
 QT.onPageEnd('MainPage');
 ```
@@ -385,8 +408,10 @@ function uploadPageProperties(pageName: string, params: any): void
 | pageName | 页面编码 |
 | params | 对当前事件的参数描述，定义为“参数名:参数值”的“<键-值>”对 |
 
-示例：
+### 示例
 ```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
 QT.uploadPageProperties('detail_page', { test: 1 })
 ```
 注意：
@@ -397,13 +422,7 @@ QT.uploadPageProperties('detail_page', { test: 1 })
 自定义事件可以用于追踪用户行为，记录行为发生的具体细节。
 使用 **sendEvent **接口进行事件的统计，接口如下：
 ```typescript
-  /**
-   * 自定义事件埋点
-   * @param eventId 当前统计的事件编码
-   * @param params 对当前事件的参数描述，定义为“参数名:参数值”的“<键-值>”对
-   * @param pageName 当前统计事件的页面编码
-   */
-  function sendEvent(eventId: string, params?: any, pageName?: string): void
+function sendEvent(eventId: string, params?: any, pageName?: string): void
 ```
 | 参数 | 含义 |
 | --- | --- |
@@ -411,8 +430,10 @@ QT.uploadPageProperties('detail_page', { test: 1 })
 | params | 对当前事件的参数描述，定义为“参数名:参数值”的“<键-值>对”。为单层对象结构，不支持多层嵌套。 |
 | pageName | 当前统计事件的页面编码。 |
 
-**示例：**
+### 示例
 ```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
 // 携带事件参数的自定义事件
 QT.sendEvent(
   'event1',
@@ -433,10 +454,11 @@ QT.sendEvent(
 );
 ```
 > **_备注：_**
-> - 多参数类型事件能满足原来计算事件/计数事件的分析场景；
-> - 对于计算型事件不同的参数类型对应不同的计算方式，总共可以分为两大类，数值型和字符型
->    - 数字型：支持累加值、最大值、最小值、平均值和去重数计算
->    - 字符型：支持去重数计算
+> 
+> 多参数类型事件能满足原来计算事件/计数事件的分析场景；
+> 对于计算型事件不同的参数类型对应不同的计算方式，总共可以分为两大类，数值型和字符型
+> - 数字型：支持累加值、最大值、最小值、平均值和去重数计算
+> - 字符型：支持去重数计算
 
 注意：
 同全局属性，事件属性在Android和iOS不同平台上，也有着类型处理的差异：
@@ -448,19 +470,16 @@ QT.sendEvent(
 ## 桥接事件埋点
 桥接事件用于h5桥接RN的场景，使用此接口将H5日志发送至App中。
 ```typescript
-
-  /**
-   * 桥接事件埋点
-   * @param data H5转发事件的日志体
-   */
-  function sendEventForH5(data: string): void
+function sendEventForH5(data: string): void
 ```
 | 参数 | 含义 |
 | --- | --- |
 | data | H5转发事件的日志体 |
 
-**示例：**
+### 示例
 ```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
 const content = data.nativeEvent.data;
 QT.sendEventForH5(content);
 ```
@@ -529,6 +548,56 @@ export default function WebPage() {
 	);
 }
 ```
+
+# 其他
+## 关闭SDK
+```typescript
+const disableSDK: () => void;
+```
+### 示例
+
+```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
+QT.disableSDK();
+```
+## 开启SDK
+```typescript
+const enableSDK: () => void;
+```
+### 示例
+```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
+QT.enableSDK();
+```
+## 自定义设备ID
+```typescript
+const setCustomDeviceId: (deviceId: string) => void;
+```
+| 参数 | 含义 |
+| --- | --- |
+| deviceId | 设备ID |
+### 示例
+
+```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
+QT.setCustomDeviceId('deviceId');
+```
+## 读取设备ID
+```typescript
+const getDeviceId: () => Promise<any>;
+```
+### 示例
+```typescript
+import * as QT from "react-native-quicktracking-analytics-module";
+
+const deviceID = await QT.getDeviceId(); 
+console.log(‘getDeviceId 调用成功’, 
+  JSON.stringify(deviceID)); 
+```
+
 # FAQ
 ## ruby版本过低
 进入项目时提示，Required ruby-2.7.5 is not installed. To install do: 'rvm install "ruby-2.7.5"'
@@ -546,17 +615,8 @@ rvm use 2.7.5
 # 参考
 > [QuickTracking Android SDK集成手册](https://help.aliyun.com/document_detail/260238.html)
 > [QuickTracking iOS SDK集成手册](https://help.aliyun.com/document_detail/260233.html)
-> [React Native Android 本地模块](https://reactnative.dev/docs/native-modules-android)
-> [React Native iOS 本地模块](https://reactnative.dev/docs/native-modules-ios)
-
-
-
-
-
-
-
-
-
+> [React Native Android 本地模块](https://reactnative.dev/docs/0.78/legacy/native-modules-android)
+> [React Native iOS 本地模块](https://reactnative.dev/docs/0.78/legacy/native-modules-ios)
 
 ## License