ここまで、Qt Insightでのデータ確認方法やそれを利用した実践的なユーザー行動分析の方法についてご説明しました。

本稿では、いよいよQtアプリケーションにQt Insight Tracker APIを追加して、クラウドにデータを送信し、Qt Insight Web Console（ブラウザで表示されるページ）で送信されたデータを確認する方法についてご紹介します。

目次

1. Qtのインストール
2. Qt Creatorでプロジェクトを開く
3. Qt Insightサンプルプロジェクト
   1. CMakeLists.txt
   2. qtinsight.conf
   3. QMLファイルでのTracker APIの使用
   4. ユーザー操作イベントの送信
   5. アプリケーションを使ってみる
   6. オフラインデバイスでQt Insightを使用する
4. Automotive HVACデモ + Qt Insight
5. まとめ

Qtのインストール

Qt Insight Trackerは、Qtフレームワークで実装されるアプリケーションを前提としています。

そのため、まずはQtをインストールする必要があります。

「Qt　インストール」と検索エンジンで調べて、インストールのページに進みましょう。

「ダウンロード」とあるリンクを開くと、以下のページが開きます。

よく見ると、Qtには２つの選択肢があることがわかります。「無料評価ライセンス（商用ライセンス）」と「オープンソース版」です。

Qt Insightは、商用ライセンスであってもオープンソース版であっても使用可能なので、それぞれの説明を読んだうえで、自分に合った方を選択して先に進んでください。

無料評価ライセンスをリクエストを選択した場合

「無料評価ライセンスをリクエスト」を選択した場合、以下のような画面が表示されます。

こちらに情報を入力すると、最終的にはqtaccount@qt.ioから以下のようなメールが届きます。以下で赤くハイライトされている「downloads via the Qt Account portal」をクリックしましょう。

すると「Qt Customer Portal」が表示されます。左側のメニューから「Downloads」を選択しすると、中央に「Online Installer」という画面が表示されるので、中央にある３つの「Unified Qt Installer」から、ご自身のPCのOSにあったインストーラをダウンロードしてください。私はWindowsを使っているので、一番右の「Unified Qt Installer 4.6.1. for Windows」をダウンロードします。

すると「qt-unified-windows-x64-4.6.1-online.exe」がダウンロードされます。

オープンソース版をダウンロードを選択した場合

「オープンソース版をダウンロード」を選択した場合、以下のような画面が表示され、使用しているOSに合ったUnifiedインストーラが自動的にダウンロードされます。もしされない場合は、以下の画像で赤くハイライトされている「here」をクリックしてください。

必要なモジュールのインストール

Unifiedインストーラがダウンロードできたところで、早速実行していきましょう。

インストーラを起動すると、以下のような画面が表示されます。

Qtのインストールには、Qtアカウントにログインする必要があります。アカウントに登録済みの場合は、Eメールとパスワードを入力したうえで右下の「次へ」をクリックして次に進んでください。

もしQtアカウントに心当たりがない場合は、「Qtアカウントをお持ちでない場合　登録」からアカウントの登録を行いましょう。

ログイン後は、以下の画面が出るまで「次へ」を押して進んでください。

この画面では「カスタムインストール」を選択し、「次へ」をクリックします。

今回は、Qt 6.5.3を選択します。もしQt 6.5.3が表示されない場合は、右上の「Archive」をチェックした後「フィルター」をクリックしてください。
以下の画像の通り、Qt 6.5.3の下にある「MinGW 11.2.0 64-bit」「Qt Quick 3D」「Qt Insight Tracker(TP)」「Qt MQTT」にチェックを入れ、右下の「次へ」をクリックしてください。ここでは「Qt Insight Tracker(TP)」がQt Insight Tracker APIを使用するために必要なモジュールです。
※2023年11月現在、オープンソース版ではまだQt Insight Tracker APIがリリースされていない可能性があります。しかし、順次オープンソース版にもリリースされて参りますので、しばしお待ちください。

使用許諾規約を確認し、チェックをした後に「次へ」で次の画面に進みます。この後は、インストールが終了するまで「次へ」で次の画面に進んでください。

Windowsの場合、デフォルトではCドライブ直下の「Qt」というフォルダ内にQtがインストールされます。

Qt Creatorでプロジェクトを開く

Qtには、Qt CreatorというIDE（統合開発環境）が付属しています。

Qt Creatorを開いていきましょう。

Qt Creatorは、<Qtのインストールフォルダ>/Tools/QtCreator/bin/qtcreator.exeを実行することで開くことができます。

Qt Creatorには、様々なアプリケーションのサンプルがソースコードと一緒に用意されています。

Welcome画面の左側のメニューから「Examples」を選択し、ドロップダウンメニューでQtのバージョンを選択すると、そのバージョンのQtのサンプルアプリの一覧が表示されます。

Qt Insightのサンプルも用意されています。

検索ボックスで「Insight」と入力すると、「Qt Insight  - Qt Quick Application」というサンプルが表示されるので、ダブルクリックしてプロジェクトを開きましょう。

ダブルクリックすると、サンプルを説明するウィンドウが開くと思いますが、それはいったん閉じても大丈夫です。

Qt Creatorの左側の「Projects」からビルドの設定を選ぶことができます。「Desktop Qt 6.5.3 MinGW 64-bit」をダブルクリックすると、プロジェクトのビルド設定が走ります。成功すると、左下の再生ボタンが緑色に変化します。

Qt Insightサンプルプロジェクト

プロジェクトの中身を確認しましょう。

左側のメニューから「Edit」を選択すると、プロジェクトのファイル構成を確認することができます。

Qtのプロジェクトは、基本的にフロントエンドのGUIを.qmlファイル、バックエンドのビジネスロジックをC++またはPythonで記述する形をとります。そして、プロジェクトのコンフィグレーションは最新バージョンではCMakeで行われます。

Qt Insightは、C++とQMLのAPIを用意しています。それらを活用することで、データをクラウドに送信することができます。

CMakeLists.txt

それらのAPIを使用するためには、まずCMakeLists.txtに必要な記述をしなければなりません。

CMakeLists.txtをダブルクリックして、エディタで開いてみましょう。

Qt Insight TrackerのAPIは、InsightTrackerライブラリをアプリケーションにリンクすることで使用可能になります。下記のように、15行目のfind_package()と26行目のtarget_link_libraries()にInsightTrackerを追加する必要があります。

Qt Insightには、もう１つ重要な要素があります。それは、「qtinsight.conf」ファイルです。

CMakeLists.txtの86行目では、下記のようにqt6_add_resources()関数の引数として与えられています。

qtinsight.conf

qtinsight.confファイルは、Qt Insightの設定を行うファイルです。

左側のプロジェクト構成の中にあるので、ダブルクリックで開いてみましょう。

qtinsight.confの設定項目をいくつかご紹介します。

1. server
   
   送信先のクラウドのURLを指します。The Qt Companyが管理するクラウドにデータを送信するオプションを選択した場合、またトライアル試用期間中は、URLはデフォルトのcollect-insight.qt.ioで問題ありません。自分のクラウド環境にQt Insightのバックエンドをインストールするプライベートクラウドオプションを選択した場合は、このURLを適切なものに変更する必要が生じます。
2. token
   tokenには、Qt Insight Web Consoleで発行できるトークンを設定します。トークンを発行し、設定してみましょう。
   Qt Insight Web Consoleで、まずは最初に作ったオーガニゼーションを選択しましょう。
   
   次に、「Organization management」を開きます。
   
   「Organization management」の「Tokens」タブを開くと、Defaultのトークンが表示されます。
   表示されない場合や、新しいトークンを作成したい場合は、右上の「Add new」ボタンで追加可能です。
   ここに表示されているトークンの値をコピーします。
   
   コピーした値をqtinsight.confのtoken欄にペーストします。これで、クラウドに送信したデータが自分のQt Insight Web Consoleのオーガニゼーションに表示されるようになります。
   
   
   
3. device_model
   
   device_modelには文字列を設定可能です。設定した文字列は、Qt Insight Web Consoleのフィルタリングに使用可能です。
   
   
   
4. device_variant
   device_variantには、文字列が設定可能ですが、Qt Insight 1.5現在ではQt Insight Web Consoleでは使用されていません。
   
   
5. device_screen_type
   device_screen_typeには、Qt Insight 1.5現在では"TOUCH"または"NON_TOUCH"が設定可能ですが、Qt Insight Web Consoleには表示されません。
   
   
6. platform
   platformには、以下の文字列のいずれかを設定可能ですが、Qt Insight 1.5現在では、Qt Insight Web Consoleには表示されません。
   5-1. "web"
   5-2. "mob"
   5-3. "pc"
   5-4. "srv"
   5-5. "app"
   5-6. "tv"
   5-7. "cnsl"
   5-8. "iot"
   
   
7. storage
   storageにはQt Insight 1.5現在、"SQLITE"を設定可能で、これを設定するとSQLITEのデータベースにイベントを保存します。もしstorageに空文字や"SQLITE"以外の文字列を設定した場合、イベントのデータベースへの保存は無効化され、イベント発生時にすぐにクラウドにデータが送信されます。
   
   
8. storage_size
   Qt Insightでは、イベントが発生した際にすぐにクラウドにデータを送るのではなく、一度SQLiteのデータベースにイベントデータを保存し、その後周期的にデータベースからイベントをクラウドに送信しています。送信されたイベントはデータベースから削除されていきます。
   この「storage_size」はこのデータベースの最大サイズを表しており、保存するクエリ数の上限を設定できます。今回のように0を設定した場合、上限サイズはなくなります。
   
   
   
9. sync
   ここでは、周期的にデータをクラウドに送信する際の周期(interval)と、周期的に送信する最大イベント数(max_batch_size)を定義します。今回はintervalのsecondsが60であり、max_batch_sizeが100であることから、60秒ごとに最大100イベントをクラウドに送信する設定になっていることがわかります。intervalにはsecondsだけではなく、minutes、hours、days、monthsもあります。
   今回は送信がわかりやすくなるように、secondsを10に変更し、max_batch_sizeを1に変更しましょう。
   
   
   
10. categories
    categoriesには、フィルタリング用の文字列をリスト形式で設定します。Qt Insight 1.5現在、クラウドにデータを送信するAPI、sendClickEvent()の引数にはcategoryというものがあり(最新のQt Insightでは、sendClickEvent()は、interection()という関数に置き換わっています。最新のQt Insight TrackerのAPIについては、ドキュメンテーションをご確認ください）、ここにqtinsight.confのcategoriesのリスト内にある文字列にないものを指定すると、イベントはクラウドに送信されなく（フィルタリングされ）ます。
    
    
11. events
    
    Qt Insight 1.5かつQt 6.6現在、この「events」に定義されているQEventを、ソースコードを変更せずに自動的にクラウドに送信することができます。これにより、Qt WidgetとQMLの両方でイベントを自動的に追跡することが容易になりました。不要なものは、リストから削除しましょう。Qt Insightのトライアルは、２か月間という期間とは別に、イベント数にも制限がかかります（それぞれの１か月間で５万イベントまでクラウドが受け付けます）。ですので、無駄にイベント数を消費したくない場合で、かつこれらのイベントは特に不要である場合は、eventsのリストを空にするなどの対応も考えられます。
    送信されたイベントは、「Event log」の「Automatic interactions」より確認可能です。
    

これらの設定項目がどのように扱われているかは、Qtのソースコードにある関数QInsightConfiguration::load()を確認することで理解することができます。この関数はqinsightconfiguration.cppにあります。気になる方は、是非見てみてください。

QMLファイルでのTracker APIの使用

では、QMLファイルでの実際のTracker APIの使用例を見てみましょう。

Qt Insightの有効化

Qt Insight Tracker APIを使用するためには、QtInsightTrackerのインポートと、Qt Insight Tracker APIの有効化を行う必要があります。
main.qmlを開いてみましょう。これは、エントリーポイントとなる.qmlファイルです。

内容を確認すると、８行目でQtInsightTrackerモジュールをインポートしており、２１行目でInsightTracker.enabledプロパティをtrueに変更することでQt Insight Trackerを有効化しています。

このアプリでは、Component.onCompletedシグナルが発生した際にenabledがtrueになるようにしているので、アプリケーション起動時に自動的にQt Insight Trackerが有効化されるようになっています。

通常、この有効化は、アプリ起動時にダイアログを表示したりして、ユーザーに合意を得たりした後で行うなどが一般的ですが、実際の製品では、アプリケーションの用途と、法規に合った形で有効化することが重要になります。

ちなみに、このサンプルアプリでは、C++側でもQt InsightのAPIを使用しています。

main.cppを開くと、16行目から18行目でQtInsightTrackerクラスのインスタンスを作成し、そこからQt Insight Trackerの有効化(17行目)、Qt Insight Trackerのイベント送信インターバルの設定(18行目)を行っていることがわかります。

こちらは今回不要になりますので、コメントアウトしてしまいましょう。

Qt Insight TrackerのC++ APIに関してはこちらをご覧ください。

ユーザー操作イベントの送信（sendClickEvent）

まず、CoffeeButton.qmlを開きます。

このファイルは、名前の通り、アプリ起動時に左に出てくるコーヒー選択ボタンに相当します。

今回注目すべきは、18行目から29行目までのエリアです。

QtでGUI(Graphics User Interface)を記述するのに使用するQML言語では、「QMLタイプ」というものを階層的に記述し、その属性値を設定していくことで簡単に動的なGUIを作成することができます。

18行目で使われているMouseAreaは、その名の通りマウスやタッチイベントに対応するためのQMLタイプです。この中でonClickedやonPressedといった記述をすると、その中に記述した処理がそれぞれMouseAreaのエリアをクリックや押下した際に実行されます。

このプログラムでは、20行目でonClickedハンドラが使用されており、その中でInsightTracker.sendClickEvent()が使用されています。これが、クリックイベントをクラウドに送信するAPIです。

sendClickEvent(string name, string category, int x, int y, string contextKey, double contextValue)

実際にどのように使用されているか、確認してみましょう。以下がコール箇所です。

1. root.text
   InsightTracker.sendClickEventの第1引数であるnameには、文字列でパラメータを指定します。ここには、クリックイベントの名前を指定します。今回はroot.textという変数を指定しています。これは、CoffeeButton.qmlの中でroodというidを持つQMLタイプの、textプロパティの値を参照して引数として渡しています。
   
2. root.InsightCategory.category
   InsightTracker.sendClickEventの第2引数であるcategoryには、送信するイベントのカテゴリを指定します。ここでは、root.InsightCategory.categoryの値を指定しています。この値は、CoffeeButton.qmlをインスタンス化している場所で指定されています。
   SideBarForm.ui.qmlを開いてみましょう。ここで、CoffeeButton.qmlのインスタンスが４つ、それぞれのコーヒーの種類に対して作られています。
   
   例えば最初のCoffeeButtonのインスタンスを見ると、41行目でInsightCagetory.categoryを"coffee"に指定しています。つまり、このインスタンスのMouseAreaのonClickedでは、InsightTracker.sendClickEvent()の第２引数として"coffee"が送信されることになります。ちなみに、この第２引数のcategoryは文字列であればいいので、今回のようにInsightCategory.categoryを必ず指定しなければならないわけではありません。
3. mouseX, mouseY
   第4、第5引数では、クリックされたマウスの座標を送信しています。ここでは、MouseAreaのプロパティであるmouseXとmouseYの値を参照して送信しています。
   
   

実際にアプリを起動して、クラウドに値が送信されるかを確認してみましょう。qtinsight.confのtokenに、作成したオーガニゼーションで発行したトークンを設定すれば、実際に送信されたデータをQt Insight Web Consoleで確認することができます。
まずは、左下の緑色の再生ボタンを押して、アプリケーションをビルド/実行します。

このアプリでは、ApplicationOutputの欄にアプリケーションからのデバッグアウトプットが表示されるようになっており、そこにQt Insight Tracker APIのログも出力されるようになっています。

試しに、コーヒーマシンアプリの左側にあるコーヒーのボタンをクリックしてみてください。イベントの発生がApplication Outputに出力されるはずです。

この時点ではイベントはSQLITEのデータベースに保存され、qtinsight.confのsyncに指定された周期でクラウドに送信されます。送信時にも、Application Outputにログが出力されるようになっています。

画面遷移イベントの送信（InsightTracker.sendScreenView）

(最新のQt Insightでは、sendScreenView()は、transition()という関数に置き換わっています。最新のQt Insight TrackerのAPIについては、ドキュメンテーションをご確認ください）

次に、画面遷移イベントを記録するAPIを確認してみましょう。

ApplicationFlow.qmlを開きます。すると15行目にInsightTracker.sendScreenViewをコールしている行があります。

sendScreenView(string name)

sendScreenViewは、画面遷移が発生した際にコールするのが一般的です。

引数として渡されているnameでは、スクリーンの名前を指定するのが一般的です。
このコードでは、applicationFlow.stateを指定しています。

applicationFlowは8行目にあるApplicationFlowFormというQMLタイプのidの値であり、stateはApplicationFlowFormのプロパティの１つです。このプロパティには、それぞれ28行目、32行目、37行目、43行目で画面が変化するイベントが変化するたびに画面の名前が設定されており、また15行目のonStateChangedシグナルハンドラーはstateプロパティが変化したときに毎回実行されるので、このタイミングでInsightTracker.sendScreenViewがコールされることになり、結果的に画面が遷移するたびにクラウドにイベントが送信されることになります。

セッションの初期化（startNewSession）

Qt Insight Trackerには、startNewSession()というAPIがあります。

このAPIを使うとセッションのリセットが可能です。セッションはAverage session lengthや、

User flowsにおける一連のナビゲーションの区切りなどに使用されます。

CoffeeMachineアプリケーションでは、ApplicationFlow.qmlの87行目で使用されています。

ここでは、53行目のSequentialAnimationの最後のアクションとしてInsightTracker.startNewSession()が実行されています。

このfinalAnimationはCoffeeMachineアプリでユーザーがコーヒーを選択し、コーヒーが淹れられた後に実行されるようになっているので、このアプリケーションでは、「ユーザーが選択したコーヒーが入るまで」をひとつのセッションとして区切っているということがわかります。

アプリケーションを使ってみる 

では最後に、実際にこのアプリケーションを使ってみましょう。

まだqtinsight.confのtokenを変更していない方は、以下の手順に従って変更してください。

Qt Insight Web Consoleで、まずは最初に作ったオーガニゼーションを選択しましょう。

次に、「Organization management」を開きます。

「Organization management」の「Tokens」タブを開くと、Defaultのトークンが表示されます。
表示されない場合や、新しいトークンを作成したい場合は、右上の「Add new」ボタンで追加可能です。
ここに表示されているトークンの値をコピーします。

コピーした値をqtinsight.confのtoken欄にペーストします。これで、クラウドに送信したデータが自分のQt Insight Web Consoleのオーガニゼーションに表示されるようになります。

さらに、結果をすぐにQt Insight Web Consoleで確認したいので、今回はsyncのintervalを1にして、イベントが毎秒クラウドに送信されるようにしましょう。

では、アプリケーションを起動してみましょう。Qt Creatorの左下の緑の再生ボタンをクリックすることで、アプリケーションを起動することができます。実際に操作を行って、しばらくするとQt Insight Web Consoleにデータが反映されるはずです！

オフラインデバイスでQt Insightを使用する

組み込みアプリでは特に、常にインターネットにつながっているわけではないものもあると思います。

そういったデバイスに対してQt Insightを使用する場合は、Qt Insight TrackerモジュールをMaintenanceToolでインストールした際に<Qtインストールフォルダ>/<Qtバージョン>/<プラットフォーム>/binフォルダにインストールされるinsightuploader.exeを使用します。

このコマンドラインツールにQt Insightトラッカーを含むアプリケーションがイベントデータを保存する.dbファイルをわたすことで、オフラインデバイスの.dbファイルに保存されたデータもクラウドに送信することができます。以下では、その方法を順を追ってご説明します！

.dbファイルの保存場所の特定

.dbファイルがどこに保存されているかは、以下の手順で確認することができます。

まず、先程のCoffee Machineサンプルアプリのmain.cppを開いてみましょう。

すると、以下のように14行目にQLoggingCategory::setFilterRules("qt.singht*=true");というコマンドが確認できます。これは、5行目の#include <QtCore/QLoggingCategory>を追加することで使用できるようになる関数で、こうすることでQt Insight系のデバッグメッセージがQt CreatorのApplication Outputに出力されるようになります。

この状態で再度CoffeeMachineアプリを起動すると、以下のような出力がApplication Outputに表示されます。これによると、CoffeeMachineアプリのイベントは"C:/Users/81808/AppData/Roaming/coffee_insight/InsightTracker.db"に保存されていることがわかります。組み込みアプリの場合も同様の出力がされますので、イベントが入ったInsightTracker.dbファイルをデバイスから回収し、PCに移動する必要があります。

では、実際にこのInsightTracker.dbファイルにinsightuploader.exeを使用してイベントデータをクラウドにアップロードしてみましょう。

以下のように、--serverにqtinsight.confのserverで指定している値を指定しつつ、InsightTracker.dbのパスを引数として与えることで、クラウドにデータをアップロードすることができます。

実際にイベントはアップロードされましたでしょうか？少し時間はかかるかもしれませんが、アップロードされたイベントはEvelt logで確認可能です。

タイムスタンプを確認すると、イベントはinsightpuloader.exeを使ってイベントをアップロードした日時ではなく、実際にイベントが発生した日時を示していることがわかります。

qtinsight.confの設定

ネットワークにつながっていないデバイスは、周期的にイベントをクラウドに送信する必要がありません。その代わり、InsightTracker.dbファイルにイベントをため込んでいきます。そのため、「イベントを送信しなくてもよい」旨をqtinsight.confファイルに指定してあげる必要があります。

そのためには、以下のようにintervalに何も指定しないという設定を行います。また、明示的に0を指定することでも同じ効果を得ることができます。

storage_sizeにはInsightTracker.dbに保存する最大レコード数を記述します。例えば、ここに1000と指定した場合は、最新の1000イベントのみがデータベースに保持されるため、InsightTrakcer.dbが無制限に膨張していってしまうことはなくなります。0とした場合はイベント数に制限を設けないため、発生したイベントはすべて保存されます。

Automotive HVACデモ + Qt Insight

では最後に、Qt Insight Trackerが挿入されたもう少し本格的なデモをご紹介して、この記事を締めくくりたいと思います。

今回ご紹介するのは、Qtで実装されたAutomotive HVACデモに、Qt Insight Tracker APIを挿入したものです。

プロジェクトの入手

まずはプロジェクトを入手しましょう。以下のリンクから、gitlabのページにアクセスすることができます。

https://git.qt.io/se_japan_public/qt-insight/qt-insight-outrun-hvac-demo

gitをインストールしている方は青い「Clone」ボタンから、また、そうでない方もその左にあるダウンロードボタンから圧縮されたプロジェクトフォルダを入手することができます。

プロジェクトがダウンロードできたら、その中にあるCMakeLists.txtをQt Creatorから開きましょう。

「Open Project」からCMakeLists.txtを選択します。

Kitは「Desktop Qt 6.5.2 MinGW 64-bit」を選択します。

qtinsightconf/MinGW/qtinsight.confを開き、3行目の「token」に自分のQt Insight Web Consoleのtokenを指定します。

ここまで出来たら、実際にアプリケーションを実行してみましょう！行った操作は30秒ごとにクラウドに送信され、Qt Insight Web Consoleでデータが確認可能になるはずです。

まとめ

皆様、いかがでしたでしょうか？この記事はだいぶ長くなりましたが、Qt Insightをどのように使えばよいのか、理解を深めることができたでしょうか？

UI/UXは製品の競争力の源泉であり、重要な差別化要因です。ユーザーが真に望むものをつかみ、皆様が最高のGUIを作っていくうえで少しでもQt Insightがお役に立つことができれば、とてもうれしいです！

シリーズ記事一覧

1. 【Qt Insight入門その１】ユーザー行動を可視化し、ユーザーにとって最高のプロダクトを実現！
2. 【Qt Insight入門その２】Qt Insightをはじめよう① 無料トライアルの登録
3. 【Qt Insight入門その３】Qt Insightをはじめよう② ユーザーフローの分析
4. 【Qt Insight入門その４】Qt Insightをはじめよう③ ファネル分析、アプリケーションクラッシュ分析
5. 【Qt Insight入門その５】組み込みアプリでA/Bテスト？Qt Insightを使った様々なユーザー行動分析
6. 【Qt Insight入門その６】Qt Insightにデータを送信する方法

Qt Insight お問い合わせフォームはこちら