Integrate tracking in Next.js

Reuse the installed runtime

Kode utama berada di src/lib/analytics/. Provider sudah dipasang pada aplikasi; jangan membuat provider baru pada setiap tombol.

API	Peran
LandingAnalytics	Identitas, validasi, antrean, batch dan retry
LandingAnalyticsProvider	Consent, konfigurasi, lifecycle dan GA bridge
BumamelyticsBindings	Listener bersama untuk elemen dengan atribut tracking
useLandingAnalytics()	Mengirim interaksi khusus melalui runtime yang sama
useTrackedImpression()	View dengan visibility threshold
useBumamelyticsCarousel()	Navigasi carousel oleh pengunjung
AnalyticsWhatsAppLink	Klik WhatsApp dan persiapan referensi journey

AnalyticsLink dan AnalyticsButton juga tersedia di source, tetapi mayoritas komponen saat ini memakai atribut + listener bersama. Jangan memasang pengiriman manual dan listener otomatis pada interaksi yang sama.

Add a CMS-backed button

1. Gunakan field Tracking ID konten yang sudah ada.
2. Daftarkan sumber ID di resolver Go analytics_button_ids.go, beserta kontrol konfigurasi yang sesuai.
3. Pastikan halaman dan event diizinkan katalog/config API.
4. Pasang nilai yang sama pada atribut website:

<NavIntlLink
  href={url}
  id={trackingId || undefined}
  data-gtm-id={trackingId || undefined}
  data-bm-id={trackingId || ""}
>
  {label}
</NavIntlLink>

5. Tampilkan switch pada widget CMS, lalu uji satu klik menghasilkan satu event.

Pertahankan marker data-bm-id="" ketika ID kosong agar elemen tidak mewarisi ID section induknya. Atribut saja belum cukup apabila resolver/config belum mengenali ID tersebut.

Track a custom interaction

Di client component di bawah provider:

const { track } = useLandingAnalytics();

// Panggil setelah respons submit benar-benar berhasil.
track({
  event: "form_submit_result",
  componentId: "contact_form",
  properties: { status: "success" },
});

contact_form adalah contoh binding key: daftarkan key, event, dan Tracking ID yang disimpan melalui CMS sebelum digunakan. Runtime mengubah key menjadi Tracking ID dari konfigurasi server. Jangan kirim isi form atau menandai success sebelum API memberi hasil.

Track a carousel

const navigate = useBumamelyticsCarousel(emblaApi, "home_hero");
// Di button handler:
navigate("next");

Hook menangani arrow dan swipe. Autoplay tidak dihitung sebagai navigasi pengunjung. position mengikuti indeks slide runtime, dimulai dari 0. Klik CTA slide menggunakan Tracking ID item; navigasi dan impression memakai identitas carousel.

Track visibility

useTrackedImpression(ref, { componentId, entityId, properties: { position } }) mengukur minimal 50% terlihat selama satu detik ketika dokumen terlihat. Jangan pasang hook ini bersamaan dengan binding impression otomatis pada target sama.

Verify your component

1. Uji consent Off dan On.
2. Uji switch event Off dan On.
3. Periksa request /api/tracking/events: ID, event, page, dan properties benar.
4. Pastikan satu aksi tidak menghasilkan event ganda.
5. Uji desktop/mobile, ID kosong, retry, dan navigasi.
6. Untuk WhatsApp, periksa journey dan referensi CRM, bukan hanya klik.

PDP belum diaktifkan. Pemakaian helper pada PDP membutuhkan aktivasi route, katalog, collector, CMS, dan pengujian tersendiri.

Bind an internal control to a CMS-owned ID

<button data-bm-key="location_slug_ExpandableRichText_1" onClick={toggleExpanded}>
  Read more
</button>

data-bm-key is an internal binding, not the emitted Tracking ID. CMS stores tracking_id: "clinic_read_more" under this binding. The public API returns component_bindings.clinic.location_slug_ExpandableRichText_1 = "clinic_read_more" and an effective component configuration keyed by clinic_read_more. The runtime resolves the binding before sending either bmlytics events or GA events, including WhatsApp journeys.

Use data-bm-id={trackingId || ""} for an existing content-owned button ID. Use data-bm-key for an internal control configured through Analytics. Hooks resolve the same configuration. An unconfigured binding has no effective event configuration and emits nothing; it must not silently fall back to a filename-derived ID.

Apply migration 034_analytics_tracking_ids.sql before activating the updated runtime. It seeds existing IDs in the database once, preserving historical continuity and existing custom IDs. Future renames are CMS edits, not code edits. Deploy the backend and CMS contract together before enabling the updated website.