Hướng Dẫn Track Events
Trong hướng dẫn này: Bạn sẽ học cách sử dụng Li2 Analytics SDK để track lead events (signup, form submissions) và sale events (purchases, subscriptions) với các ví dụ thực tế.
Yêu Cầu
Trước khi track events, đảm bảo bạn đã:Cài Đặt SDK
Đã hoàn thành Setup Guide và cài đặt Li2 Analytics SDK
Enable Tracking
Đã bật conversion tracking cho touchpoint trong Settings
Lead Tracking
Lead event đánh dấu khi khách hàng thể hiện sự quan tâm đến sản phẩm/dịch vụ của bạn. Đây là bước trung gian quan trọng giữa visit và sale.Khi Nào Track Lead?
Form Submissions
Form Submissions
Khi khách hàng điền form liên hệ, đăng ký nhận tư vấn, hoặc request demo.Ví dụ: Form “Liên hệ chúng tôi”, “Đặt lịch demo”, “Nhận báo giá”
Account Signups
Account Signups
Khi khách hàng tạo tài khoản mới hoặc đăng ký trial.Ví dụ: Đăng ký Free plan, Start trial, Tạo account
Newsletter Subscriptions
Newsletter Subscriptions
High-Intent Actions
High-Intent Actions
Khi khách hàng thực hiện hành động có ý định cao.Ví dụ: Add to cart, Download whitepaper, Xem pricing page
Cách Track Lead
- Client-Side (Browser)
- Server-Side (Node.js)
Sử dụng khi: Track trực tiếp trong browser sau khi user submit form hoặc signup.
Click ID tự động: SDK tự động lấy click ID từ cookie
li_cid, bạn không cần truyền thủ công.Lead Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
eventName | string | ✅ | Tên lead event (VD: “Signup”, “Contact Form”) |
customerExternalId | string | ✅ | ID khách hàng trong hệ thống của bạn |
customerEmail | string | ⚪ | Email khách hàng (khuyến nghị) |
customerName | string | ⚪ | Tên khách hàng |
customerAvatar | string | ⚪ | URL avatar |
metadata | object | ⚪ | Dữ liệu bổ sung (max 10,000 chars) |
clickId | string | Server only | Click ID (chỉ cần khi track từ server) |
Sale Tracking
Sale event đánh dấu conversion thành công - khách hàng đã hoàn thành giao dịch mua hàng.Khi Nào Track Sale?
E-commerce Purchases
E-commerce Purchases
Khi khách hàng hoàn thành thanh toán và order được confirm.Timing: Sau khi payment processor confirm success (webhook từ Stripe, PayPal, etc.)
Subscription Payments
Subscription Payments
Khi khách hàng subscribe plan trả phí (monthly/annual).Timing: Sau khi first payment thành công hoặc trial convert to paid
One-time Services
One-time Services
Khi khách hàng thanh toán dịch vụ (consulting, booking, etc.).Timing: Sau khi payment confirmed hoặc booking confirmed with payment
Cách Track Sale
- Client-Side (Browser)
- Server-Side (Webhook)
Sử dụng khi: Track ngay sau checkout success trên thank-you page.
Sale Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customerExternalId | string | ✅ | ID khách hàng (phải giống với lead event) |
amount | number | ✅ | Số tiền (smallest unit: cents, xu) |
eventName | string | ⚪ | Tên sale event (default: “Purchase”) |
currency | string | ⚪ | Mã tiền tệ (default: “usd”) |
invoiceId | string | ⚪ | Invoice/transaction ID (dùng để dedupe) |
paymentProcessor | string | ⚪ | Payment processor (“stripe”, “paypal”, etc.) |
customerEmail | string | ⚪ | Email (auto-create customer nếu chưa có) |
customerName | string | ⚪ | Tên khách hàng |
metadata | object | ⚪ | Dữ liệu bổ sung (max 10,000 chars) |
clickId | string | Server only | Click ID (chỉ cần khi track từ server) |
Multi-currency Support: Li2 hiện hỗ trợ tracking revenue trong 2 loại tiền tệ:
- USD (US Dollar):
currency: "usd" - VND (Vietnamese Dong):
currency: "vnd" - Li2 tự động convert sang default currency của organization để tính tổng revenue
- Original currency được lưu giữ trong event data
Common Use Cases
- SaaS Signup → Subscription
- E-commerce: Product Purchase
- Lead Gen: Form → Consultation Booking
Funnel: Visit → Trial Signup → Paid Subscription
Step 1: User clicks touchpoint linkBest Practices
1. Consistent customerExternalId Across Events
1. Consistent customerExternalId Across Events
QUAN TRỌNG: Sử dụng CÙNG MỘT Tại sao: Li2 dùng
customerExternalId cho cả lead và sale events của cùng khách hàng.customerExternalId để link lead → sale và aggregate metrics.2. Track Sale Từ Server-Side (Recommended)
2. Track Sale Từ Server-Side (Recommended)
Lý do nên track sale từ server:
- ✅ Chống fraud: User không thể fake sale event
- ✅ Accuracy: Webhook confirms payment thực sự thành công
- ✅ Reliability: Không bị ảnh hưởng bởi ad blockers hoặc network issues
3. Sử dụng invoiceId Để Handle Webhook Retries
3. Sử dụng invoiceId Để Handle Webhook Retries
Khi webhook được retry (Stripe, PayPal thường retry khi timeout), Cách hoạt động:
invoiceId giúp Li2 tránh duplicate trong vòng 7 ngày:- Trong 7 ngày: Li2 cache và trả về response cũ, không tạo duplicate
- Sau 7 ngày: Cache expire, có thể tạo sale event mới nếu gửi lại
4. Metadata Cho Reporting & Analysis
4. Metadata Cho Reporting & Analysis
Lưu thông tin bổ sung vào
metadata để phân tích sau:Metadata limit: 10,000 characters (JSON stringified)
5. Handle Errors Gracefully
5. Handle Errors Gracefully
Tracking failures không nên block user experience:
Utility Functions
Li2 Analytics SDK cung cấp các helper functions:isTrackingAvailable()
Kiểm tra xem click ID có available hay không (user có đến từ tracked link không):getClickId()
Lấy click ID hiện tại (useful khi cần gửi lên server):Troubleshooting
Lead/Sale không xuất hiện trong dashboard?
Lead/Sale không xuất hiện trong dashboard?
Check list:
-
Verify response: Check console hoặc Network tab
-
Click ID available?
-
Touchpoint có enable conversion tracking?
- Vào touchpoint Settings → Conversion Tracking phải ON
-
Allowed hostnames configured?
- Settings → Analytics → Allowed Hostnames phải có domain hiện tại
-
Publishable key đúng?
- Verify key trong script tag khớp với Settings → Analytics
Error: 'customerExternalId is required'
Error: 'customerExternalId is required'
Sale không link được với Lead?
Sale không link được với Lead?
Nguyên nhân phổ biến: Verify: Check customer profile trong dashboard xem có cả lead và sale events không.
customerExternalId không match.Revenue không đúng?
Revenue không đúng?
Check amount format: Phải dùng smallest currency unitVND Example:
Server-side tracking: 'clickId is required'
Server-side tracking: 'clickId is required'
Server không thể auto-detect click ID. Bạn PHẢI capture từ client:

