React Native SDK

SDK基本信息

集成说明

Quick Tracking React Native SDK是基于Quick Tracking原生客户端埋点SDK上的扩展，封装了QT埋点常用的api，如全局属性、页面属性、自定义事件等，需要分别在RN、Android、iOS三端做集成以及配置。

React Native SDK集成

npm线上地址：react-native-quicktracking-analytics-module

下载npm包到项目中

# npm
npm install react-native-quicktracking-analytics-module

# yarn
yarn add react-native-quicktracking-analytics-module

# pnpm
pnpm add react-native-quicktracking-analytics-module

引入SDK环境变量

import * as QT from "react-native-quicktracking-analytics-module";

AppKey和收数域名获取

进入控制台

进入QT后台，点击“管理控制台”

集成应用

找到需要集成埋点的应用：进入“应用列表”，选择所需组织，点击操作中的“详情或者去集成”

Android 基座配置

Maven地址配置

在工程 build.gradle 配置脚本中 buildscript 和 allprojects 段中添加 sdk maven 仓库地址

buildscript {
    repositories {
    google()
    jcenter()
    maven { url 'https://repo1.maven.org/maven2/' }
  }
  dependencies {
      classpath 'com.android.tools.build:gradle:3.4.0'}
      // NOTE: Do not place your application dependencies here; they belong
      // in the individual module build.gradle files
  }
}
allprojects {
    repositories {
    google()
    jcenter()
    maven { url 'https://repo1.maven.org/maven2/' }
  }
}

组件引用

在工程app对应build.gradle配置脚本dependencies段中，添加集成所需要的依赖

dependencies {
    implementation fileTree(include:['*.jar'], dir:'libs')

    //QuickTracking统计分析SDK
    implementation 'com.lydaas.qtsdk:qt-px-common:1.8.5.PX'
}

请注意：如果已经通过package.json 添加了 QuickTracking ReactNative SDK 的依赖,则不需要再单独集成QuickTracking Android原生SDK

埋点验证配置

在Android.manifest中，找到MainActivity对应的activity标签，并将以下代码粘贴进去，appkey换成自己的

//1.唤起码默认为"atm.该app对应的appkey"，不可改变
//2.请使用单独intent-filter,和其他intent-filter并列
//不要将以下代码填入其他intent-filter里；

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="atm.appkey" />
</intent-filter>

配置权限

统计SDK需要宿主APP授予如下权限：

下面给出AndroidManifest.xml清单文件示例：

<manifest ……> 
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <application ……>
</manifest>

混淆配置

如果您的应用使用了代码混淆，请添加如下配置，以避免Quick Tracking SDK被错误混淆导致SDK不可用。

-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);
}
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

SDK需要引用导入工程的资源文件，通过了反射机制得到资源引用文件R.java，但是在开发者通过proguard等混淆优化工具处理apk时，proguard可能会将R.java删除，如果遇到这个问题，请添加如下配置：

-keep public class [您的应用包名].R$*{
    public stac final int 

iOS 基座配置

使用CocoaPods集成

进入iOS工程目录

cd ios && pod install   

埋点验证配置

添加您的 URL Scheme 到项目中，URL Scheme 位于项目设置 target -> 选项卡 Info - > URL Types。

填入的scheme：atm.yourappkey。

在AppDelegate中调用函数[QTMobClick handleUrl:url]来接收 URL

- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    if ([QTMobClick handleUrl:url]) {
        return YES;
    }
    return YES;
}

埋点验证操作请参考文档：埋点验证详细指南

埋点API

SDK初始化

注意初始化方法要放在App.tsx中，保证最先被执行到

示例

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 方法设置收数域名

function setTrackDomain(mainTrackDomain: string, subTrackDomain: string): void;

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.setTrackDomain(
  '收数域名',
  '备用收数域名（如果没有可以传空''）'
);

预初始化

仅Android端需要预初始化方法

function preInit(appKey: string, channel: string): void;

示例

import * as QT from "react-native-quicktracking-analytics-module";

if (Platform.OS === 'android') {
  QT.preInit('appkey', '应用商店名称');
} 

正式初始化

务必调用，请务必在用户同意隐私政策后，再初始化SDK。

function init(appKey: string, channel: string): void

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.init('appkey', 'quicktracking');

日志开关（按需开启， 上线的时候记得关闭）

function enableLog(enable: boolean): void;

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.enableLog(true);

用户账号上报

用户登录

该值的上传对应产品中“登录用户”：计算“登录用户”数，就是计算下述API上传值的去重数

function profileSignIn(ID: string, provider?: string): void

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.profileSignIn('用户ID');

用户登出

账号登出时需调用此接口，调用之后不再发送账号相关内容。

function profileSignOff(): void

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.profileSignOff();

用户属性上传

使用事件编码固定为"$$_user_profile"的自定义事件上传，该事件所携带的事件属性会被作为用户属性放在用户表中。

function sendEvent(eventId: string, params: any): void

请注意：用户属性上传一定要在用户账号上报后。

示例：

import * as QT from "react-native-quicktracking-analytics-module";

QT.onProfileSignIn("张三");

const user = {
  gender: "male",
  age: "8"
}
QT.sendEvent("$$_user_profile", user);

上述上传的业务含义为：张三 男 8岁

全局属性

全局属性为每一个事件都会携带的属性

注册全局属性

function registerGlobalProperty(globalProperty: any): void

注意：

1. 属性名、string类型的属性值，只支持大小写字母、数字及下划线。

2. 在Android中，属性值不支持JavaScript的boolean类型，需要手动在JS中转为0、1。

3. 在Android中，对于全局属性值为null或undefined的场景，底层Android sdk会过滤这个全局属性字段，如需要空值分析场景，需自定义默认空值

4. 在iOS中，全局属性值不支持null和undefined，需要手动过滤。

示例：

import * as QT from "react-native-quicktracking-analytics-module";

QT.registerGlobalProperty({
    name: 'MyApp',
    description: 'this is a app',
    aBoolean: 1, //boolean类型需传为0或1,
    aNull: '', //null或undefined类型需传空字符串
    //默认为number类型，对于返回值为null或undefined场景，需业务自定义数值型默认空值
    aNumber: 66, 
});

删除特定的全局属性

function unregisterGlobalProperty(propertyName: string): void

示例：

import * as QT from "react-native-quicktracking-analytics-module";

QT.unregisterGlobalProperty('name'); // 删除全局属性name

获取特定的全局属性

async function getGlobalProperty(propertyName: string): Promise<any>

示例：

import * as QT from "react-native-quicktracking-analytics-module";

const nameValue = await QT.getGlobalProperty('name');
console.log('getGlobalProperty 调用成功', nameValue);

获取所有全局属性

async function getGlobalProperties(propertyName: string): Promise<any>

示例：

import * as QT from "react-native-quicktracking-analytics-module";

const globalProperties = await QT.getGlobalProperties();
console.log('getGlobalProperties 调用成功', globalProperties);

清除所有全局属性

function clearGlobalProperties(): void

示例：

import * as QT from "react-native-quicktracking-analytics-module";

QT.clearGlobalProperties(); // 所有全局属性都被清除（慎用）

页面浏览事件埋点

开发者如果希望对页面路径和页面停留时长进行采集和统计。可以通过调用该接口手动埋点

function onPageStart(pageName: string): void
function onPageEnd(pageName: string): void

示例：

import * as QT from "react-native-quicktracking-analytics-module";

QT.onPageStart('MainPage');
QT.onPageEnd('MainPage');

请注意：

onPageStart 是SDK记录页面进入的信息，onPageStart不会上报事件，只有调用onPageEnd的时候才会上报页面浏览事件。

onPageStart和onPageEnd必须成对调用，且传值的pageName需要保持一致，如果没有onPageEnd或者onPageEnd与onPageStart传值的pageName不一致，则onPageStart记录的信息不会生效。

页面属性上传

支持给当前页面附加自定义属性

function uploadPageProperties(pageName: string, params: EventParams): void

参数：

示例：

import * as QT from "react-native-quicktracking-analytics-module";

QT.uploadPageProperties('detail_page', { test: 1 })

请注意：

1. 该接口必须在onPageStart和onPageEnd之间调用。

2. 属性名、string类型的属性值，只支持大小写字母、数字及下划线。

3. 在Android中，属性值不支持JavaScript的boolean类型，需要手动在JS中转为0、1。

4. 在Android中，对于全局属性值为null或undefined的场景，底层Android sdk会过滤这个全局属性字段，如需要空值分析场景，需自定义默认空值

5. 在iOS中，全局属性值不支持null和undefined，需要手动过滤。

自定义事件埋点

自定义事件可以用于追踪用户行为，记录行为发生的具体细节。

使用 sendEvent 接口进行事件的统计，接口如下：

function sendEvent(eventId: string, params?: any, pageName?: string): void

示例：

import * as QT from "react-native-quicktracking-analytics-module";

// 携带事件参数的自定义事件
QT.sendEvent(
  'event1',
  {
    name: 'quick tracking',
    method: 'func',
  },
);

// 携带事件参数和页面编码的自定义事件
QT.sendEvent(
  'event2',
  {
    name: 'quick tracking',
    method: 'func',
  },
  'main-page'
);

备注：

• 多参数类型事件能满足原来计算事件/计数事件的分析场景；

• 对于计算型事件不同的参数类型对应不同的计算方式，总共可以分为两大类，数值型和字符型

  • 数字型：支持累加值、最大值、最小值、平均值和去重数计算

  • 字符型：支持去重数计算

请注意：

同全局属性，事件属性在Android和iOS不同平台上，也有着类型处理的差异：

1. 在Android中，不支持JavaScript的boolean类型，需要手动在JS中转为0、1。

2. 在Android中，对于全局属性值为null或undefined的场景，底层Android sdk会过滤这个全局属性字段，如需要空值分析场景，需自定义默认空值

3. 在iOS中，全局属性值不支持null和undefined，需要手动过滤。

桥接事件埋点

桥接事件用于h5桥接RN的场景，使用此接口将H5日志发送至App中。

function sendEventForH5(data: string): void

示例：

import * as QT from "react-native-quicktracking-analytics-module";

const content = data.nativeEvent.data;
QT.sendEventForH5(content);

RN App中嵌入h5页面（RN桥接模式）

H5集成 QuickTracking Web SDK

该步骤请参考：Web SDK

转发H5端发送的日志给React Native WebView

<script charset="UTF-8">
  ...
  // sdk接入及配置部分
  ...
  
  //转发页面自定义事件（点击、元素曝光、其他）
  aplus_queue.push({
    action: 'aplus.aplus_pubsub.subscribe',
    arguments: ['mw_change_hjlj', function (content) {
      var eventData = content && content.what_to_send && content.what_to_send.hjljdataToUmNative;
      if (/*iOS环境*/) {
        window.ReactNativeWebView.postMessage(JSON.stringify(eventData), '*'); 
      } else {
        window.ReactNativeWebView.postMessage(JSON.stringify(eventData));
      }
    }]
  })
  
  aplus_queue.push({
    action: 'aplus.aplus_pubsub.subscribe',
    arguments: ['mw_change_pv', function (content) {
      var pvData = content && content.what_to_send && content.what_to_send.pvdataToUmNative;
      if (/*iOS环境*/) {
        window.ReactNativeWebView.postMessage(JSON.stringify(pvData), '*');    
      } else {
        window.ReactNativeWebView.postMessage(JSON.stringify(pvData));
      }
    }]
  })
</script>

React Native WebView接收消息并调用QT SDK上报日志

import * as React from 'react'
import { WebView } from 'react-native-webview';
import { QT } from 'react-native-quicktracking-analytics-module';
import { Platform, SafeAreaView } from 'react-native';

export default function WebPage() {
  const onMessage = (data) => {
    try {
      const content = data.nativeEvent.data;
      QT.sendEventForH5(content);
    } catch (error) {
      console.log('webview message error:', error);
    }
  };
  
  return (
    <SafeAreaView style={{ flex: 1 }}>
    	<WebView
      	...
        onMessage={onMessage}
      	...
      />
    </SafeAreaView>
  );
}

其他

关闭SDK

const disableSDK: () => void;

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.disableSDK();

开启SDK

const enableSDK: () => void;

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.enableSDK();

自定义设备ID

const setCustomDeviceId: (deviceId: string) => void;

示例

import * as QT from "react-native-quicktracking-analytics-module";

QT.setCustomDeviceId('deviceId');

读取设备ID

const getDeviceId: () => Promise<any>;

示例

import * as QT from "react-native-quicktracking-analytics-module";

const deviceID = await QT.getDeviceId(); 
console.log(‘getDeviceId 调用成功’, JSON.stringify(deviceID)); 

RN 全埋点

需要 QuickTracking ReactNative SDK 2.0.0版本及以上支持

页面浏览事件自动采集

考虑到React Navigation库自身丰富的场景支持以及在社区的影响力，在SDK的页面浏览事件自动采集能力上直接借助了React Navigation开放的接口能力，示例如下：

import {QT} from 'react-native-quicktracking-analytics-module';
import {
  NavigationContainer,
  useNavigationContainerRef,
} from '@react-navigation/native';
import {createNativeStackNavigator} from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

const App = () => {
  const navigationRef = useNavigationContainerRef();
  const routeNameRef = useRef('');

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        routeNameRef.current = currentRouteName;
        // 设置页面编码
        QT.onPageStart(currentRouteName);
      }}
      onStateChange={() => {
        const previousRouteName = routeNameRef.current;
        const currentRouteName = navigationRef.getCurrentRoute()?.name;
        // 按需设置页面属性（可选）
        QT.uploadPageProperties(previousRouteName, {
          test_page_p_1: 1,
          test_page_p_2: "test"
        });
        // 采集页面浏览事件
        QT.onPageEnd(previousRouteName);
        if (currentRouteName) {
          if (previousRouteName !== currentRouteName) {
            // 更新新的页面编码
            QT.onPageStart(currentRouteName);
            routeNameRef.current = currentRouteName;
          }
        }
      }}
    >
      ...
    </NavigationContainer>
  )
}

控件点击事件自动采集

在待埋点项目路径下执行node命令

node node_modules/react-native-quicktracking-analytics-module/src/hook.js -run

注：如果需要恢复原始文件，可以执行 reset 命令

node node_modules/react-native-quicktracking-analytics-module/src/hook.js -reset

忽略RN控件全埋点采集

由于存在混合开发的场景，支持单独关闭React Native控件点击事件的自动采集，在待埋点项目的package.json中增加QTSDKConfig配置：

{
  "name": "reactnative_demo",
  "QTSDKConfig": {
    "enableAutoCLK": true
  }
}

enableAutoCLK字段取值含义：

• true 开启RN控件自动采集

• false 关闭RN控件自动采集

注：开启RN控件点击事件自动采集功能需要配合上述 node 命令使用

开启iOS控件点击事件自动采集

#import <QTCommon/UMConfigure.h>
#import <QTCommon/MobClick.h>
#import <UMCommonLog/UMCommonLogHeaders.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    // 全埋点原生控件点击自动采集功能开启
    [QTMobClick setAutoEventEnabled:YES];
    
    return YES;
}

开启Android控件点击事件自动采集

import com.quick.qt.analytics.QtTrackAgent;

public class MainApplication extends Application implements ReactApplication {
  ...
    
  @Override
  public void onCreate() {
    super.onCreate();
    ...
    // 全埋点原生控件点击自动采集功能开启
    QtTrackAgent.setAutoEventEnabled(true);
    ...
  }

  ...
}

设置ReactNative控件自定义属性

注：仅支持React Native控件，如TouchableHighlight、TouchableOpacity、Pressable等等

<Pressable
  onPress={()=>{}}
  qtParams={{
    pressable: "press_1",
  }}
>
  {({pressed}) => (
    <Text style={styles.text}>
      {pressed ? '点下了Pressable控件!' : 'Pressable 控件'}
    </Text>
  )}
</Pressable>

<TouchableHighlight 
  onPress={()=>{}} 
  qtParams={{aTouchableHighlight: 1, b: 2}}>
  <Text>TouchableHighlight 控件</Text>
</TouchableHighlight>

<TouchableOpacity 
  onPress={()=>{}} 
  qtParams={{aTouchableOpacity: 1, b: 2}}>
  <Text>TouchableOpacity 控件</Text>
</TouchableOpacity>

<TouchableWithoutFeedback 
  onPress={()=>{}} 
  qtParams={{aTouchableWithoutFeedback: 1, b: 2}}>
  <Text>TouchableWithoutFeedback 控件</Text>
</TouchableWithoutFeedback>

忽略单个控件的自动采集

在事件属性中增加 ignore字段等于true

<TouchableHighlight 
  onPress={()=>{}} 
  qtParams={{
    aTouchableHighlight: 1, 
    b: 2,
    ignore: true
  }}>
  <Text>TouchableHighlight 控件</Text>
</TouchableHighlight>

嵌入的html可以收发数，但Android端不能

查看Android Manifest里有没有配置网络权限。

参考

QuickTracking Android SDK集成手册

QuickTracking iOS SDK集成手册

React Native Android 本地模块

React Native iOS 本地模块

License

MIT

Made with create-react-native-library