Quick Tracking：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.6.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.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;

樣本

需要在Android原生Application中進行preinit初始化,防止事件漏報等異常

class MainApplication : Application(), ReactApplication {

  private var appKey = "您的appkey"
  private var domain = "您的收數網域名稱"
  override fun onCreate() {
    super.onCreate()
    QtConfigure.setCustomDomain(domain, domain)//設定收數網域名稱
    // QtConfigure.setLogEnabled(true)// 開啟日誌
    QtConfigure.preInit(
      this,
      appKey,
      "您的渠道名稱"
    )
   // loadReactNative(this)
  }
}

正式初始化

務必調用，請務必在使用者同意隱私政策後，再初始化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類型需傳Null 字元串
    //預設為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