Quick Tracking:API Pelacakan

1. Cara melihat rencana pelacakan

Sebelum memulai pelacakan, Anda perlu menentukan lokasi dan objek yang akan dilacak, serta menyusun persyaratan pelacakan yang jelas. Di platform Quick Tracking, persyaratan eksplisit untuk pelacakan disebut rencana pelacakan, dan template spesifikasi dirancang khusus untuk mendukung rencana tersebut.

Dalam skema titik penguburan, konten pelacakan yang diperlukan mencakup:

1. Subjek acara: ID Perangkat dan ID Akun.

• ID Perangkat: ID perangkat default aplikasi HarmonyNext adalah ID perangkat unik di tingkat aplikasi, yang secara otomatis dibuat oleh Quicktracking:

• ID Akun: ID akun pengguna klien setelah masuk. Saat pengguna masuk dari perangkat berbeda, ID perangkat berubah, tetapi ID akun tetap sama. Sebagai contoh, seorang pengguna masuk secara terpisah menggunakan ponsel dan tablet.

2. Atribut Pengguna: Atribut yang terkait dengan ID akun, seperti pengguna dengan ID akun "testdemo@111", memiliki "tanggal lahir" yaitu "1999-02-13" dan "tingkat keanggotaan" yaitu "platinum". "Tanggal lahir" dan "tingkat keanggotaan" merupakan atribut pengguna.

3. Atribut Saluran: atribut terkait pengiriman iklan, mencakup saluran pengiriman, metode pengiriman, dan konten pengiriman.

4. Atribut Global: atribut yang terdapat di setiap acara setelah pengaturan awal atribut global dilakukan satu kali.

5. Acara Penelusuran Halaman: Acara yang dilaporkan saat halaman dimuat. Dalam skema pelacakan, acara dengan kode halaman yang sama dengan kode acara ditandai dengan warna biru.

6. Klik, paparan, dan acara kustom: acara yang dilaporkan saat pengguna klien berinteraksi dengan klien.

2. Pengaturan ID Perangkat&ID Akun&Atribut Pengguna

2.1. ID Perangkat

ID perangkat versi saat ini secara otomatis dibuat oleh QuickTrackingSDK. ID perangkat kustom tidak didukung.

2.1.1 Mendapatkan ID Perangkat

@quicktracking/analytics_2.0.3 versi dukungan.

import { getDeviceId } from '@quicktracking/analytics';

function getDeviceId():string

2.2. ID Akun

SDK Quick Tracking menggunakan perangkat sebagai standar untuk menghitung pengguna. Untuk menghitung akun Anda sendiri, gunakan metode berikut.

2.2.1. Login Pengguna

2.2.1.1. Deskripsi API

import { onProfileSignIn } from '@quicktracking/analytics';

function onProfileSignIn(provider: string, puid: string):void

2.2.1.2. Deskripsi Parameter

Catatan: ID akun disimpan di penyimpanan lokal dan hanya menjadi tidak valid jika Anda menghapus aplikasi, membersihkan data aplikasi, atau memanggil API logout berikut. Selain itu, setiap acara akan tetap membawa ID akun.

2.2.1.3. Contoh kode

import { onProfileSignIn } from '@quicktracking/analytics';

Button ('Masuk').onClick(() => {
  onProfileSignIn("QuickTrackingUser", "QuickTrackingUser_demo");
})

2.2.2. Logout Pengguna

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

2.2.2.1. Deskripsi API

import { onProfileSignOff } from '@quicktracking/analytics';

function onProfileSignOff():void

2.2.2.2. Contoh kode

import { onProfileSignOff } from '@quicktracking/analytics';

Button ('Keluar').onClick(() => {
  onProfileSignOff();
})

2.3. Unggah atribut pengguna

Unggah acara kustom dengan pengkodean acara tetap ke $$_user_profile. Atribut acara yang dibawa oleh acara tersebut akan ditempatkan di tabel pengguna sebagai atribut pengguna.

2.3.1. Deskripsi API

Lihat API Acara Kustom.

2.3.2. Contoh kode

import { trackEvent } from '@quicktracking/analytics';

Button ('Unggah properti pengguna').onClick(() => {
  trackEvent("$$_user_profile", {
    sex: "boy",
    age: 13,
    favorite: "basketball"
  });
})

3. Atribut Saluran

Ada dua skenario di mana informasi atribut saluran perlu dilacak:

1. Tautan H5 Memanggil Aplikasi APP Terpasang.

2. Tautan H5 Memanggil Aplikasi APP Baru Tidak Terpasang

3.1. Tautan H5 Memanggil Aplikasi APP Terpasang

Skema URL aplikasi mencakup atribut saluran, dan kunci atribut harus diawali dengan "utm_" karena kata kunci yang dikenali oleh SDK adalah "utm_".

Contohnya: utm_channel=gzh <skema URL>?

Perhatian: Jika atribut saluran telah bekerja sama dengan perusahaan pengiriman saluran di pasar dan tidak dapat dimulai dengan utm_, Anda dapat menggunakan API atribut global untuk melaporkan atribut saluran (kunci atribut tetap harus dimulai dengan utm_).

3.1.1. Contoh kode evokasi sisi H5

<html>
  <script>
    function openHarmonyApp() {
      var url = "hmapp://ut.open.realtime:80/Index?utm_a=aaa&utm_b=bbb";
      alert(url)
      window.location.href = url
    };
  </script>
  <body>
    <button onclick="openHarmonyApp()"> Panggil aplikasi Hongmeng </button>
  </body>
</html>

3.1.2. Contoh kode aplikasi Hongmeng Next

Jika aplikasi dapat dipanggil oleh tautan H5, Anda harus mengonfigurasi tag kemampuan modul. Untuk informasi lebih lanjut, lihat Dokumentasi Resmi Situs Web HarmonyOS Next.

3.1.2.1. Contoh konfigurasi

3.1.2.2. Contoh Parsing parameter utm dan atur sebagai atribut global

import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import hilog from '@ohos.hilog';
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import window from '@ohos.window';
import {registerGlobalProperties, trackAppInstall } from '@quicktracking/analytics'


export default class EntryAbility extends UIAbility {
  handleWant(want: Want) {
    if (want.uri && want.uri.indexOf('utm_')) {
      const dUri = decodeURI(want.uri)
      const utmArgs:Record<string, string> = {}
      const paramsString = dUri.split("?")[1]
      const paramsArray = paramsString.split("&")
      for (let i of paramsArray) {
        const kvs = i.split("=")
        const k: string = kvs[0]
        const v = kvs[1]
        utmArgs[k] = v
      }
      registerGlobalProperties(utmArgs)
    }
  }
  // Tautan H5 memanggil aplikasi APP, hot start
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.handleWant(want)
  }

  // Tautan H5 memanggil aplikasi APP dan cold start.
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.handleWant(want)

    //! ! !. Hanya perlu dipanggil ketika enableAutoTrackApplication = false
    trackAppInstall({
      browser: `'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.x.x Safari/537.36'`,
      page_name: "ManIndex", // Kode halaman halaman yang dipanggil. Parameter ini opsional. Kami sarankan Anda mengonfigurasi parameter ini.
      url: "pages/Index" // Jalur halaman yang memanggil halaman. Parameter ini opsional. Kami sarankan Anda mengonfigurasi parameter ini.
    }, {
      man_app_p1: 111, // Properti kustom. Opsional.
      man_app_p2: 222
    })
    
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        return;
      }
    });
  }
}

3.2. Tautan H5 Memanggil Aplikasi APP Baru Tidak Terpasang

Dalam skenario ini, jika hanya parameter "utm_" yang dibawa dalam tautan H5, parameter "utm_" tidak dapat dibawa dalam acara startup setelah aplikasi diunduh. Oleh karena itu, perlu dilakukan pencocokan fuzzy antara "acara pemanggilan H5" dan "acara aktivasi aplikasi" tentang "alamat IP dan UserAgent browser".

1. Ketika pengguna mengklik tombol "Panggil /Unduh Aplikasi" di H5, acara pemanggilan aplikasi ($$_app_link) dilaporkan. Dalam acara tersebut, appKey dan atribut saluran dari aplikasi yang dipanggil harus disertakan.

// Contoh kode
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: 'Application appKey', // Diperlukan. AppKey dari aplikasi yang akan dipanggil.
    custom1: 'custom1', // Opsional. Parameter kustom.
    ...
 }]
})

2. Setelah aplikasi diunduh, aplikasi secara otomatis atau manual melaporkan acara startup pertama $$_app_install untuk menyelesaikan tindakan terkait.

• Jika konfigurasi default SDK adalah enableAutoTrackApplication = true, acara aktivasi aplikasi $$_app_install akan dilaporkan secara otomatis.

• Jika konfigurasi default SDK adalah enableAutoTrackApplication = false, pengembang harus melaporkan acara aktivasi aplikasi secara aktif.

3.2.1. Deskripsi API

import { trackAppInstall } from '@quicktracking/analytics'

function trackAppInstall(params: {
  browser?: string,
  [key: string]: string
}, customProps?: object)

3.2.2. Contoh pemanggilan

Lihat 3.1.2 Contoh Kode Aplikasi Hongmeng Next 3.1.2. Contoh Kode Aplikasi HarmonyOS Next.

4. Atribut Global

4.1. Mendaftarkan Atribut Global

4.1.1. Deskripsi API

import { registerGlobalProperties } from '@quicktracking/analytics'

function registerGlobalProperties(params?: Record<string, string | number | string[]>)

4.1.2. Deskripsi Parameter

4.1.3. Contoh kode

import { registerGlobalProperties } from '@quicktracking/analytics'

Button ('Daftarkan properti global').onClick(async () => {
  registerGlobalProperties({
    "a": 1,
    "b": 2
  }) // Hasil keluaran:{a: 1, b: 2}
})
Button ('Daftarkan ulang properti global').onClick(async () => {
  registerGlobalProperties({
    "b": 6,
    "c": 4 
  }) // Hasil keluaran:{a: 1, b: 6, c: 4}
})

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

4.2. Hapus properti global

4.2.1. Deskripsi API

import { unregisterGlobalProperty } from '@quicktracking/analytics'

function unregisterGlobalProperty(key?: string)

4.2.2. Deskripsi Parameter

4.2.3. Contoh kode

import { unregisterGlobalProperty } from '@quicktracking/analytics'

Button ('Hapus nilai properti global').onClick(async () => {
  unregisterGlobalProperty('a')
})

4.3. Dapatkan properti global tunggal berdasarkan kunci.

4.3.1. Deskripsi API

import { getGlobalProperty } from '@quicktracking/analytics'

function getGlobalProperty(key?: string): string | number | string[] | undefined

4.3.2. Deskripsi Parameter

4.3.3. Contoh kode

import { getGlobalProperty } from '@quicktracking/analytics'

Button ('Dapatkan properti global tunggal berdasarkan kunci').onClick(async () => {
  promptAction.showToast({
    message: 'Dapatkan atribut b =${ getGlobalProperty("b")}',
    duration: 3000
  })
})

4.4. Dapatkan semua properti global.

4.4.1. Deskripsi API

import { getGlobalProperties } from '@quicktracking/analytics'

function getGlobalProperties(): Record<string, string | number | string[]>

4.4.2. Contoh kode

import { getGlobalProperties } from '@quicktracking/analytics'

Button ('Dapatkan semua properti global').onClick(async () => {
  promptAction.showToast({
    message: 'Atribut global adalah \n${JSON.stringify(getGlobalProperties())}',
    duration: 5000
  })
})

4.5. Bersihkan semua properti global

4.5.1. Deskripsi API

import { clearGlobalProperties } from '@quicktracking/analytics'

function clearGlobalProperties()

4.5.2. Contoh kode

Button ('Bersihkan semua properti global').onClick(async () => {
  clearGlobalProperties()
  promptAction.showToast({
    message: 'Atribut global adalah \n${JSON.stringify(getGlobalProperties())}',
    duration: 5000
  })
})

5. Acara penelusuran halaman

SDK QuickTracking Hongmeng Next menyediakan dua kemampuan: pelacakan halaman otomatis dan manual.

5.1. Pencapaian Otomatis

Jika konfigurasi default SDK adalah enableAutoTrackPage = true, acara penelusuran halaman dilacak secara otomatis. Untuk informasi lebih lanjut, lihat deskripsi API pra-inisialisasi.

5.2. Pencapaian Manual

Dibandingkan dengan sistem iOS atau Android, sistem Hongmeng Next tidak memiliki komponen halaman yang ketat dalam konsep. Komponen apa pun yang dideklarasikan oleh sintaks dekorator dapat dianggap sebagai komponen halaman dalam arti bisnis selama ditandai dalam file main_pages.json atau file route_map.json.

• Halaman RouterPage yang didefinisikan dalam file main_pages.json.

• Definisikan halaman NavDestination dalam file route_map.json.

5.2.1. Deskripsi API

import { onPageStart, onPageEnd } from '@quicktracking/analytics'

function onPageStart(context: PageContext | null, pageName: string, pageUrl?: string) // Panggil saat masuk halaman.
function onPageEnd(context: PageContext | null, pageName: string, pageUrl?: string) // Panggil 

saat keluar halaman.

5.2.2. Deskripsi Parameter

5.2.3. Contoh kode

• Halaman RouterPage

import { onPageStart, onPageEnd, updatePageProperties, skipAutoTrack } from '@quicktracking/analytics';

@Entry
@Component
struct RouterPageDemo {
  @State message: string = 'RouterPageDemo';

  onPageShow(): void {
    //skipAutoTrack(this)
    onPageStart(this, "RouterPageDemo")
    updatePageProperties(this, "RouterPageDemo", {
      a: 1,
      b: 2
    })
  }

  onPageHide() {
    onPageEnd(this, "RouterPageDemo")
  }

  build() {
    Column() {
      Text(this.message)
        .id('HelloWorld')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
    }
    .height('100%')
    .width('100%')
  }
}

• Halaman NavDestination

import { onPageStart, updatePageProperties, onPageEnd, skipAutoTrack } from '@quicktracking/analytics';

@Builder
export function IndexBuilder(name: string, param: Object) {
  NaviPageOne()
}

@Component
export default struct NaviPageOne {

  @State name: string = 'NaviPageOne';

  pathInfos: NavPathStack = new NavPathStack();

  build() {
    NavDestination() {
      Column() {
        Text("")
          .id('NaviPageOneHelloWorld')
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .alignRules({
            center: { anchor: '__container__', align: VerticalAlign.Center },
            middle: { anchor: '__container__', align: HorizontalAlign.Center }
          })
      }
      .height('100%')
      .width('100%')
    }
    .onReady((context: NavDestinationContext) => {
      this.pathInfos = context.pathStack
    })
    .title(this.name)
    .id(this.name)
    .onShown(() =>{
      //skipAutoTrack(this)
      onPageStart(this, "NaviPageOne")
      updatePageProperties(this, "NaviPageOne", {
        a: 1,
        b: 2
      })
    })
    .onHidden(() => {
      onPageEnd(this, "NaviPageOne")
    })
  }
}

5.3. Atur properti acara halaman.

5.3.1. Deskripsi API

import { updatePageProperties } from '@quicktracking/analytics';

function updatePageProperties(context: PageContext, pageName: string, params?: Record<string, string | number | string[]>, pageUrl?: string) 

5.3.2. Deskripsi Parameter

5.3.3. Contoh kode

Lihat bagian 5.2.3 untuk contoh kode.

5.4. Pelacakan halaman otomatis dan manual dicampur.

Dalam beberapa skenario, pelacakan pengguna diharapkan menggunakan pelacakan halaman otomatis untuk menyelesaikan pelacakan perilaku umum dan mengontrol waktu pelacakan secara manual untuk beberapa halaman untuk menyelesaikan pelacakan yang lebih rinci. Namun, jika acara penelusuran halaman otomatis dan manual dilaporkan berulang kali, akurasi data perilaku pengguna akan terpengaruh. Oleh karena itu, SDK dapat menonaktifkan pelacakan halaman otomatis untuk satu halaman.

5.4.1. Deskripsi API

import { skipAutoTrack } from '@quicktracking/analytics';

function skipAutoTrack(context: PageContext)

5.4.2. Deskripsi Parameter

5.4.3. Contoh kode

Lihat Contoh Kode 5.2.2.

Perhatian:!!!

1. Untuk memastikan statistik kode acara halaman dinormalisasi, pengembang harus memanggil onPageStart saat halaman yang dilacak secara otomatis dimuat, serta menentukan pageName dari kode acara halaman. Dalam hal ini, kode acara halaman otomatis juga akan berubah menjadi pageName yang diteruskan oleh onPageStart.

2. Jika pengembang telah mengaktifkan pelacakan otomatis acara halaman, dan halaman A tidak memanggil operasi skipAutoTrack tetapi menggunakan onPageStart dan onPageEnd secara berpasangan melalui pelacakan kode, dua acara penelusuran halaman akan dilaporkan saat halaman A ditutup.

3. Metode onPageStart dan onPageEnd harus dipanggil secara berpasangan. Jika tidak, akurasi pelacakan acara halaman akan terpengaruh.

6. Acara Kustom

6.1.1. Deskripsi API

import { trackEvent } from '@quicktracking/analytics';

function trackEvent(eventID: string, params?: Record<string, string | number | string[]>)

6.1.2. Deskripsi Parameter

6.1.3. Contoh kode

• Untuk melacak di thread UI

import { trackEvent } from '@quicktracking/analytics';
Button ('Acara kustom').onClick(() => {
  trackEvent("eventid", {
    param1: "value"
    param2: 2,
    param3: ["productId1", "productId2"],
    $page_name: "pageDemo", // Opsional. Properti acara.
    $page_url: "pages/pageDemo", // Opsional. Properti acara.
  });
});

• Untuk melacak di thread pekerja

import worker, { ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@ohos.worker';
import { trackEvent } from '@quicktracking/analytics';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = function (e: MessageEvents) {
 trackEvent("workerevent", {
    param1: "value"
    param2: 2,
    param3: ["productId1", "productId2"],
    $page_name: "pageDemo", // Opsional. Properti acara.
    $page_url: "pages/pageDemo", // Opsional. Properti acara.
  })
}

workerPort.onmessageerror = function (e: MessageEvents) {}

workerPort.onerror = function (e: ErrorEvent) {}

Tidak ada metode yang langsung dipanggil dalam c++. Jika penyematan lapisan c++ diperlukan, silakan merujuk pada pengetahuan tentang interoperabilitas antara c++ dan arkts di situs web resmi Hongmeng Next dan panggil metode trackEvent untuk mengimplementasikan penyematan melalui NAPI.

7. Lacak secara manual acara startup, keluar, dan aktivasi aplikasi

Secara default, konfigurasi SDK enableAutoTrackApplication = true diaktifkan. Jika persyaratan pelacakan untuk acara startup, keluar, dan aktivasi tidak dapat dipenuhi dalam beberapa skenario, Anda dapat secara manual memanggil operasi API untuk melacak perilaku dalam ketiga skenario tersebut.

Perhatian: !!!

Pelacakan manual acara startup, keluar, dan aktivasi aplikasi tidak dapat dicampur dengan pelacakan otomatis acara startup, keluar, dan aktivasi aplikasi. Jika tidak, akurasi statistik data terpengaruh. Artinya, enableAutoTrackApplication = false perlu disetel.

7.1. Laporkan secara manual acara aktivasi aplikasi

7.1.1. Deskripsi API

import { trackAppInstall } from '@quicktracking/analytics';

function trackAppInstall(context: ApplicationContext,  appKey: string, params: {
  browser?: string,
  $page_name?: string,
  $page_url?: string,
  [key: string]: string | number | string[]
}) {
  appTrack.manager.manualTrackAppInstall(context, appKey, params)
}

7.1.2. Deskripsi Parameter

7.1.3. Contoh kode

import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import window from '@ohos.window';
import { trackAppInstall } from '@quicktracking/analytics';

export default class EntryAbility extends UIAbility {

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    trackAppInstall(
      this.context.getApplicationContext(), 
      "The appKey of your application", 
      {
        $browser: 'Mozilla/5.0 Chrome/126. X.X Safari/537.36', // Opsional. Nilai default adalah undefined.
        $page_name: "home_page", // Opsional. Nilai default adalah undefined.
        $page_url: "pages/Index", // Opsional. Nilai default adalah undefined.
        utm_source: "hwbroser", 
        man_app_p1: 111,
        man_app_p2: '222',
        man_app_p3: ['1', '2']
      }
    )
  }
}

7.2. Laporkan secara manual acara startup aplikasi

7.2.1. Deskripsi API

import { trackAppStart } from '@quicktracking/analytics';

function trackAppStart(params: {
  isFirstLaunch?: boolean,
  $page_name?: string,
  $page_url?: string,
}, customParams?: object )

7.2.2. Deskripsi Parameter

7.2.3. Contoh kode

import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import window from '@ohos.window';
import { trackAppStart } from '@quicktracking/analytics';

export default class EntryAbility extends UIAbility {

  onForeground(): void {
    
    trackAppStart({
      isFirstLaunch: true, // Opsional. Nilai default: false.
      $page_name: "home_page", // Opsional. Nilai default adalah undefined.
      $page_url: "pages/Index" // Parameter opsional. Nilai default: undefined.
    }, {
      man_app_p1: 111,
      man_app_p2: "222",
      man_app_p3: ['1', '2']
    })
    
  }
}

7.3. Laporkan secara manual acara keluar aplikasi

7.3.1. Deskripsi API

import { trackAppEnd } from '@quicktracking/analytics';

function trackAppEnd(params: {
  $page_name?: string,
  $page_url?: string,
  duration?: number
}, customParams?: object)

7.3.2. Deskripsi Parameter

7.3.3. Contoh kode

import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import window from '@ohos.window';
import { trackAppEnd } from '@quicktracking/analytics';

export default class EntryAbility extends UIAbility {

  onBackground(): void {
    
    trackAppEnd({
      $page_name: "home_page",
      $page_url: "pages/Index",
      duration: 666
    }, {
      man_app_p1: 111,
      man_app_p2: "222",
      man_app_p3: ['1', '2']
    })
    
  }
}