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 ホストプロジェクト内の example/android/app/src/main/java/com/aliyun/qt_common_sdk_example/App.java をご参照ください。ご自身の Flutter プロジェクトの Android ホストプロジェクトに、io.flutter.app.FlutterApplication を拡張する同様の App クラスを追加します。onCreate メソッドで、appkey および channel パラメーターを指定して QtConfigure.preInit を呼び出します。
ご自身の Android ホストプロジェクトの AndroidManifest.xml ファイルにある application タグに、android:name 属性を追加します。その値を、以下に示すように新しい App クラスに設定します。
事前初期化のための appkey および channel パラメーターは、Dart コードで QTCommonSdk.initCommon に渡される androidAppkey (1 番目) および channel (3 番目) のパラメーターと一致させる必要があります。
プライバシーポリシーの要件に準拠するため、インストール後の最初のコールドスタート時にユーザーがプライバシーポリシーに同意した後にのみ、QTCommonSdk.initCommon を呼び出してください。
ユーザーが同意した後のコールドスタートでは、アプリの最初のページが初期化される際に QTCommonSdk.initCommon を直接呼び出します。
難読化の設定
flutter build apk は、デフォルトで R8 を有効にします。アプリケーションでコードの難読化を使用する場合、Quick Tracking 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 または同様の難読化ツールが R.java を削除する場合は、以下の設定を追加してください。
-keep public class [your.application.package.name].R$*{
public static final int *;
} プライバシーポリシーの遵守とプラグインの初期化
1. コンプライアンス声明
SDK サービスを使用していることをユーザーに通知する必要があります。プライバシーポリシーに以下の条項を追加してください：
「当社の製品は、分析サービスを提供するために、お客様のデバイス識別子 (IDFA, IDFV, OPENUDID, GUID など) を収集する必要がある SDK を統合しています。また、レポートデータの精度を補正し、基本的な不正行為対策機能を提供するために、地理的位置情報も使用します。」
2. コンプライアンスに準拠した初期化
SDK を初期化すると、分析データの収集が有効になります。関連規制を遵守するため、アプリの最初のコールドスタート時にユーザーがプライバシーポリシーを読み、同意した後にのみ QTCommonSdk.initCommon を呼び出してください。SDK は、初期化後にのみデバイス情報を収集し、データをレポートします。ユーザーが同意しない場合は、初期化関数を呼び出さないでください。
ユーザーの同意を得た後は、その後のアプリのコールドスタートごとに初期化関数を呼び出してください。
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 App Market');
} else if (Platform.isIOS) {
// iOS 固有のコード
QTCommonSdk.setCustomDomain(DOMAIN, DOMAIN);
QTCommonSdk.setLogEnabled(true);
QTCommonSdk.initCommon(APP_ANDROID_KEY, APP_IOS_KEY, 'App Store');
}
}
...プラグイン API
以下の API リファレンスにおいて、「Android のみ」または「iOS のみ」とマークされたメソッドは、そのプラットフォームにのみ適用されます。ラベルのないメソッドは、Android と iOS の両方に対応しています。
///
/// 分析ログをレポートするためのプライマリドメインとフォールバックドメインを設定します。
/// この関数は、SDK の初期化前に呼び出す必要があります。
///
/// @param primaryDomain プライマリドメイン。
/// @param standbyDomain フォールバックドメイン。null または空文字列の場合、
/// プライマリドメインが自動的にフォールバックドメインとして使用されます。
///
///
static void setCustomDomain(String primaryDomain, String standbyDomain)
///
/// SDK を初期化します。
///
/// @param androidAppkey Android アプリの appkey。
/// @param iosAppkey iOS アプリの appkey。
/// @param channel チャネル識別子。例：'App Store'、'Android App Market'。
///
///
static Future<dynamic> initCommon(
String androidAppkey, String iosAppkey, String channel)
///
/// カスタムのアプリバージョン番号を設定します。デフォルトは、プロジェクトの pubspec.yaml ファイルで指定されたバージョンです。
/// これは一度しか設定できません。他の SDK メソッドの前に呼び出すことを推奨します。
///
/// @param appVersion カスタムのバージョン番号文字列。
/// @param appVersionCode 対応する Android の `versionCode`。(Android のみ)
///
static void setAppVersion(String appVersion, int appVersionCode)
///
/// SDK がコンソールにログメッセージを出力するかどうかを制御します。
///
/// @param bFlag デフォルトは `false` (ログなし) です。`true` に設定するとデバッグログが有効になります。
/// リリースビルドでは `false` に設定する必要があります。
///
///
static void setLogEnabled(bool bFlag)
///
/// カスタムイベントを追跡します。
///
/// @param event イベント ID。
/// @param properties カスタムパラメーターのマップ。
///
static void onEvent(String event, Map<String, dynamic> properties)
///
/// 特定のページに関連付けられたカスタムイベントを追跡します。
///
/// @param event イベント ID。
/// @param pageName ページ名。
/// @param properties カスタムパラメーターのマップ。
///
static void onEventWithPage(
String event, String pageName, Map<String, dynamic> properties)
///
/// ユーザープロファイルのサインインを追跡します。
///
/// @param userID ユーザーの ID。
///
///
static void onProfileSignIn(String userID)
///
/// プロバイダーを使用してユーザープロファイルのサインインを追跡します。
///
/// @param userID ユーザーの ID。
/// @param provider 認証プロバイダー。
///
static void onProfileSignInEx(String userID, String provider)
///
/// ユーザープロファイルのサインオフを追跡します。
///
///
static void onProfileSignOff()
///
/// ページビューの追跡を開始します。
///
/// @param viewName ページ名。
///
///
static void onPageStart(String viewName)
///
/// ページビューの追跡を終了します。
///
/// @param viewName ページ名。
///
///
static void onPageEnd(String viewName)
///
/// すべてのイベントに含まれるグローバルプロパティを登録します。
///
/// @param properties 登録するカスタムパラメーターのマップ。
///
///
static void registerGlobalProperties(Map<String, dynamic> properties)
///
/// グローバルプロパティの登録を解除します。
///
/// @param propertyName 登録を解除するグローバルプロパティのキー。
///
///
static void unregisterGlobalProperty(String propertyName)
///
/// 登録されているすべてのグローバルプロパティを JSON 文字列として取得します。
///
///
static Future<String>? get getGlobalProperties async
///
/// 単一のグローバルプロパティの値を取得します。
///
///
static Future<dynamic>? getGlobalProperty(String propertyName) async
///
/// すべてのグローバルプロパティをクリアします。
///
static void clearGlobalProperties()
///
/// 特定のページのページビュー追跡をスキップします。
///
/// @param pageName スキップするページの名前。
///
///
static void skipMe(String pageName)
///
/// 特定のページのプロパティを設定します。
///
/// @param pageName ページ名。
/// @param properties ページのカスタムパラメーターのマップ。
///
static void setPageProperty(
String pageName, Map<String, dynamic> properties)
///
/// 現在の SPM (スーパーポジションモデル) を更新します。
///
/// @param curSPM 現在のページイベントの SPM。
///
static void updateCurSpm(String curSPM)
///
/// 次のページのビジネスパラメーターを更新します。
///
/// @param properties 次のページに渡すビジネスパラメーターのキーと値のマップ。
///
static void updateNextPageProperties(Map<String, dynamic> properties)
///
/// カスタムのデバイス ID を設定します。
///
/// @param customDeviceId カスタムのデバイス ID。
///
static void setCustomDeviceId(String customDeviceId)
///
/// デバイス ID を取得します。
///
///
static Future<dynamic>? getDeviceId() async
///
/// iOS 専用 API
/// システムメソッドのフッキングを有効または無効にします。
///
/// @param value ブール値。
///
///
static void isHook(bool value)
static void isHookUrl(bool value)
static void isHookEvent(bool value)
static void isHookPage(bool value)
///
/// iOS 専用 API
/// カスタムの OpenUDID を設定します。
///
/// @param customOpenUdid カスタムの OpenUDID。
///
///
static void setCustomOpenUdid(String customOpenUdid)
///
/// iOS 専用 API
/// カスタムの IDFA を設定します。
///
/// @param customIdfa カスタムの IDFA。
///
///
static void setCustomIdfa(String customIdfa)
///
/// iOS 専用 API
/// カスタムの IDFV を設定します。
///
/// @param customIdfv カスタムの IDFV。
///
///
static void setCustomIdfv(String customIdfv)
///
/// iOS 専用 API
/// カスタムの UTDI を設定します。
///
/// @param customUtdid カスタムの UTDI。
///
///
static void setCustomUtdid(String customUtdid)
///
/// iOS 専用 API
/// カスタムの MCC (モバイル国コード) を設定します。
///
/// @param customMcc カスタムの MCC。
///
///
static void setCustomMcc(String customMcc)
///
/// iOS 専用 API
/// カスタムの MNC (モバイルネットワークコード) を設定します。
///
/// @param customMnc カスタムの MNC。
///
///
static void setCustomMnc(String customMnc)
///
/// iOS 専用 API
/// カスタムのローカル IP アドレスを設定します。
///
/// @param customLocalIP カスタムのローカル IP。
///
///
static void setCustomLocalIP(String customLocalIP)
///
/// アプリケーションが自身のプロセスを強制終了して終了する場合、
/// 終了前にこのメソッドを呼び出してください。(Android のみ)
///
///
static void onKillProcess()
// QT JS SDK が flutter_webview_plugin の JavascriptChannel インターフェイスを介して JS レイヤーから Flutter レイヤーに分析データを送信する場合、このメソッドを呼び出す必要があります。
// 詳細な例については、example/lib/main.dart の 15～23 行目をご参照ください。
//
static void onJSCall(String msg)
static void setViewProperties(String keyName, dynamic value)
///
/// 自動イベント追跡用。
///
/// @param event イベントコード。
/// @param autoTrackProperties 自動追跡用のプリセットパラメーター。
/// @param customProperties カスタムパラメーター。
static void onAutoEvent(
String event,
Map<String, dynamic> autoTrackProperties,
Map<String, dynamic>? customProperties) QT JS SDK と flutter_webview_plugin のブリッジ
ご自身の Flutter プロジェクトがハイブリッド開発に flutter_webview_plugin (バージョン 0.4.0 以降) を使用しており、Quick Tracking JS SDK が H5 ページに統合されている場合、onJSCall インターフェイスを使用して、レポート用に JS SDK からネイティブの Android/iOS SDK に分析データを転送します。
example/lib/main.dart の 15～23 行目の実装をご参照ください。flutter_webview_plugin 用に 'QuickTrackingFlutterBridge' という名前の JS ブリッジチャネルを登録します。onMessageReceived: (JavascriptMessage message) コールバックで、QTCommonSdk.onJSCall(message.message); を呼び出します。
以下のコード例は example/lib/main.dart からのものです。
// 'QuickTrackingFlutterBridge' という名前の JS ブリッジチャネルコールバックオブジェクトを定義
final Set<JavascriptChannel> jsChannels = [
JavascriptChannel(
name: 'QuickTrackingFlutterBridge',
onMessageReceived: (JavascriptMessage message) {
// print(message.message);
QTCommonSdk.onJSCall(message.message);
}),
].toSet();
// Flutter WebView プラグインの起動時に JS ブリッジオブジェクトを登録
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)', // ユーザーが flutter のウェブサイトで twitter アイコンをクリックしたときに twitter へリダイレクトされるのを防ぐ
);注：他の機能が正しく動作するためには、QTCommonSdk.initCommon を呼び出してプラグインを初期化する必要があります。appkey は、アナリティクスコンソールの [Management] -> [App Management] -> [App List] で確認できます。または、[My Products] でアプリを選択し、[Settings] -> [App Information] に移動して確認することもできます。