全部產品
Search

搜尋本產品

    Quick Tracking：flutter SDK

    文件中心

    Quick Tracking：flutter SDK

    更新時間：Oct 22, 2025

    Quick Tracking 統計SDK Flutter外掛程式整合說明

    整合Flutter外掛程式

    環境準備

    qt_common_sdk: ^2.1.4

    ｜---依賴原生iOS 1.7.6 版本

    ｜---依賴原生 Android 1.8.5.PX 版本

    手動整合

    • 下載本工程git庫：flutter-ananlytics-plugin，刪除工程目錄下.git隱藏目錄。

    • 將本工程根目錄下android、ios、lib三個檔案夾和pubspec.yaml設定檔拷貝到您的flutter工程中。

    在您的flutter工程pubspec.yaml中加入外掛程式依賴

    #本地依賴

qt_common_sdk:
 path: ../

    線上依賴

    在工程pubspec.yaml中加入 dependencies

    # 線上依賴
dependencies:
  qt_common_sdk: ^2.1.4

    匯入

    import 'package:qt_common_sdk/qt_common_sdk.dart';

    基座配置

    Android端基座配置

    請參考本工程中樣本Android 宿主工程中App.java檔案(example/android/app/src/main/java/com/aliyun/qt_common_sdk_example/App.java)，給您的flutter工程Android宿主工程增加App類，注意此類必須是 io.flutter.app.FlutterApplication 類的子類。在App類的onCreate生命週期函數內，調用原生統計SDK的預初始化方法QtConfigure.preInit，並傳入appkey和渠道參數。

    image.png

    另外，您還需要在Android宿主工程AndroidManifest.xml資訊清單檔中 application 配置中添加 “android:name”屬性，其值為新增的 App 類。如下圖：

    image.png

    注意，預初始化傳入的appkey和渠道參數必須和後續在flutter工程的dart代碼中調用的SDK正式初始化函數QTCommonSdk.initCommon 傳入的第一個參數(Android appkey)和第三個參數(Android 渠道)必須嚴格一致。

    為了滿足《隱私政策》要求，開發人員必須保證在應用安裝後，首次冷啟動情境，只能在App使用者同意隱私授權之後，才能調用flutter外掛程式的QTCommonSdk.initCommon介面真正出初始化SDK。

    使用者已經同意隱私授權之後的後續應用冷啟動，可以在flutter首個頁面初始化時直接調用QTCommonSdk.initCommon介面初始化SDK。

    混淆配置

    Flutter Build APK預設會開啟R8如果您的應用使用了代碼混淆，請添加如下配置，以避免Quick Tracking SDK被錯誤混淆導致SDK不可用。

    -keep class com.quick.qt.** {*;}
-keep class rpk.quick.qt.** {*;}
-dontwarn com.quick.qt.analytics.middle.DevLog

-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 *;
}

    隱私政策合規以及Flutter外掛程式正式初始化

    1.合規聲明

    您務必告知使用者您選擇SDK服務，請在《隱私政策》中增加如下參考條款：

    “我們的產品整合SDK，SDK需要收集您的裝置識別碼（IDFA/IDFV/OPENUDID/GUID/）以提供統計分析服務，並通過地理位置校準報表資料準確性，提供基礎反作弊能力。”

    2.合規初始化

    為保證您的App在整合統計SDK之後，能夠滿足工信部相關合規要求，您應確保App首次冷啟動時，在使用者閱讀您的《隱私政策》並取得使用者授權之後，才能調用flutter外掛程式的QTCommonSdk.initCommon介面真正出初始化SDK，此時SDK才會真正採集裝置資訊並上報資料。反之，如果使用者不同意《隱私政策》授權，則不能調用初始化函數。

    一旦App擷取到《隱私政策》的使用者授權，後續的App冷啟動，開發人員應該保證調用到初始化函數。

    3. 初始化程式碼範例

    if (!sdkHasInit) {
      sdkHasInit = true;

      // 區分 iOS 和 Android 平台
      if (Platform.isAndroid) {
        // Android 平台特定代碼
        QTCommonSdk.setCustomDomain(DOMAIN, DOMAIN);
        QTCommonSdk.setLogEnabled(true);
        QTCommonSdk.initCommon(APP_ANDROID_KEY, APP_IOS_KEY, 'Android 應用市場');
      } else if (Platform.isIOS) {
        // iOS 平台特定代碼
        QTCommonSdk.setCustomDomain(DOMAIN, DOMAIN);
        QTCommonSdk.setLogEnabled(true);
        QTCommonSdk.initCommon(APP_ANDROID_KEY, APP_IOS_KEY, 'App Store');
      }
    }
    ...

    外掛程式介面說明

    如下各個介面注釋部分會針對介面或者參數標註 "Android特有" 或 "iOS特有"，請注意區分。 沒有特別標註的介面或者參數即為Android和iOS雙端通用。

     ///
 /// 設定上報統計日誌的主網域名稱和備用網域名稱。此函數必須在SDK初始化函數調用之前調用。
 ///
 /// @param primaryDomain String 主網域名稱.
 /// @param standbyDomain String 備用網域名稱 上傳日誌備用網域名稱收數地址,參數可以為null或者空串，若此參數為空白，SDK內部會自動將主網域名稱設定為備用網域名稱。
 ///
 ///
 static void setCustomDomain(String primaryDomain, String standbyDomain)

 ///
 /// 初始化
 ///
 /// @param androidAppkey String 開發人員申請的android appkey。android特有，Android端填寫
 /// @param iosAppkey String 開發人員申請的ios appkey。 ios特有，iOS端填寫
 /// @param channel String 渠道標識，可設定nil表示"App Store".
 ///
 ///
 static Future<dynamic> initCommon(String androidAppkey, String iosAppkey, String channel)

 ///
 /// 自訂app版本號碼，預設擷取version，只可設定一次建議在所有介面之前調用
 ///
 /// @param appVersion String 自訂版本號碼
 /// @param appVersionCode int 對應Android應用版本號碼versionCode，僅Android端會使用此參數，Android特有
 ///
 static void setAppVersion (String appVersion, int appVersionCode) 

 ///
 /// 設定是否在console輸出sdk的調試日誌
 ///
 /// @param bFlag bool 設定為flase(不輸出log); 設定為true, 輸出可供調試參考的log資訊，
 /// SDK內部預設此開關關閉，App正式上線前需將日誌開關關閉。
 ///
 ///
 static void setLogEnabled (bool bFlag)

 ///
 /// 自訂事件
 ///
 /// @param event String 事件Id.
 /// @param properties Map 自訂參數.
 ///
 static void onEvent(String event, Map<String,dynamic> properties)

 ///
 /// @param event String 事件Id.
 /// @param pageName String 頁面名稱.
 /// @param properties Map 自訂參數.
 ///
 static void onEventWithPage(String event,String pageName, Map<String,dynamic> properties)

 ///
 /// 帳號統計登入
 ///
 /// @param userID String user's ID
 ///
 ///
 static void onProfileSignIn(String userID)

 ///
 /// 帳號統計登出
 ///
 ///
 static void onProfileSignOff ()

 ///
 /// 頁面統計: 頁面開始顯示時調用
 ///
 /// @param viewName String 頁面名稱
 ///
 ///
 static void onPageStart(String viewName)

 ///
 /// 頁面統計：頁面消失時調用
 ///
 /// @param viewName String 頁面名稱
 ///
 ///
 static void onPageEnd(String viewName)

 ///
 /// 設定頁面屬性.
 ///
 /// @param pageName String 頁面名稱
 /// @param properties Map 自訂參數
 ///
 static void setPageProperty(String pageName, Map<String,dynamic> properties)

 ///
 /// 註冊全域屬性
 ///
 /// @param properties Map 自訂參數
 ///
 ///
 static void registerGlobalProperties(Map<String,dynamic> properties)

 ///
 /// 刪除一個全域屬性
 ///
 /// @param propertyName String 自訂參數key
 ///
 ///
 static void unregisterGlobalProperty(String propertyName)

 ///
 /// 擷取全域屬性
 ///
 ///
 static Future<String>? get getGlobalProperties async

 ///
 /// 擷取一個全域屬性值
 ///
 ///
 static Future<dynamic>? getGlobalProperty(String propertyName) async

 ///
 /// 清除全域屬性
 ///
 static void clearGlobalProperties() 

 ///
 /// 跳過當前頁面統計.
 ///
 /// @param pageName String 頁面名稱
 ///
 ///
 static void skipMe(String pageName) 
 
 ///
 /// 設定頁面屬性.
 ///
 /// @param pageName String 頁面名稱
 /// @param properties Map 自訂參數
 ///
 static void setPageProperty(String pageName, Map<String,dynamic> properties)
 
 //
 // QT JS SDK通過flutter_webview_plugin外掛程式將JS層統計資料發送到flutter層JavascriptChannel介面
 // 時需調用此介面，具體範例程式碼見example/lib/main.dart 第15行~第23行 寫法。
 //
 static void onJSCall(String msg)
 
 ///
 /// 應用如果以強殺死自身進程方式暴力退出，
 /// 則需要在自殺前調用此介面，此介面為Android端特有
 ///
 ///
 static void onKillProcess()

    flutter_webview_plugin外掛程式配合QT JS SDK橋接使用說明

    在flutter工程使用社區flutter_webview_plugin(支援版本0.4.0+) + H5做混合開發時，如果在H5頁面中整合了QuickTracking JS版本統計SDK，則通過使用onJSCall介面API，支援將QT JS SDK的統計資料透傳至 Android/iOS原生統計SDK，由原生統計SDK上報JS SDK統計資料。

    開發人員需要參考樣本工程example/lib/main.dart 第15行~第23行 寫法。給flutter_webview_plugin外掛程式註冊一個名為'Umeng4AplusFlutter'的JS bridge通過，然後在onMessageReceived: (JavascriptMessage message)回呼函數中調用QTCommonSdk.onJSCall(message.message);

    如下範例程式碼可以在example/lib/main.dart檔案中找到。

    // 定義一個名為'Umeng4AplusFlutter'的JS bridge通道回調對象
final Set<JavascriptChannel> jsChannels = [
   JavascriptChannel(
       name: 'Umeng4AplusFlutter',
       onMessageReceived: (JavascriptMessage message) {
         // print(message.message);
         QTCommonSdk.onJSCall(message.message);
       }),
].toSet();

//..........

// 開啟flutter webview 外掛程式對象時將js bridge對象註冊上
flutterWebViewPlugin.launch(
                   selectedUrl,
                   javascriptChannels: jsChannels,
                   rect: Rect.fromLTWH(
                        0.0, 0.0, MediaQuery.of(context).size.width, 300.0),
                   userAgent: kAndroidUserAgent,
                   invalidUrlRegex:
                        r'^(https).+(twitter)', // prevent redirecting to twitter when user click on its icon in flutter website
								 );

    注意: 需要先調用 QTConfigure.init 來初始化外掛程式（Appkey可在統計後台 “管理->應用管理->應用列表” 頁面查看，或在 “我的產品”選擇某應用->設定->應用資訊 查看Appkey），才能保證其他功能正常工作。