Skip to content

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.

APIPeran
LandingAnalyticsIdentitas, validasi, antrean, batch dan retry
LandingAnalyticsProviderConsent, konfigurasi, lifecycle dan GA bridge
ButicsBindingsListener bersama untuk elemen dengan atribut tracking
useLandingAnalytics()Mengirim interaksi khusus melalui runtime yang sama
useTrackedImpression()View dengan visibility threshold
useButicsCarousel()Navigasi carousel oleh pengunjung
AnalyticsWhatsAppLinkKlik 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:
tsx
<NavIntlLink
  href={url}
  id={trackingId || undefined}
  data-gtm-id={trackingId || undefined}
  data-bm-id={trackingId || ""}
>
  {label}
</NavIntlLink>
  1. 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:

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

tsx
const navigate = useButicsCarousel(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 browser baru dan browser dengan nilai lama denied atau granted: semuanya mengirim mode otomatis saat CMS mengaktifkan tracking. Nilai browser lama tidak dibaca.
  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.

Integrasi PDP memakai helper yang sama. Lihat Product detail tracking untuk konfigurasi dan persyaratan rilis.

Bind an internal control to a CMS-owned ID ​

tsx
<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 Butics 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.

Bumame Engineering · Butics — Butech Analytics