Tracking - Code tích hợp

Trang này để làm gì

Hướng dẫn cho người làm web: nhúng SDK Tracking vào website, gửi lượt xem trang, gắn nhận diện khách (identify), kiểm tra mã đã chạy và xử lý lỗi thường gặp. Phần lớn công việc chỉ là dán một đoạn mã; riêng bước identify cần lập trình viên viết thêm vài dòng.

Đường dẫn: Data Hub → Tracking → Website → nút Xem hướng dẫn

Lấy đoạn mã đã điền sẵn projectKey

Đoạn mã trên trang này dùng projectKey mẫu. Bản đã điền đúng projectKey của từng website nằm ở trang chi tiết project, tab Cài đặt SDK, có nút Sao chép.

Bước 1 - Tạo project

Trong trang Tracking, bấm Tạo project và khai báo:

• Tên project: tên gợi nhớ, ví dụ "Website bán hàng".
• Môi trường: chọn live cho website thật, test để chạy thử. Không đổi được sau khi tạo.
• Domain được phép (Allowed origins): nhập đúng tên miền website sẽ gắn mã, kèm http:// hoặc https://, ví dụ https://shop.example.com. Bắt buộc ít nhất một domain; website ngoài danh sách sẽ bị từ chối.

Sau khi lưu, hệ thống sinh projectKey dạng pk_live_… hoặc pk_test_…. Xem thêm ở Tracking - Cài Tracking lên website.

Bước 2 - Nhúng mã vào website

Dán đoạn mã sau vào trong thẻ <head> của mọi trang trên website, hoặc thêm qua Google Tag Manager. Website làm trên nền tảng có sẵn (WordPress, Haravan, Sapo...) thường có ô chèn mã trong phần cài đặt giao diện. Thay pk_live_xxxxxxxx bằng projectKey của project.

<script async crossorigin="anonymous" src="https://cdn.jsdelivr.net/npm/@cnv-vn/track@latest/dist/cnv-track.min.js"></script>
<script>
  window.cnvQ = window.cnvQ || [];
  cnvQ.push(['init', 'pk_live_xxxxxxxx']);
</script>

Nhúng xong là SDK tự gửi lượt xem trang, kèm nguồn khách, UTM và thiết bị. Không cần thêm dòng code nào.

Bước 3 - Lượt xem trang và sự kiện

• Lượt xem trang được gửi tự động khi SDK khởi tạo ở Bước 2.
• Lượt bấm nút không cần viết code: tạo click rule ở tab Button tracking của project, SDK tự gửi sự kiện clicked khi khách bấm đúng nút. Xem Tracking - Button tracking.
• Nền tảng chỉ nhận những tên sự kiện đã bật cho từng project (mặc định chỉ có clicked). Gọi cnvQ.push(["track", "<tên khác>"]) sẽ bị từ chối với lỗi event_not_allowed. Cần thêm tên sự kiện riêng thì liên hệ CNV để bật cho project.

Website dạng một trang (SPA)

Website viết bằng React, Vue, Angular... không tải lại trang khi khách chuyển trang. Gọi cnvQ.push(["page"]) sau mỗi lần đổi route, nếu không hệ thống chỉ thấy lượt xem đầu tiên của phiên.

Bước 4 - Nhận diện khách hàng (identify)

Đây là phần lập trình viên phải tự viết. Gọi identify ngay khi biết khách là ai: khách đăng nhập, đặt hàng, hoặc gửi form để lại thông tin. Không gọi thì mọi hoạt động chỉ được ghi nhận là khách ẩn danh: vẫn có số liệu, nhưng không gắn được vào hồ sơ khách nào. Email và số điện thoại được mã hoá theo Nghị định 13/2023.

// `user` = khách ĐANG đăng nhập, lấy từ hệ thống của bạn (session / API / template).
// Đừng để nguyên giá trị mẫu - mọi khách sẽ bị ghi nhận là cùng một người.
cnvQ.push(['identify', user.id, {
  email: user.email,    // email HOẶC phone: khoá nối vào hồ sơ khách hàng
  phone: user.phone,
  name: user.fullName   // tuỳ chọn
}]);

// Khi khách ĐĂNG XUẤT - thiếu dòng này, người dùng máy sau bị tính là cùng khách.
cnvQ.push(['reset']);

Các dòng bắt đầu bằng // là chú thích giải thích, không phải lệnh cần chạy.

Ý nghĩa từng tham số

Tham số	Bắt buộc?	Phải truyền giá trị gì
userId (tham số thứ hai)	Bắt buộc	Mã của chính khách đó trong hệ thống của bạn (id tài khoản, mã khách hàng...). Phải là chuỗi khác rỗng và khác nhau giữa các khách. Truyền rỗng hoặc không phải chuỗi thì SDK bỏ qua lệnh, không gửi gì và không báo lỗi.
email / phone	Cần ít nhất 1	Khoá để nối phiên web với hồ sơ khách trên CDP: nền tảng tra khách theo email / số điện thoại, không theo userId của bạn. Thiếu cả hai thì sự kiện vẫn được ghi nhưng không gắn vào khách nào.
name	Tuỳ chọn	Tên hiển thị. Có thể dùng firstName và lastName nếu hệ thống của bạn lưu tách riêng.
Trường khác	Tuỳ chọn	Thêm trường riêng (hạng thẻ, ngày đăng ký, nhóm khách...) để dùng khi phân khúc. Không gửi mật khẩu, số thẻ ngân hàng hay mã OTP.

identify làm được gì

• Nối cả hành trình trước lúc đăng nhập: những trang khách đã xem, nút khách đã bấm trên cùng trình duyệt được gắn về đúng khách đó.
• Chỉ cần gọi một lần cho mỗi lần đăng nhập. SDK ghi nhớ danh tính trong cookie và localStorage, mọi sự kiện sau tự mang theo, không cần gọi lại ở từng trang.
• Gọi lại nhiều lần là an toàn: thông tin được gộp thêm, chỉ trường trùng tên mới bị ghi đè bằng giá trị mới.
• Sau khi nối được, khách được tính vào ô Khách đã nhận diện ở báo cáo tracking và hoạt động web hiện trong hồ sơ Customer 360.

Dễ sai ở đâu - sai thì không có thông báo lỗi nào

• Copy nguyên đoạn mã mà không thay biến: mọi khách mang cùng một danh tính, ô Khách đã nhận diện mãi hiện 1.
• Chỉ truyền userId, không kèm email hay số điện thoại: không nối được vào hồ sơ nào, khách vẫn nằm ngoài Customer 360.
• Khách chưa từng có hồ sơ trên CDP (chưa mua, chưa đăng ký): chưa nối được ngay lúc gọi; hệ thống nối bù sau khi hồ sơ khách được tạo.
• Gọi identify trước dòng init: SDK ghi nhớ danh tính nhưng không gửi sự kiện nào. Luôn đặt sau đoạn mã ở Bước 2.
• Không gọi reset khi khách đăng xuất: người dùng máy đó sau khi khách đăng xuất bị tính là cùng một khách. Lưu ý nhất với máy dùng chung tại cửa hàng.

Kiểm nhanh: mở project, tab Tổng quan, xem bước Gắn danh tính khách (identify) trong Các bước cài đặt. Dòng "Có gọi identify nhưng chưa khớp được khách hàng nào" nghĩa là đoạn mã đang chạy nhưng thiếu email / số điện thoại.

Kiểm tra hoạt động

1. Xem request trên trình duyệt Mở website, bật DevTools → tab Network, lọc theo js/v1. Bạn sẽ thấy request POST tới /js/v1/batch trả mã 2xx.
2. Thử trên project test Dùng project môi trường test khi đang thử nghiệm để không lẫn vào dữ liệu thật.
3. Xem dữ liệu trên CDP Sau vài phút, mở project, tab Tổng quan: Các bước cài đặt tự đánh dấu theo dữ liệu thật. Bấm Kiểm tra lại nếu vừa cài xong.

Lỗi thường gặp

Hiện tượng	Nguyên nhân & cách xử lý
Lỗi origin_not_allowed	Domain website chưa có trong Allowed origins. Thêm đúng domain (kèm http/https) vào project.
Lỗi event_not_allowed	Tên sự kiện chưa được bật cho project. Mặc định nền tảng chỉ nhận clicked (qua Button tracking), cùng với identify và lượt xem trang. Liên hệ CNV nếu cần bật thêm tên sự kiện khác.
Lỗi 401 / invalid key	projectKey sai hoặc đã bị đổi (Đổi key). Lấy key mới nhất ở trang chi tiết project và cập nhật vào mã.
Lỗi 429 / rate limit	Vượt giới hạn số lượng sự kiện. Giảm tần suất gửi hoặc liên hệ CNV để nâng hạn mức.
Sự kiện không về	Kiểm tra đã gọi cnvQ.push(["init", key]) trước khi gửi sự kiện, project không ở trạng thái Tạm dừng, và domain khớp Allowed origins.
Đã gọi identify mà khách không hiện ở Customer 360	Thiếu email / số điện thoại, khách chưa có hồ sơ trên CDP, hoặc userId vẫn là giá trị mẫu. Xem lại Bước 4.

Lưu ý bảo mật

• projectKey là khoá công khai, nằm trong mã JavaScript của website là bình thường. Dữ liệu được bảo vệ bằng danh sách domain được phép và giới hạn tần suất gửi, không phải bằng việc giữ bí mật key.
• Khi Đổi key, key cũ ngừng hoạt động ngay lập tức. Nhớ cập nhật lại mã trên website.
• Không gửi mật khẩu, số thẻ ngân hàng hay mã OTP. Email, số điện thoại chỉ gửi qua identify khi thực sự cần.

Bước tiếp theo

• Tracking - Tổng quan
• Tracking - Button tracking
• Tracking - Báo cáo