Quick Tracking:トラッキング API

1. トラッキングソリューションを表示するにはどうすればよいですか。

埋点する前に、どこでトラッキングするか、何をトラッキングするかを決定する必要があります。つまり、明確な埋点要件を整理する必要があります。 Quick Tracking プラットフォームでは、明示的なトラッキング要件はトラッキングソリューションと呼ばれ、トラッキングソリューション用に仕様テンプレートが設計されています。

トラッキングプランでは、必要なトラッキングコンテンツは次のとおりです。

1. イベント件名: デバイス ID および アカウント ID。

• デバイス ID: Windows デバイスのデフォルトのデバイス ID は、アプリケーションレベルで一意のデバイス ID です。デバイス ID は、 Quick Tracking SDK によって自動的に生成されるか、setCustomDeviceId 操作を呼び出すことができます。

• アカウント ID: クライアントユーザーがシステムにログインするためのアカウント ID。ユーザーが異なるデバイスからログインすると、デバイス ID は変更されますが、アカウント ID は変更されません。たとえば、ユーザーがコンピューターとパッドを使用して個別にログインします。

2. ユーザー属性: アカウント ID の属性。たとえば、アカウント ID が「testdemo@111」のユーザーの「誕生日」は「1999-02-13」、「メンバーシップレベル」は「プラチナ」です。「誕生日」と「メンバーシップ」の評価はユーザー属性です。

3. グローバル属性: グローバル属性が一度設定された後、各イベントで伝送される属性

4. ページ閲覧イベント: ページが読み込まれたときに報告されるイベント。トラッキングプランでは、ページコードがイベントコードと同じイベントは青色でマークされます。

5. クリック、露出、カスタムイベント: クライアントユーザーがクライアントと対話したときに報告されるイベント。

2. トラッキングに関する注意事項

• 入力パラメーターは、単一引用符やデータ型などの特殊な文字列をサポートしていません。サポートしている場合、イベントがデータベースから削除されず、データが失われる可能性があります。

• 中国語パラメーターを使用するには、ソースコードファイルのエンコーディングが有効な Unicode（UTF-8 符号なし）エンコーディングである必要があります。

• ログ切り替え操作を除き、操作を有効にする前に initQTPC 操作を呼び出す必要があります。

• Windows 10.X では、GetVersionEx を使用してシステムバージョンを不正確に取得できます。この場合は、マニフェストファイルをプロジェクトフォルダーに追加し、マニフェストファイルをプロジェクトのプロパティ> インベントリツール> 入力と出力> 追加のインベントリファイルに追加する必要があります。次のサンプルファイルを使用します。

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
      <asmv3:application>
        <asmv3:windowsSettings xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">
          <dpiAware>false</dpiAware>
        </asmv3:windowsSettings>
      </asmv3:application>
      <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
          <application>
              <!-- Windows 10 and Windows 11 --> 

• 入力パラメーターサイズの制限:

// カスタム属性とグローバル属性のキーと値が上限を超えると、設定を完了できません。
const size_t kStringPropertyValueMaxLength=4096; // カスタムプロパティとグローバルプロパティ値の上限。
const size_t kStringPropertyKeyMaxLength=1024; // カスタムプロパティとグローバルプロパティキーの最大値。
const size_t kStringArrayValueMaxSize=100; // カスタム属性文字列配列の長さの上限。上限を超えると、文字列配列は切り捨てられます。
const size_t kStringMapValueMaxSize=50; // グローバル属性セットの上限。上限を超えると、それ以上のデータを挿入できません。
const size_t kStringEventCodeMaxLength=500; // イベントコードの最大長

3. デバイス ID、アカウント ID、およびユーザー属性の設定

3.1 デバイス ID

SDK はカスタムデバイス ID をサポートしています。カスタムデバイス ID を使用する場合は、setCustomDeviceId インターフェースを有効な値に設定する必要があります。

インターフェース関数:

// カスタムデバイス ID を指定します。
QTFORPC_API QT_VOID setCustomDeviceId(QT_CSTR deviceId);

パラメーター:

string customDeviceId = "testId";
qtInterface->setCustomDeviceId(customDeviceId.c_str());

3.2 アカウント ID

3.2.1 ユーザーログイン

デバイスに基づくユーザー統計の Quick Tracking SDK では、標準として、独自のアカウントをカウントする必要がある場合は、次の方法を使用してください。

インターフェース関数:

// アプリケーションにログインします。
QTFORPC_API QT_VOID onProfileSignIn(QT_CSTR userID, QT_CSTR nick);

パラメーター:

qtInterface->onProfileSignIn("userId", "userNick");

3.2.2 ユーザーログアウト

ユーザーアカウントをバインドする必要がなくなった場合は、SDK が提供するユーザーログアウトメソッドを呼び出すことができます。メソッドを呼び出すと、SDK はユーザーアカウント関連のコンテンツを送信しなくなります。

インターフェース関数:

// ログアウトします。
QTFORPC_API QT_VOID onProfileSignOff();

qtInterface->onProfileSignOff();

3.3 ユーザー属性のアップロード

イベントエンコーディングを使用して、$$_user_profile カスタムイベントアップロードを行います。イベントによって伝送されるイベント属性は、ユーザー属性としてユーザーテーブルに保存されます。

注: データの精度を確保するために、uploadUserProfile は onPageStart 後、onPageEnd 前に呼び出す必要があります。

インターフェース関数:

// ユーザー属性をアップロードします。
QTFORPC_API QT_VOID uploadUserProfile(QT_VSTR pageObj, QT_MAP customProperties);

パラメーター:

WNDCLASS *wndClass = new WNDCLASS();
qtInterface->onPageStart(wndClass, "PageName");
std::string cusp = R"({
    "age": 18,
    "level": "King",
    "name": "coolboy",
})";
qtInterface->uploadUserProfile(wndClass, cusp.c_str());
qtInterface->onPageEnd(wndClass);

4. グローバル属性

4.1 グローバル属性の登録

インターフェース関数:

// グローバルプロパティを設定します。
QTFORPC_API QT_VOID registerGlobalProperty(QT_CSTR key, QT_CSTR value);

パラメーター:

qtInterface->registerGlobalProperty("key", "value");

注: 既存のグローバル属性のキーが既存のグローバル属性のキーと同じである場合、既存の値が更新されます。既存のグローバル属性のキーが既存のグローバル属性のキーと異なる場合は、新しいグローバル属性が挿入されます。

4.2 グローバル属性を削除する

API 関数:

// キーに基づいてグローバル属性を削除します。
QTFORPC_API QT_VOID unregisterGlobalProperty(QT_CSTR key);

パラメータ:

qtInterface->unregisterGlobalProperty("key");

4.3 キーに基づいて単一のグローバル属性を取得する

API 関数:

// キーに基づいてグローバルプロパティを取得します。
QTFORPC_API QT_VOID getGlobalProperty(QT_CSTR key, QT_STR value, QT_INT size);

パラメータ:

// サイズは必要に応じて設定されます。
char value[64] = { 0 };
qtInterface->getGlobalProperty("key", value, 64);
string myValue = value;

4.4 すべてのグローバルプロパティを取得する

API 関数:

// グローバル属性をすべて取得します。
QTFORPC_API QT_VOID getGlobalProperties(QT_STR properties, QT_INT size);

パラメータ:

// サイズは必要に応じて設定されます。
char properties[128] = { 0 };
qtInterface->getGlobalProperties(properties);
std::map<string, string> myProperties = QT::Helper::QT_DeserializePerson(properties, 128);

5. ページ閲覧イベント

5.1 ページでの手動トラッキング

インターフェース関数:

// ページの表示が開始されます。
QTFORPC_API QT_VOID onPageStart(QT_VSTR pageObj, QT_CSTR pageName);
// ページが非表示になり始めます。
QTFORPC_API QT_VOID onPageEnd(QT_VSTR pageObj);

パラメータ:詳細については、「WordPress REST API」をご参照ください。

5.2 ページイベントのプロパティの設定

API 関数:

// ページイベントパラメータを設定します。
QTFORPC_API QT_VOID updatePageProperties(QT_VSTR pageObj, QT_MAP pageProperties);

パラメータ:

WNDCLASS *wndClass = new WNDCLASS();
// ページ開始時に qtInterface を呼び出す
qtInterface->onPageStart(wndClass, "PageName");
std::string cusp = R"({
    "param_str": "hello c++",
    "param_num": 1900,
    "param_bool": true,
    "param_list": ["hello", "world", "c++"]
})";
// ページのプロパティを更新する
qtInterface->updatePageProperties(wndClass, cusp.c_str());
// ページ終了時に qtInterface を呼び出す
qtInterface->onPageEnd(wndClass);

4.4 すべてのグローバルプロパティを取得する

現在のページ（コンテナ内の子ページ）の前のページ（ソースページはコンテナページ）をスキップします。

API 関数:

// マルチコンテナネストのコンテナをスキップします。
QTFORPC_API QT_VOID skipPage(QT_VSTR pageObj);

WNDCLASS *wndClass = new WNDCLASS();
qtInterface->onPageStart(wndClass, "firstPage");
std::string cusp = R"({
    "param_str": "hello c++",
    "param_num": 1900,
    "param_bool": true,
    "param_list": ["hello", "world", "c++"]
})";
qtInterface->updatePageProperties(wndClass, cusp.c_str());
qtInterface->onPageEnd(wndClass);

WNDCLASS *wndClass1 = new WNDCLASS();
qtInterface->onPageStart(wndClass1, "secondPage");
qtInterface->onPageEnd(wndClass1);

WNDCLASS *wndClass2 = new WNDCLASS();
// thirdPage の前のページ、つまり secondPage をスキップします。この場合、thirdPage の ref_page_name は firstPage です。 skipPage が呼び出されない場合、ref_page_name は secondPage です。
qtInterface->skipPage(wndClass2);
qtInterface->onPageStart(wndClass2, "thirdPage");
qtInterface->onPageEnd(wndClass2);

6. イベントトラッキング

カスタムイベントを使用して、ユーザーの行動を追跡し、行動の具体的な詳細を記録できます。

インターフェース関数:

// トラッキングイベント。
QTFORPC_API QT_VOID trackEvent(QT_VSTR pageObj, QT_CSTR id, QT_MAP customProperties);
// トラッキングイベントには、ページ名が含まれます。
QTFORPC_API QT_VOID trackEventWithPageName(QT_VSTR pageObj, QT_CSTR id, QT_MAP customProperties, QT_CSTR pageName);

パラメータ:

WNDCLASS *wndClass = new WNDCLASS();
// ページ開始を通知
qtInterface->onPageStart(wndClass, "PageName");
std::string cusp = R"({
    "param_str": "hello c++",
    "param_num": 1900,
    "param_bool": true,
    "param_list": ["hello", "world", "c++"]
})";
// ページ名付きのイベントを追跡
qtInterface->trackEventWithPageName(wndClass, "test_event", cusp.c_str(), "PageName");
// ページ終了を通知
qtInterface->onPageEnd(wndClass);

7. アプリケーションの起動と終了イベントを手動でトラックする

API 関数:

// フォアグラウンドに入ります。
QTFORPC_API QT_VOID enterForeground(QT_VSTR pageObj, QT_MAP customProperties);
// PageName を使用してフォアグラウンドに入ります。
QTFORPC_API QT_VOID enterForegroundWithPageName(QT_VSTR pageObj, QT_MAP customProperties, QT_CSTR pageName);
// バックグラウンドに入ります。
QTFORPC_API QT_VOID enterBackground(QT_VSTR pageObj, QT_MAP customProperties);
// PageName を使用してバックグラウンドに入ります。
QTFORPC_API QT_VOID enterBackgroundWithPageName(QT_VSTR pageObj, QT_MAP customProperties, QT_CSTR pageName);

パラメーター:

WNDCLASS *wndClassForeground = new WNDCLASS();
// ページ開始
qtInterface->onPageStart(wndClassForeground, "StartPageName");
std::string start_cusp = R"({
    "param_str": "hello c++",
    "param_num": 1900,
    "param_bool": true,
    "param_list": ["hello", "world", "c++"]
})";
// フォアグラウンドに入る
qtInterface->enterForeground(wndClassForeground, start_cusp.c_str());
// ページ終了
qtInterface->onPageEnd(wndClassForeground);

WNDCLASS *wndClassBackground = new WNDCLASS();
// ページ開始
qtInterface->onPageStart(wndClassBackground, "EndPageName");
std::string end_cusp = R"({
    "param_str": "hello c++",
    "param_num": 1900,
    "param_bool": true,
    "param_list": ["hello", "world", "c++"]
})";
// バックグラウンドに入る
qtInterface->enterBackground(wndClassBackground, end_cusp.c_str());
// ページ終了
qtInterface->onPageEnd(wndClassBackground);

8. その他

8.1 ローカルへのデータ保存を停止する

finiQTPC を呼び出して、データベースからのデータの削除を停止できます。現在、Stop メソッドのみ使用可能です。

API 関数:

パラメータ:

void callBackFunc()
{
	fprintf(stderr, "finiQTPC コールバック\n"); // finiQTPC コールバック
}

qtInterface->finiQTPC(callBackFunc);

リアルタイムデバッグモード 8.2

設定エンドポイントは、WordPress の設定の読み取りと更新を可能にします。詳細については、「設定」をご参照ください。

注: アプリケーションを正式に起動する前に、SDK のリアルタイム デバッグ モードを無効にしてください。

API 関数:

// リアルタイムデバッグモードを有効にします。
QTFORPC_API QT_VOID turnOnRealTimeDebug(QT_MAP configs);
// リアルタイムデバッグを無効にします。
QTFORPC_API QT_VOID turnOffRealTimeDebug();

パラメータ:

map<string, string> configs; // configs マップ
configs["debug_key"] = "test"; // デバッグキーを "test" に設定
std::string sconfig;
QT::Helper::QT_Serializable(sconfig, configs);
qtInterface->turnOnRealTimeDebug(sconfig.c_str()); // リアルタイムデバッグを有効にする

qtInterface->turnOnRealTimeDebug(); // リアルタイムデバッグを有効にする

クイックアップロードモードを有効にする 8.3

WordPress のバージョン 4.7 以降では、REST API がデフォルトで有効になっています。以前のバージョンを使用している場合は、REST API プラグインをインストールする必要があります。

注: アプリケーションを正式に起動する前に、SDK クイックアップロードモードを無効にしてください。

API 関数:

// クイックアップロードモードを有効にします。
QTFORPC_API QT_VOID setFastUploadMode();

qtInterface->setFastUploadMode();