Appearance
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:
| Aksi | Event | Konfigurasi / sumber identitas |
|---|---|---|
| Produk dibuka | page_view | page_key=pdp; page_entity_id=product.id |
| Intro terlihat | component_impression | binding pdp_hero → Tracking ID section dari CMS |
| Detail/item terlihat | component_impression | pdp_details / pdp_detail_item; item.id sebagai entity_id |
| FAQ dibuka | accordion_open | kontrol FAQ; ID item pertanyaan |
| Pesan Sekarang diklik | component_click | product.order_button_id dari form konten |
| CTA banner diklik | component_click | product.cta_banner.button_id dari form konten |
| Scroll mencapai milestone | page_scroll | binding 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
| Repository | File utama yang dibaca |
|---|---|
Bumame/cnc_api_go | internal/modules/landing/tracking/analytics.go, analytics_button_ids.go; internal/modules/landing/migrations/sql/036_analytics_pdp.sql |
Bumame/cnc_flutter | lib/modules/landing_cms/tracking/landing_section_analytics_catalog.dart; products/landing_cms_product_screens.dart |
Bumame/landing_next_v2 | src/lib/analytics/; src/app/product/[slug]/page.tsx; src/components/products/ProductCtaLink.tsx |
Bumame/dataform-landing-analytics | definitions/butics/; page dimension serta quality contract |
Bumame/tracking-docs | Panduan 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:
analytics.gomendaftarkanpdpsebagai page type dan halaman yang membutuhkan page_entity_id. Validasi frontend dan backend harus sepakat.- Migration
036_analytics_pdp.sqlmenambahkan konfigurasi template, menginisialisasi ID tombol yang kosong/tidak valid/konflik, dan mempertahankan URL/UTM. analytics_button_ids.gomembaca ID tombol langsung dari tabel konten. Sumber order:landing_legacy_products.order_button_id; sumber banner:landing_legacy_product_cta_banners.button_id.- Resolver memetakan kontrol
pdp_ctake ID tombol konten. Public config berisi ID efektif; collector memakai resolusi yang sama. - 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.