> ## Documentation Index > Fetch the complete documentation index at: https://docs.li2.ai/llms.txt > Use this file to discover all available pages before exploring further. # Hướng Dẫn Cài Đặt Conversion Tracking > Hướng dẫn từng bước để bật conversion tracking cho touchpoints và tích hợp Li2 Analytics SDK vào website hoặc ứng dụng của bạn. # Hướng Dẫn Cài Đặt Conversion Tracking **Trong hướng dẫn này**: Bạn sẽ học cách bật conversion tracking cho touchpoints, cài đặt Li2 Analytics SDK, và chuẩn bị hệ thống để track lead và sale events. ## Yêu Cầu Trước Khi Bắt Đầu **Yêu cầu gói dịch vụ**: Conversion tracking chỉ khả dụng cho: * **Premium Plan** trở lên * **Premium Trial** (để dùng thử) Nếu bạn đang dùng gói Free hoặc Basic, vui lòng nâng cấp để sử dụng tính năng này. Trước khi bắt đầu, hãy đảm bảo bạn có: Owner hoặc Manager role trong organization Ít nhất một touchpoint để track conversions Khả năng thêm JavaScript code vào trang web của bạn Premium plan hoặc cao hơn *** ## Tổng Quan Quy Trình Cài Đặt Quá trình cài đặt conversion tracking gồm 4 bước chính: Kích hoạt tracking trong touchpoint settings Thêm tracking code vào website/app của bạn Thiết lập allowed hostnames để bảo vệ dữ liệu Test và confirm tracking hoạt động đúng *** ## Bước 1: Bật Conversion Tracking cho Touchpoint ### 1.1 Truy Cập Touchpoint Settings Trong dashboard, navigate đến **Touch-Points** và chọn touchpoint bạn muốn track conversions. Click tab **Settings** (biểu tượng ⚙️) trong touchpoint details page. Scroll xuống phần **Advanced Settings** → tìm **Conversion Tracking**. ### 1.2 Kích Hoạt Conversion Tracking Trong phần Conversion Tracking: 1. **Toggle switch** sang ON (màu xanh) 2. Click **Save Changes** để lưu **Best Practice**: Chỉ bật conversion tracking cho touchpoints thực sự cần đo lường ROI (ví dụ: campaign chính, landing pages quan trọng). Điều này giúp giữ dữ liệu sạch và dễ phân tích. Bật conversion tracking không ảnh hưởng đến hoạt động hiện tại của touchpoint. Link ngắn, QR code, và NFC vẫn hoạt động bình thường. Tracking chỉ bắt đầu khi bạn tích hợp SDK (Bước 2). *** ## Bước 2: Cài Đặt Li2 Analytics SDK Li2 Analytics SDK là thư viện JavaScript giúp track conversions tự động. ### Cài Đặt cho Website HTML Thông Thường Thêm script này vào `` hoặc trước `` của tất cả các pages cần track: ```html theme={null} ``` **Thay thế publishableKey:** * Tìm dòng: `s.setAttribute("data-publishable-key", "li2_pk_xxxxxxxx");` * Thay `li2_pk_xxxxxxxx` bằng publishable key thực của bạn từ Settings → Analytics **Vị trí đặt script:** * **Trong ``**: Load sớm, đảm bảo tracking luôn hoạt động * **Trước ``**: Không block page render, nhưng có thể miss early events **Khuyến nghị**: Đặt trong `` với `defer` attribute (đã có sẵn trong script) để balance giữa performance và tracking accuracy. ### Cài Đặt cho WordPress **Plugin Đang Phát Triển**: Chúng tôi đang phát triển Li2 Analytics plugin cho WordPress để cài đặt dễ dàng hơn. Hiện tại, vui lòng sử dụng phương pháp thêm script thủ công bên dưới. **Cách 1: Sử dụng Plugin "Insert Headers and Footers"** 1. Cài đặt plugin **Insert Headers and Footers** 2. Vào **Settings → Insert Headers and Footers** 3. Paste script tracking code (từ tab HTML/JavaScript) vào **Scripts in Header** 4. Save changes **Cách 2: Thêm Trực Tiếp vào Theme** 1. Vào **Appearance → Theme File Editor** 2. Mở file `header.php` 3. Paste script tracking code (từ tab HTML/JavaScript) trước `` 4. Update file **Chú ý**: Nếu update theme, bạn sẽ mất code tracking. Khuyến nghị dùng plugin hoặc child theme để tránh vấn đề này. *** ## Bước 3: Cấu Hình Bảo Mật ### 3.1 Thiết Lập Allowed Hostnames Allowed Hostnames là danh sách domains được phép gửi tracking requests. Đây là lớp bảo mật quan trọng để chặn abuse. Navigate đến **Settings → Analytics** trong organization settings. Trong phần **Security**, tìm **Allowed Hostnames** và add domains của bạn: **Ví dụ:** * `example.com` - Chỉ cho phép domain chính xác * `*.example.com` - Cho phép tất cả subdomains (www, app, blog, etc.) * `localhost` - Cho phép local development (khuyến nghị trong dev) Click **Save** để áp dụng whitelist. **Quan trọng**: Nếu không add allowed hostnames, tracking requests sẽ **BỊ CHẶN**. Đảm bảo add đủ tất cả domains và subdomains bạn sử dụng. **Wildcard Support:** | Pattern | Cho phép | | ----------------- | ----------------------------------------------------- | | `example.com` | Chỉ `example.com` | | `www.example.com` | Chỉ `www.example.com` | | `*.example.com` | `app.example.com`, `blog.example.com`, etc. | | `*` | **Tất cả domains** (KHÔNG khuyến nghị cho production) | **Development Setup**: Khi develop local, add `localhost` hoặc `127.0.0.1` vào allowed hostnames. Remove khi deploy production. ### 3.2 Xem Lại Publishable Key Publishable key được tự động tạo khi bạn enable Analytics. Để xem: 1. Vào **Settings → Analytics** 2. Copy **Publishable Key** (dạng `li2_pk_...`) 3. Paste vào SDK configuration (đã làm ở Bước 2) **Publishable vs Secret Key**: * **Publishable key** (`li2_pk_...`): An toàn để expose phía client, dùng cho SDK * **Secret key** (`li2_sk_...`): Chỉ dùng server-side, KHÔNG expose ra client Conversion tracking SDK chỉ cần publishable key. *** ## Bước 4: Xác Minh Cài Đặt ### 4.1 Test Click ID Capture Sau khi cài đặt SDK, test xem click ID có được capture đúng không: Từ touchpoint đã enable conversion tracking, copy short link (VD: `li2.link/test-campaign`) Mở trình duyệt ở chế độ ẩn danh (Incognito) và click vào short link Mở **Developer Tools** (F12) → **Application** → **Cookies** Tìm cookie tên `li_cid` với value dạng: `cm3w...` ✅ **Thành công** nếu cookie tồn tại ❌ **Thất bại** nếu không có cookie → Check lại SDK installation Trong **Console** tab, nhập: ```javascript theme={null} li2Analytics ``` Nếu SDK load đúng, bạn sẽ thấy object với functions: `trackLead`, `trackSale` **Nguyên nhân phổ biến:** 1. **SDK chưa load**: Check Network tab, tìm request đến `unpkg.com/@li2/analytics` 2. **Publishable key sai**: Verify key trong script khớp với key trong Settings 3. **Click link không có uid parameter**: Li2 tự động add parameter `?uid=...` - nếu không có, touchpoint setting có thể chưa đúng 4. **Third-party cookies bị block**: Một số browser block third-party cookies - `li_cid` là first-party nên không bị ảnh hưởng, nhưng check setting browser **Cách fix**: Re-install SDK, verify publishable key, test lại với browser khác **Nguyên nhân:** 1. **Script chưa load xong**: Đợi page load hoàn toàn rồi thử lại 2. **CDN blocked**: Check Network tab xem request đến unpkg.com có bị block không 3. **Ad blocker**: Tắt ad blocker và test lại **Cách fix**: Check script tag trong HTML source, verify CDN accessible, disable ad blockers **Nguyên nhân:** * Domain hiện tại không có trong **Allowed Hostnames** **Cách fix**: 1. Vào Settings → Analytics → Allowed Hostnames 2. Add domain hiện tại (VD: `example.com`) 3. Save và test lại CORS error message thường rất rõ ràng: `Request origin 'https://example.com' is not included in the allowed hostnames`. Copy exact domain và add vào allowed list. ### 4.2 Test End-to-End Flow (Optional) Để test toàn bộ flow từ click → lead tracking: ```javascript theme={null} // Mở Console sau khi click vào touchpoint link li2Analytics.trackLead({ eventName: "Test Lead", customerExternalId: "test-user-123", customerEmail: "test@example.com", customerName: "Test User" }); ``` Check **Network** tab - nên thấy POST request đến API endpoint với status **200 OK**. **Lưu ý**: Test lead này sẽ được ghi nhận thật trong database. Hiện tại Li2 chưa hỗ trợ delete conversion events qua UI. Khuyến nghị: * Sử dụng `eventName: "Test ..."` để dễ phân biệt với real data * Hoặc test trên development/staging environment trước khi deploy production *** ## Hoàn Tất! 🎉 Bạn đã cài đặt xong conversion tracking! Các bước tiếp theo: Học cách track khi khách hàng sign up hoặc thể hiện quan tâm Học cách track revenue khi khách hàng mua hàng Cài đặt conversion tracking qua Google Tag Manager Cấu hình conversion goals và custom events Li2 Swift SDK: API conversion tự gắn về deep-link match (`trackAttributedSale`, `identify`) *** ## Troubleshooting **Nguyên nhân**: Organization chưa có Premium plan. **Cách fix**: 1. Vào **Settings → Billing** 2. Upgrade lên Premium hoặc cao hơn 3. Hoặc start Premium Trial để test **Giải pháp**: * SDK đã được optimize với `defer` loading - không block page render * CDN global distribution đảm bảo latency thấp * Minified bundle size \< 10KB **Nếu vẫn lo ngại**: Load SDK async sau khi page interactive: ```javascript theme={null} window.addEventListener('load', function() { // Inject SDK script here }); ``` Trang này nói về **Li2 Analytics SDK (web/JavaScript)** — không chạy trong app native. * **App iOS có deep link**: dùng **Li2 Swift SDK** (`0.2.0+`). Nó có API conversion định kiểu riêng (`trackDirectLead` / `trackAttributedLead` / `trackAttributedSale` / `identify`) tự gắn về deep-link match qua `Li2.lastClickId` — không cần truyền click ID thủ công. Xem [Đo lường chuyển đổi trong Tích Hợp App](/vi/deep-links/mobile-integration#đo-lường-chuyển-đổi-conversion-tracking). * **Android / nền tảng khác**, hoặc khi không có deep link: dùng **server-side tracking** với secret key (`li2_sk_...`) và truyền `clickId` thủ công. Xem [Events Tracking - Server-side](./events#cách-track-lead). Trong **Touch-Points list**, tìm icon 📊 bên cạnh touchpoint name. Icon này chỉ xuất hiện khi conversion tracking đã được enabled. Hoặc filter touchpoints với **Advanced Filters → Conversion Tracking = Enabled**. *** ## Best Practices **1. Enable tracking có chọn lọc**: Chỉ enable cho touchpoints quan trọng để data sạch và dễ analyze. **2. Test trong development**: Luôn add `localhost` vào allowed hostnames khi develop, remove khi deploy production. **3. Monitor setup**: Check Analytics dashboard thường xuyên trong tuần đầu sau setup để catch issues sớm. **4. Document your setup**: Ghi lại publishable key, allowed hostnames ở đâu để team khác có thể maintain. **5. Secure your keys**: Publishable key an toàn cho client, nhưng KHÔNG commit secret keys vào Git.