Quick Tracking:API Pelacakan

1. Bagaimana cara melihat solusi pelacakan?

Sebelum memasukkan titik penguburan, Anda perlu menentukan di mana dan apa yang akan dilacak, yaitu menyusun persyaratan titik penguburan yang jelas. Di platform Quick Tracking, persyaratan pelacakan eksplisit disebut solusi pelacakan, dan template spesifikasi dirancang untuk solusi tersebut.

Dalam rencana pelacakan, konten pelacakan yang diperlukan meliputi:

1. Subjek kejadian: ID Perangkat dan ID Akun.

• ID Perangkat: ID perangkat default untuk perangkat Windows adalah ID unik perangkat pada tingkat aplikasi. ID perangkat secara otomatis dibuat oleh Quick Tracking SDK atau Anda dapat memanggil operasi setCustomDeviceId.

• ID Akun: ID akun pengguna klien untuk masuk ke sistem. Ketika pengguna masuk dari perangkat yang berbeda, ID perangkat berubah, tetapi ID akun tidak berubah. Sebagai contoh, seorang pengguna masuk secara terpisah menggunakan komputer dan tablet.

2. Atribut pengguna: atribut dari ID akun, seperti pengguna dengan ID akun "testdemo@111", "tanggal lahir" adalah "1999-02-13", dan "tingkat keanggotaan" adalah "platinum". "Tanggal lahir" dan "peringkat keanggotaan" adalah atribut pengguna.

3. Atribut global: atribut yang dibawa dalam setiap kejadian setelah atribut global ditetapkan sekali.

4. Kejadian penelusuran halaman: kejadian yang dilaporkan ketika halaman dimuat. Dalam rencana pelacakan, kejadian dengan kode halaman yang sama dengan kode kejadian ditandai dengan warna biru.

5. Klik, tayangan, dan kejadian kustom: kejadian yang dilaporkan ketika pengguna klien berinteraksi dengan klien.

2. Catatan Pelacakan

• Parameter input tidak mendukung string khusus seperti tanda kutip tunggal dan tipe data. Jika tidak, kejadian mungkin gagal dijatuhkan dari database dan data mungkin hilang.

• Penggunaan parameter Cina mengharuskan bahwa pengkodean file sumber adalah pengkodean Unicode (UTF-8 tanpa tanda) yang valid.

• Kecuali untuk operasi saklar log, Anda harus memanggil operasi initQTPC sebelum operasi berlaku.

• Di Windows 10.x, Anda dapat menggunakan GetVersionEx untuk mendapatkan versi sistem secara tidak akurat. Dalam kasus ini, Anda harus menambahkan file manifest ke folder proyek dan tambahkan file manifest ke properti proyek> alat inventaris> masukan dan keluaran> file inventaris tambahan. File sampel berikut digunakan:

  <?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 -->
              <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
              <!-- Windows 8.1 -->
              <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
              <!-- Windows 8 -->
              <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
              <!-- Windows 7 -->
              <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
              <!-- Windows Vista -->
              <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/> 
          </application>
      </compatibility>
      <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
          <security>
              <requestedPrivileges>
                  <!--
                    Pengaturan UAC:
                    - aplikasi harus berjalan pada tingkat integritas yang sama dengan proses pemanggil
                    - aplikasi tidak perlu memanipulasi jendela milik
                      proses tingkat integritas lebih tinggi
                    -->
                  <requestedExecutionLevel
                      level="asInvoker"
                      uiAccess="false"
                  />   
              </requestedPrivileges>
          </security>
      </trustInfo>
   </assembly>

• Batas ukuran parameter input:

// Jika kunci dan nilai atribut kustom dan global melebihi batas atas, pengaturan tidak dapat diselesaikan.
const size_t kStringPropertyValueMaxLength=4096; // Batas atas nilai properti kustom dan global.
const size_t kStringPropertyKeyMaxLength=1024; // Nilai maksimum kunci properti kustom dan global.
const size_t kStringArrayValueMaxSize=100; // Batas atas panjang array string atribut kustom. Jika batas atas terlampaui, array string dipotong.
const size_t kStringMapValueMaxSize=50; // Batas atas set atribut global. Jika batas atas terlampaui, tidak ada lagi data yang dapat dimasukkan.
const size_t kStringEventCodeMaxLength=500; // panjang maksimum kode kejadian 

3. Pengaturan ID Perangkat, ID Akun, dan atribut pengguna

3.1 ID Perangkat

SDK mendukung ID perangkat kustom. Jika Anda ingin menggunakan ID perangkat kustom, Anda harus mengatur antarmuka setCustomDeviceId ke nilai yang valid.

Fungsi antarmuka:

// Tentukan ID perangkat kustom.
QTFORPC_API QT_VOID setCustomDeviceId(QT_CSTR deviceId);

Parameter:

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

3.2 ID Akun

3.2.1 Masuk Pengguna

Quick Tracking SDK dalam statistik pengguna berdasarkan standar perangkat. Jika Anda perlu mencatat akun mereka sendiri, silakan gunakan metode berikut.

Fungsi antarmuka:

// Masuk ke aplikasi.
QTFORPC_API QT_VOID onProfileSignIn(QT_CSTR userID, QT_CSTR nick);

Parameter:

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

3.2.2 Keluar Pengguna

Jika Anda tidak lagi perlu mengikat akun pengguna, Anda dapat memanggil metode logout pengguna yang disediakan oleh SDK. Setelah Anda memanggil metode tersebut, SDK tidak lagi mengirimkan konten terkait akun pengguna.

Fungsi antarmuka:

// Keluar.
QTFORPC_API QT_VOID onProfileSignOff();

qtInterface->onProfileSignOff();

3.3 Unggah atribut pengguna

Gunakan pengkodean kejadian untuk $$_user_profile unggah kejadian kustom. Atribut kejadian yang dibawa oleh kejadian disimpan dalam tabel pengguna sebagai atribut pengguna.

Catatan: uploadUserProfile harus dipanggil setelah onPageStart dan sebelum onPageEnd untuk memastikan akurasi data.

Fungsi antarmuka:

// Unggah properti pengguna.
QTFORPC_API QT_VOID uploadUserProfile(QT_VSTR pageObj, QT_MAP customProperties);

Parameter:

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. Atribut Global

4.1 Daftarkan Atribut Global

Fungsi antarmuka:

// Tetapkan properti global.
QTFORPC_API QT_VOID registerGlobalProperty(QT_CSTR key, QT_CSTR value);

Parameter:

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

Catatan: Jika kunci atribut global yang ada sama dengan kunci atribut global yang ada, nilai yang ada diperbarui. Jika kunci atribut global yang ada berbeda dari kunci atribut global yang ada, atribut global baru dimasukkan.

4.2 hapus atribut global

Fungsi API:

// Hapus atribut global berdasarkan kunci.
QTFORPC_API QT_VOID unregisterGlobalProperty(QT_CSTR key);

Parameter:

qtInterface->unregisterGlobalProperty("key");

4.3 untuk mendapatkan atribut global tunggal berdasarkan kunci

Fungsi API:

// Dapatkan properti global berdasarkan kunci.
QTFORPC_API QT_VOID getGlobalProperty(QT_CSTR key, QT_STR value, QT_INT size);

Parameter:

// Ukuran diatur sesuai kebutuhan.
char value[64] = { 0 };
qtInterface->getGlobalProperty("key", value, 64);
string myValue = value;

4.4 Dapatkan Semua Properti Global

Fungsi API:

// Dapatkan semua atribut global.
QTFORPC_API QT_VOID getGlobalProperties(QT_STR properties, QT_INT size);

Parameter:

// Ukuran diatur sesuai kebutuhan.
char properties[128] = { 0 };
qtInterface->getGlobalProperties(properties);
std::map<string, string> myProperties = QT::Helper::QT_DeserializePerson(properties, 128);

5. Kejadian Penelusuran Halaman

Pelacakan Manual pada Halaman 5.1

Fungsi antarmuka:

// Halaman mulai ditampilkan.
QTFORPC_API QT_VOID onPageStart(QT_VSTR pageObj, QT_CSTR pageName);
// Halaman mulai menghilang.
QTFORPC_API QT_VOID onPageEnd(QT_VSTR pageObj);

Parameter:

WNDCLASS *wndClass = new WNDCLASS();
qtInterface->onPageStart(wndClass, "PageName");
qtInterface->onPageEnd(wndClass);

5.2 pengaturan properti kejadian halaman

Fungsi API:

// Tetapkan parameter kejadian halaman.
QTFORPC_API QT_VOID updatePageProperties(QT_VSTR pageObj, QT_MAP pageProperties);

Parameter:

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->updatePageProperties(wndClass, cusp.c_str());
qtInterface->onPageEnd(wndClass);

5.3 Lewati Kontainer

Melewati halaman sebelumnya (halaman sumber adalah halaman kontainer) dari halaman saat ini (halaman anak di dalam kontainer).

Fungsi API:

// Lewati kontainer untuk bersarang multi-kontainer.
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();
// Melewati halaman sebelumnya dari thirdPage, yaitu secondPage. Dalam hal ini, ref_page_name dari thirdPage adalah firstPage. Jika skipPage tidak dipanggil, ref_page_name adalah secondPage. 
qtInterface->skipPage(wndClass2);
qtInterface->onPageStart(wndClass2, "thirdPage");
qtInterface->onPageEnd(wndClass2);

6. Pelacakan Kejadian

Kejadian kustom dapat digunakan untuk melacak perilaku pengguna dan mencatat detail spesifik dari perilaku tersebut.

Fungsi antarmuka:

// Melacak kejadian.
QTFORPC_API QT_VOID trackEvent(QT_VSTR pageObj, QT_CSTR id, QT_MAP customProperties);
// Melacak kejadian termasuk nama halaman.
QTFORPC_API QT_VOID trackEventWithPageName(QT_VSTR pageObj, QT_CSTR id, QT_MAP customProperties, QT_CSTR pageName);

Parameter:

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. Lacak secara manual acara startup dan keluar aplikasi

Fungsi antarmuka:

// Masuk ke latar depan.
QTFORPC_API QT_VOID enterForeground(QT_VSTR pageObj, QT_MAP customProperties);
// Masuk ke latar depan dengan NamaHalaman.
QTFORPC_API QT_VOID enterForegroundWithPageName(QT_VSTR pageObj, QT_MAP customProperties, QT_CSTR pageName);
// Masuk ke latar belakang.
QTFORPC_API QT_VOID enterBackground(QT_VSTR pageObj, QT_MAP customProperties);
// Masuk ke latar belakang dengan NamaHalaman.
QTFORPC_API QT_VOID enterBackgroundWithPageName(QT_VSTR pageObj, QT_MAP customProperties, QT_CSTR pageName);

Parameter:

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. Lainnya

8.1 hentikan penyimpanan data ke lokal

Anda dapat memanggil finiQTPC untuk menghentikan penjatuhan data dari database. Saat ini, hanya metode Stop yang tersedia.

Fungsi API:

// deinitialize QT
QTFORPC_API QT_VOID finiQTPC(QT_CB cb);

Parameter:

void callBackFunc()
{
	fprintf(stderr, "finiQTPC callback\n");
}

qtInterface->finiQTPC(callBackFunc);

Mode debugging waktu nyata 8.2

Panggil turnOnRealTimeDebug untuk mengaktifkan mode debugging waktu nyata. Interval pelaporan data menjadi 30 detik. Panggil turnOffRealTimeDebug untuk menonaktifkan debugging waktu nyata.

Catatan: Sebelum aplikasi diluncurkan secara resmi, nonaktifkan mode debugging waktu nyata SDK.

Fungsi API:

// Aktifkan mode debugging waktu nyata.
QTFORPC_API QT_VOID turnOnRealTimeDebug(QT_MAP configs);
// Nonaktifkan debugging waktu nyata.
QTFORPC_API QT_VOID turnOffRealTimeDebug();

Parameter:

map<string, string> configs;
configs["debug_key"] = "test";
std::string sconfig;
QT::Helper::QT_Serializable(sconfig, configs);
qtInterface->turnOnRealTimeDebug(sconfig.c_str());

qtInterface->turnOnRealTimeDebug();

Aktifkan mode unggah cepat 8.3

Panggil setFastUploadMode untuk mengaktifkan mode unggah cepat. Interval pelaporan data berubah menjadi satu laporan per detik. Nilai defaultnya adalah tiga laporan per detik.

Catatan: Sebelum aplikasi diluncurkan secara resmi, nonaktifkan mode unggah cepat SDK.

Fungsi API:

// Aktifkan mode unggah cepat.
QTFORPC_API QT_VOID setFastUploadMode();

qtInterface->setFastUploadMode();