Skip to content

Engineer walkthrough: add PDP tracking ​

Panduan ini memakai satu fitur nyata: halaman Product Details (PDP). Anda akan memahami urutan perubahan yang sudah diterapkan pada PDP production, lalu mengulang pola yang sama saat membuat fitur baru. Jangan menjalankan migration PDP lagi hanya untuk mencoba contoh.

1. Start with a tracking plan ​

Tulis kontrak sebelum menyentuh UI. Untuk PDP:

AksiEventKonfigurasi / sumber identitas
Produk dibukapage_viewpage_key=pdp; page_entity_id=product.id
Intro terlihatcomponent_impressionbinding pdp_hero → Tracking ID section dari CMS
Detail/item terlihatcomponent_impressionpdp_details / pdp_detail_item; item.id sebagai entity_id
FAQ dibukaaccordion_openkontrol FAQ; ID item pertanyaan
Pesan Sekarang diklikcomponent_clickproduct.order_button_id dari form konten
CTA banner diklikcomponent_clickproduct.cta_banner.button_id dari form konten
Scroll mencapai milestonepage_scrollbinding page_scroll; depth_percent

Tentukan batasnya: PDP template berlaku untuk semua produk; ID produk membedakan record. View section memakai ID section, klik CTA memakai ID tombol. Tidak ada nomor telepon, judul medis bebas, atau input pasien pada payload.

2. Find the owning repositories ​

RepositoryFile utama yang dibaca
Bumame/cnc_api_gointernal/modules/landing/tracking/analytics.go, analytics_button_ids.go; internal/modules/landing/migrations/sql/036_analytics_pdp.sql
Bumame/cnc_flutterlib/modules/landing_cms/tracking/landing_section_analytics_catalog.dart; products/landing_cms_product_screens.dart
Bumame/landing_next_v2src/lib/analytics/; src/app/product/[slug]/page.tsx; src/components/products/ProductCtaLink.tsx
Bumame/dataform-landing-analyticsdefinitions/butics/; page dimension serta quality contract
Bumame/tracking-docsPanduan ini; terpisah dari aplikasi

Mulai branch dari main production untuk perubahan legacy PDP. Jangan ikut membawa PDP pengganti di development. Baca AGENTS.md masing-masing checkout dan periksa diff sebelum membuat PR.

3. Prepare Go and the database contract ​

Apakah Go perlu berubah? Ya, bila ada page_key baru, properti/event baru, sumber Tracking ID baru, atau konfigurasi komponen belum tersedia. Tidak perlu mengubah Go hanya untuk mengedit nilai label/ID pada kontrol yang sudah terpasang.

Untuk PDP implementasi yang sudah ada:

  1. analytics.go mendaftarkan pdp sebagai page type dan halaman yang membutuhkan page_entity_id. Validasi frontend dan backend harus sepakat.
  2. Migration 036_analytics_pdp.sql menambahkan konfigurasi template, menginisialisasi ID tombol yang kosong/tidak valid/konflik, dan mempertahankan URL/UTM.
  3. analytics_button_ids.go membaca ID tombol langsung dari tabel konten. Sumber order: landing_legacy_products.order_button_id; sumber banner: landing_legacy_product_cta_banners.button_id.
  4. Resolver memetakan kontrol pdp_cta ke ID tombol konten. Public config berisi ID efektif; collector memakai resolusi yang sama.
  5. Collision berbeda produk/tujuan ditolak. Dua placement pada produk dan tujuan persis sama boleh berbagi identitas CTA sesuai aturan resolver.

Contoh fragmen config tersimpan, bukan HTTP body lengkap:

json
{
  "pages": {
    "pdp": {
      "enabled": true,
      "components": {
        "pdp_hero": {
          "tracking_id": "pdp_hero",
          "label": "Product introduction",
          "enabled": true,
          "events": ["component_impression"]
        }
      }
    }
  }
}

Kunci pdp_hero adalah binding stabil. Jika editor mengganti Tracking ID menjadi product_intro, konfigurasi publik menyatakan component_bindings.pdp.pdp_hero=product_intro; event mendatang memakai component_id=product_intro. Jangan mengubah literal binding di JSX untuk setiap perubahan CMS.

Migration harus idempotent sesuai migration runner, memiliki lock/statement timeout, diuji pada salinan/staging yang diizinkan, dan dilengkapi backup/rollback. SQL history tetap disimpan setelah deploy; script bantu UAT bukan pengganti migration.

4. Add the CMS section ​

PDP menggunakan widget yang sama dengan halaman lain. Pada form produk:

dart
// Di BmSectionContainer untuk bagian intro:
footer: landingSectionAnalytics('pdp', 'intro'),

Factory tersebut mengambil definisi dari landing_section_analytics_catalog.dart. Bentuk reusable API dasarnya:

dart
const LandingSectionAnalytics(
  pageKey: 'pdp',
  sectionTitle: 'Product intro',
  componentTitles: {'pdp_hero': 'Product introduction'},
  interactions: [
    SectionAnalyticsInteraction(
      'pdp_hero',
      'component_impression',
      'Product introduction',
      'Measure visible product introductions.',
    ),
  ],
)

Import widget dan SectionAnalyticsInteraction dari file tracking yang sesuai. Snippet ini menunjukkan satu section; ketika menggunakan catalog production, jangan menambah widget kedua untuk kontrol yang sama.

Untuk tombol, gunakan field Tracking ID yang sudah ada pada form konten. Jangan buat field identifier kedua di Analytics. contentIdentityHints menjelaskan bahwa switch CTA mengendalikan order dan banner. Section view tetap punya ID sendiri. Boolean On/Off berasal dari pasangan component/event yang ditentukan engineer; editor tidak mengetik nama event bebas.

Urutan editor: simpan konten/ID tombol → buka/reload Analytics → atur interaksi → Save analytics. Save Analytics tidak menyimpan harga, judul atau isi produk. Widget mengambil config terbaru dan menerapkan perubahan section agar bagian lain tetap utuh.

5. Attach the existing Next.js runtime ​

Provider sudah berada pada root aplikasi. Jangan membuat UUID/session provider baru pada halaman produk.

Pasang konteks record pada root halaman, seperti source production:

tsx
<main
  data-bm-page-entity={product.id}
  data-bm-page-path={`/product/${product.slug}`}
>
  {/* Existing product UI */}
</main>

Tanpa identitas ini, tracking halaman detail memang ditahan agar event tidak kehilangan produk pemiliknya. Path marker harus sama dengan route aktif, termasuk perpindahan SPA antarproduk.

Untuk section, gunakan binding dan listener bersama:

tsx
<section data-bm-key="pdp_details" data-bm-exposure="true">
  {product.details.map(item => (
    <article key={item.id}
      data-bm-key="pdp_detail_item"
      data-bm-exposure="true"
      data-bm-entity={item.id}>
      {/* Existing item UI */}
    </article>
  ))}
</section>

product.details di atas adalah ilustrasi koleksi item—gunakan nama field model halaman sebenarnya. Marker tracking dan API helper adalah bentuk yang tersedia; jangan menyalin model contoh menjadi kontrak API baru.

Untuk tombol gunakan komponen production:

tsx
<ProductCtaLink
  href={product.cta_banner.button_url}
  id={product.cta_banner.button_id}
>
  {product.cta_banner.button_label || 'Pesan Sekarang'}
</ProductCtaLink>

Di dalamnya, ID yang sama diteruskan ke id, data-gtm-id, dan data-bm-id. Jika ID kosong, data-bm-id="" tetap dipasang supaya klik tidak mewarisi ID parent. Button tetap berfungsi, tetapi klik tanpa konfigurasi tidak boleh diklaim terukur.

Untuk komponen custom yang tidak dapat memakai binding, gunakan useLandingAnalytics().track(...). Pilih satu jalur pengiriman: manual atau listener otomatis. Gunakan data-bm-manual="true" untuk area manual agar listener klik tidak mengirim lagi. Jangan menambahkan pemanggilan gtag manual; GA bridge sudah menangani mirror.

6. Handle WhatsApp through the journey path ​

Gunakan helper/komponen WA yang sudah ada dan resolver tujuan. Jangan sekadar menambah UUID ke URL lalu menganggap referensi tersimpan. prepareWhatsApp membangun event; journey endpoint menyimpan event+CRM reference; mirror GA untuk journey diterbitkan setelah keberhasilan.

Pertahankan tujuan asli dan UTM. Tes URL CRM /wa/<template> serta short link yang dikonfigurasi. Kode pendek di pesan bukan event_id, session_id, atau UUID bm_click_id. Jangan mengirim pesan ke CS saat UAT tanpa otorisasi pengiriman pesan.

7. Add the data dimension and finish the feature ​

Tambahkan page label pada core_butics.dim_base_pages jika page type baru. Kolom payload baru memerlukan pembaruan validator, staging projection, GA bridge bila relevan, dokumentasi dan tests—bukan hanya TypeScript type.

Periksa Testing and release. Fitur selesai setelah konfigurasi, website, collector dan data yang tersimpan sesuai kontrak; bukan saat toggle CMS terlihat.

Bumame Engineering · Butics — Butech Analytics