react-native-quicktracking-analytics-module

集成说明

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

React Native SDK集成

下载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 { QT } from "react-native-quicktracking-analytics-module";

Android 基座集成

进入控制台

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

集成应用

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

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')

  implementation "com.umeng.umsdk:qt-px-common:1.4.0.PX"
}

埋点验证配置

在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授予如下权限：

权限	用途
ACCESS_NETWORK_STATE	检测联网方式，在网络异常状态下避免数据发送，节省流量和电量。
READ_PHONE_STATE（可选）	获取用户设备的IMEI，通过IMEI对用户进行唯一标识，以便提供统计分析服务。
ACCESS_WIFI_STATE	获取WIFI mac地址，在平板设备或电视盒子上，无法通过IMEI标识设备，我们会将WIFI mac地址作为用户的唯一标识，以便正常提供统计分析服务。
INTERNET	允许应用程序联网和发送统计数据的权限，以便提供统计分析服务。

下面给出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 ……>

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

-keep class com.umeng.** {*;}
-keep class org.repackage.** {*;}

-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 static final int *;
}

初始化SDK

1. 域名设置

务必在初始化之前设置私有化环境收数域名。

/**
* 设置上传统计日志的主域名和备用域名。SDK会优先将统计数据上报到主域名，失败的情况下会再尝试将数据上报到备用域名。
* 主域名primaryDomain或不能传入null或者空串，否则会抛出SdkDomainUndefined运行时异常。
*/

QtConfigure.setCustomDomain("收数域名", null);

2. 预初始化

请在宿主App的Application.onCreate函数中调用基础组件库初始化函数。

// SDK预初始化函数不会采集设备信息，也不会向友盟后台上报数据。
//  preInit预初始化函数耗时极少，不会影响App首次冷启动用户体验

QtConfigure.preInit(this,"appkey","Channel");

iOS 基座集成

使用CocoaPods集成

进入iOS工程目录

 cd ios && pod install && cd ..

SDK初始化并集成appKey

为保证您的App在集成统计SDK之后，能够满足工信部相关合规要求，您应确保App首次冷启动时，在用户阅读您的《隐私政策》并取得用户授权之后，才调用正式初始化函数初始化统计SDK，此时SDK才会真正采集设备信息并上报数据。反之，如果用户不同意《隐私政策》授权，则不能调用初始化函数

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  ...
  /** 初始化所有组件产品
     @param appKey 开发者在QT申请的appkey.
     @param channel 渠道标识，可设置nil表示"App Store".
 */
  [QTConfigure initWithAppkey:@"应用的appKey" channel:@"安装渠道"];
  ...
  return YES;
}

一旦App获取到《隐私政策》的用户授权，后续的App冷启动，开发者应该保证调用到初始化函数。

配置收数域名

#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 命令进行直接更新）

pod 'UMCCommonLog'

Podfile示例 开启日志打印

#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。 在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初始化

正式初始化

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

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

参数	含义
appKey	QT后台提供的唯一应用key值
channel	下载渠道

示例

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

用户账号上报

用户登录

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

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

参数	含义
ID	用户账号，长度小于64字节。
该值的上传对应产品中“登录用户”：计算“登录用户”数，就是计算该用户账号的去重数
provider

用户登出

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

function profileSignOff(): void

示例

QT.profileSignIn('用户ID');
QT.profileSignOff();

用户属性上传

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

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

参数	含义
eventId	当前统计的事件编码
params	对当前事件的参数描述，定义为“参数名:参数值”的“<键-值>”对

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

示例：

QT.onProfileSignIn("张三");

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

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

全局属性

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

注册全局属性

function registerGlobalProperty(globalProperty: any): void

参数	含义
globalProperty	要注册的全局属性，定义为“属性名:属性值”的“<键-值>”对。为单层对象结构，不支持多层嵌套。

注意：

1. 属性名、string类型的属性值，只支持大小写字母、数字及下划线。
2. 在Android中，属性值不支持JavaScript的boolean类型，需要手动在JS中转为0、1。
3. 在Android中，对于全局属性值为null或undefined的场景，底层Android sdk会过滤这个全局属性字段，如需要空值分析场景，需自定义默认空值
4. 在iOS中，全局属性值不支持null和undefined，需要手动过滤。

示例：

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

参数	含义
propertyName	要删除的全局属性名

示例：

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

获取特定的全局属性

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

参数	含义
propertyName	要获取的全局属性名

示例：

 await QT.getGlobalProperty('name'); // 获取全局属性name，返回 {name: "MyApp"}

获取所有全局属性

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

示例：

 await QT.getGlobalProperties(); // 获取所有全局属性

清除所有全局属性

function clearGlobalProperties(): void

示例：

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

页面浏览事件埋点

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

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

参数	含义
pageName	页面编码

示例：

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

注意： onPageStart 和 onPageEnd 必须成对调用。

页面属性上传

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

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

参数	含义
pageName	页面编码
params	对当前事件的参数描述，定义为“参数名:参数值”的“<键-值>”对

示例：

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

注意： 该接口必须在onPageStart和onPageEnd之间调用

自定义事件埋点

自定义事件可以用于追踪用户行为，记录行为发生的具体细节。 使用 **sendEvent **接口进行事件的统计，接口如下：

  /**
   * 自定义事件埋点
   * @param eventId 当前统计的事件编码
   * @param params 对当前事件的参数描述，定义为“参数名:参数值”的“<键-值>”对
   * @param pageName 当前统计事件的页面编码
   */
  function sendEvent(eventId: string, params?: any, pageName?: string): void

参数	含义
eventId	为当前统计的事件编码。
params	对当前事件的参数描述，定义为“参数名:参数值”的“<键-值>对”。为单层对象结构，不支持多层嵌套。
pageName	当前统计事件的页面编码。

示例：

// 携带事件参数的自定义事件
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中。

  /**
   * 桥接事件埋点
   * @param data H5转发事件的日志体
   */
  function sendEventForH5(data: string): void

参数	含义
data	H5转发事件的日志体

示例：

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

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

H5集成 QuickTracking Web SDK

该步骤请参考QuickTrackingWeb 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>
	);
}

FAQ

ruby版本过低

进入项目时提示，Required ruby-2.7.5 is not installed. To install do: 'rvm install "ruby-2.7.5"' 注意您的ruby版本，MacOS自带的Ruby为2.6.8，不符合RN项目需求。 建议在本地终端中执行 ruby --version 下载ruby包管理器，如rbenv或rvm等，改成ruby版本为RN需要的版本

rvm install 2.7.5
rvm use 2.7.5

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

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

参考

QuickTracking Android SDK集成手册 QuickTracking iOS SDK集成手册 React Native Android 本地模块 React Native iOS 本地模块

License

MIT

---

Made with create-react-native-library