Chuyển đến nội dung chính

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?

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á”
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
Khi khách hàng subscribe newsletter hoặc email updates.Ví dụ: Đăng ký nhận tin tức, Subscribe blog updates
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

Sử dụng khi: Track trực tiếp trong browser sau khi user submit form hoặc signup.
// Sau khi user submit form thành công
li2Analytics.trackLead({
  eventName: "Contact Form Submitted",
  customerExternalId: "user_12345", // Your internal user ID
  customerEmail: "[email protected]",
  customerName: "Nguyễn Văn A",
  metadata: {
    formType: "contact",
    message: "Interested in premium plan",
    source: "landing_page"
  }
})
.then(result => {
  if (result.success) {
    console.log('Lead tracked!', result.customerId);
  } else {
    console.error('Failed:', result.message);
  }
});
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

ParameterTypeRequiredDescription
eventNamestringTên lead event (VD: “Signup”, “Contact Form”)
customerExternalIdstringID khách hàng trong hệ thống của bạn
customerEmailstringEmail khách hàng (khuyến nghị)
customerNamestringTên khách hàng
customerAvatarstringURL avatar
metadataobjectDữ liệu bổ sung (max 10,000 chars)
clickIdstringServer onlyClick ID (chỉ cần khi track từ server)
Best Practice cho customerExternalId: Sử dụng ID persistent và unique:
  • ✅ User ID từ database: "user_12345"
  • ✅ Email nếu chưa có account: "[email protected]"
  • ❌ Session ID (không persistent): "sess_abc123"
ID này dùng để link lead → sale events của cùng một khách hàng.

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?

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

Sử dụng khi: Track ngay sau checkout success trên thank-you page.
// Trên Thank You Page sau khi checkout thành công
li2Analytics.trackSale({
  customerExternalId: "user_12345",
  amount: 4999, // $49.99 in cents
  eventName: "Product Purchase",
  currency: "usd",
  invoiceId: "inv_abc123", // Unique invoice ID
  paymentProcessor: "stripe",
  customerEmail: "[email protected]",
  customerName: "Nguyễn Văn A",
  metadata: {
    productId: "prod_premium",
    productName: "Premium Plan - Annual",
    discount: "SAVE20"
  }
})
.then(result => {
  if (result.success) {
    console.log('Sale tracked!', result.saleEventId);
  }
});
Amount Format: LUÔN sử dụng smallest currency unit (cents, xu, etc.)
  • 4999 (nghĩa là $49.99)
  • 49.99 (sẽ được hiểu là $0.4999)

Sale Parameters

ParameterTypeRequiredDescription
customerExternalIdstringID khách hàng (phải giống với lead event)
amountnumberSố tiền (smallest unit: cents, xu)
eventNamestringTên sale event (default: “Purchase”)
currencystringMã tiền tệ (default: “usd”)
invoiceIdstringInvoice/transaction ID (dùng để dedupe)
paymentProcessorstringPayment processor (“stripe”, “paypal”, etc.)
customerEmailstringEmail (auto-create customer nếu chưa có)
customerNamestringTên khách hàng
metadataobjectDữ liệu bổ sung (max 10,000 chars)
clickIdstringServer onlyClick 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

Funnel: Visit → Trial Signup → Paid Subscription

Step 1: User clicks touchpoint link
Li2 tự động capture click ID và lưu vào cookie
Step 2: User signs up for trial (Lead Event)
// Sau khi signup form submit thành công
li2Analytics.trackLead({
  eventName: "Trial Signup",
  customerExternalId: newUser.id,
  customerEmail: newUser.email,
  customerName: newUser.name,
  metadata: {
    plan: "pro_trial",
    trialDays: 14
  }
});
Step 3: User subscribes after trial (Sale Event)
// Trong Stripe webhook handler
await li2.trackSale({
  clickId: savedClickId, // Đã lưu khi signup
  customerExternalId: user.id,
  amount: 2900, // $29/month
  currency: "usd",
  eventName: "Subscription Started",
  paymentProcessor: "stripe",
  invoiceId: invoice.id,
  metadata: {
    plan: "pro_monthly",
    billingInterval: "month"
  }
});

Best Practices

QUAN TRỌNG: Sử dụng CÙNG MỘT customerExternalId cho cả lead và sale events của cùng khách hàng.
// ✅ ĐÚNG: Cùng ID
trackLead({ customerExternalId: "user_123", ... })
trackSale({ customerExternalId: "user_123", ... })

// ❌ SAI: Khác ID
trackLead({ customerExternalId: "user_123", ... })
trackSale({ customerExternalId: "order_456", ... }) // Li2 không link được
Tại sao: Li2 dùng customerExternalId để link lead → sale và aggregate metrics.
Khi webhook được retry (Stripe, PayPal thường retry khi timeout), invoiceId giúp Li2 tránh duplicate trong vòng 7 ngày:
trackSale({
  invoiceId: "inv_abc123", // Unique per transaction
  amount: 4999,
  // ...
});
Cách hoạt động:
  • 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
Use case: Đủ để handle webhook retries phổ biến (Stripe retry trong 72h). Không phải permanent deduplication.
Lưu thông tin bổ sung vào metadata để phân tích sau:
metadata: {
  // Campaign tracking
  utm_source: "facebook",
  utm_campaign: "summer_sale",

  // Product details
  productCategory: "electronics",
  sku: "PROD-123",

  // Customer insights
  isReturningCustomer: true,
  customerSegment: "vip"
}
Metadata limit: 10,000 characters (JSON stringified)
Tracking failures không nên block user experience:
try {
  const result = await li2Analytics.trackSale({...});
  if (!result.success) {
    // Log error nhưng KHÔNG show lỗi cho user
    console.error('Tracking failed:', result.message);
    // Optionally: retry hoặc log to error tracking service
  }
} catch (error) {
  console.error('Tracking error:', error);
  // User vẫn thấy success message của purchase
}

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):
if (li2Analytics.isTrackingAvailable()) {
  // User came from a Li2 touchpoint
  trackLead({...});
} else {
  // User came from direct traffic or other sources
  // Skip tracking hoặc handle differently
}

getClickId()

Lấy click ID hiện tại (useful khi cần gửi lên server):
const clickId = li2Analytics.getClickId();

if (clickId) {
  // Gửi lên server để track sau
  await fetch('/api/save-lead', {
    method: 'POST',
    body: JSON.stringify({ clickId, ...formData })
  });
}

Troubleshooting

Check list:
  1. Verify response: Check console hoặc Network tab
    const result = await trackLead({...});
    console.log(result); // { success: true/false, message: ... }
    
  2. Click ID available?
    console.log('Click ID:', li2Analytics.getClickId());
    // Nếu null → user không đến từ tracked link
    
  3. Touchpoint có enable conversion tracking?
    • Vào touchpoint Settings → Conversion Tracking phải ON
  4. Allowed hostnames configured?
    • Settings → Analytics → Allowed Hostnames phải có domain hiện tại
  5. Publishable key đúng?
    • Verify key trong script tag khớp với Settings → Analytics
// ❌ Missing customerExternalId
trackLead({
  eventName: "Signup"
  // customerExternalId: ... <- THIẾU
});

// ✅ Fixed
trackLead({
  eventName: "Signup",
  customerExternalId: user.id // REQUIRED
});
Check amount format: Phải dùng smallest currency unit
// ❌ SAI
trackSale({ amount: 49.99, currency: "usd" }) // → $0.49 (!!)

// ✅ ĐÚNG
trackSale({ amount: 4999, currency: "usd" }) // → $49.99
VND Example:
// ✅ ĐÚNG
trackSale({ amount: 500000, currency: "vnd" }) // → 500,000 VND
Server không thể auto-detect click ID. Bạn PHẢI capture từ client:
// ❌ SAI: Server-side tracking without clickId
li2.trackLead({
  eventName: "Signup",
  customerExternalId: "user_123"
  // clickId: ... <- THIẾU
});

// ✅ ĐÚNG: Capture từ client, gửi lên server
// Client:
const clickId = li2Analytics.getClickId();
fetch('/api/signup', {
  body: JSON.stringify({ clickId, ...data })
});

// Server:
li2.trackLead({
  clickId: clickId, // From client
  eventName: "Signup",
  customerExternalId: "user_123"
});

Next Steps