Plugin Version: 1.3.0

Tác giả: growstep.vn / bayvui.net

================================================================

TỔNG QUAN

Plugin tạo form báo phí bảo hiểm du lịch Liberty ngay trên website
WordPress. Khách chọn thời gian / chương trình / khu vực → giá hiển
thị tức thì. Khi khách để lại SĐT, thông tin được lưu vào database
và gửi thông báo qua Telegram về cho bạn.

Tính năng chính:
• Hiển thị bảng giá Liberty theo 14 mốc thời gian (1–73 ngày)
• 3 chương trình: Classic / Executive / Premier
• 3 khu vực: Đông Nam Á / Châu Á–TBD / Toàn cầu
• Lưu lead vào DB WordPress (bảng riêng)
• Gửi thông báo Telegram ngay khi có lead mới
• Chống giả mạo form (CSRF nonce)
• Xem danh sách lead trong trang Admin

================================================================

PHẦN 1 – CÀI ĐẶT PLUGIN

Bước 1: Upload file plugin
a) Vào WordPress Admin → Plugins → Add New → Upload Plugin
b) Chọn file .php của plugin (hoặc file .zip nếu đã đóng gói)
c) Nhấn Install Now → Activate

— HOẶC —

a) Copy file .php vào thư mục:
/wp-content/plugins/liberty-travel-quote/
b) Vào WordPress Admin → Plugins → tìm “Liberty Travel Quote”
c) Nhấn Activate

Bước 2: Kiểm tra bảng DB
Khi plugin được kích hoạt lần đầu, nó tự động tạo bảng:
{prefix}_liberty_travel_leads
trong database WordPress của bạn. Không cần làm gì thêm.

================================================================

PHẦN 2 – CẤU HÌNH TELEGRAM (BẮT BUỘC ĐỂ NHẬN THÔNG BÁO)

Bước 1: Tạo Telegram Bot
a) Mở Telegram → tìm @BotFather → gõ /newbot
b) Đặt tên cho bot (VD: BaoHiemDuLich Bot)
c) BotFather sẽ cấp cho bạn một TOKEN dạng:
123456789:ABCDEF_xxxxxxxxxxxxxxxxxxxx
d) Lưu token này lại.

Bước 2: Lấy Chat ID
a) Tạo nhóm Telegram (hoặc dùng chat cá nhân)
b) Thêm bot vào nhóm đó
c) Gửi một tin nhắn bất kỳ trong nhóm
d) Truy cập URL sau trên trình duyệt (thay YOUR_TOKEN):
https://api.telegram.org/botYOUR_TOKEN/getUpdates
e) Tìm trường “chat” → “id” trong kết quả JSON
• Chat ID nhóm thường có dấu âm, VD: -1001234567890
• Chat ID cá nhân là số dương, VD: 987654321

Bước 3: Thêm vào wp-config.php
Mở file wp-config.php (thư mục gốc WordPress), thêm 2 dòng
VÀO TRƯỚC dòng “/* That’s all, stop editing! */”:

define('TELEGRAM_BOT_TOKEN', '123456789:ABCDEF_your_bot_token');
define('TELEGRAM_CHAT_ID',   '-1001234567890');

⚠ Thay giá trị bằng token và chat ID thực của bạn.
⚠ Dùng dấu nháy đơn ‘ ‘ bao quanh giá trị.

================================================================

PHẦN 3 – CHÈN FORM VÀO TRANG / BÀI VIẾT

Bước 1: Tạo trang (Page) hoặc mở trang có sẵn trong WordPress

Bước 2: Thêm shortcode sau vào nội dung trang:

[liberty_travel_quote]

Bước 3: Publish / Update trang → truy cập trang đó để kiểm tra.

Form sẽ hiển thị với:
• Dropdown chọn Thời gian
• Dropdown chọn Chương trình
• Dropdown chọn Khu vực
• Giá Liberty cập nhật tức thì khi thay đổi lựa chọn
• Ô nhập Tên + SĐT → nút “Gửi thông tin tư vấn”

================================================================

PHẦN 4 – XEM DANH SÁCH LEAD TRONG ADMIN

Vào WordPress Admin → Liberty Leads (menu bên trái, icon điện thoại)

Bảng hiển thị tối đa 200 lead gần nhất với các cột:
ID | Thời gian | Chương trình | Khu vực | Phí (đ) | Tên | SĐT | Ngày tạo

Nhấn vào SĐT để gọi trực tiếp (trên thiết bị hỗ trợ tel:).

================================================================

PHẦN 5 – CÀI ĐẶT MÔI TRƯỜNG DEV / LOCALHOST

Nếu bạn chạy WordPress trên máy local (LocalWP, Valet, XAMPP…),
nonce có thể bị lỗi. Thêm dòng sau vào wp-config.php để bật chế độ
dev (bỏ kiểm tra nonce khi cùng domain):

define('LTQ_DEV_MODE', true);

⚠ QUAN TRỌNG: Xóa dòng này (hoặc đổi thành false) trước khi
đưa website lên production/live. Giữ LTQ_DEV_MODE trên môi
trường live sẽ làm giảm bảo mật form.

================================================================

PHẦN 6 – LƯU Ý VỀ PLUGIN CACHE

Nếu website dùng plugin cache (LiteSpeed Cache, WP Rocket, W3 Total
Cache…), nonce nhúng trong form có thời hạn. Cần xử lý như sau:

1) Sau khi cài đặt hoặc cập nhật plugin → xóa cache toàn bộ
2) Nếu form báo lỗi “Nonce không hợp lệ”:
→ Xóa cache trang chứa shortcode
→ Hoặc cấu hình plugin cache loại trừ trang đó khỏi cache
3) Nên cấu hình plugin cache để KHÔNG cache trang có form
(thường có tùy chọn “Excluded URLs” hoặc “Never Cache”)

================================================================

PHẦN 7 – CẤU TRÚC KỸ THUẬT (dành cho developer)

REST Endpoint:
POST /wp-json/liberty/v1/lead
Headers: Content-Type: application/json
X-WP-Nonce: {wp_rest nonce}
Body (JSON):
name – tên khách (tùy chọn)
phone – số điện thoại (bắt buộc)
duration_key – VD: “7-10ngay”
program – “classic” | “executive” | “premier”
region – “sea” | “asia” | “global”
price_vnd – số nguyên (đồng)
_wpnonce – body nonce dự phòng

Bảng DB: {prefix}_liberty_travel_leads
id, name, phone, duration_key, program, region,
price_vnd, source, created_at

Dependencies (tải từ CDN, không cần cài thêm):
• Alpine.js v3 – reactive UI
• Bootstrap 5.3.3 – giao diện form

================================================================

PHẦN 8 – XỬ LÝ SỰ CỐ THƯỜNG GẶP

Vấn đề: Form hiển thị nhưng không gửi được
→ Kiểm tra lại TELEGRAM_BOT_TOKEN và TELEGRAM_CHAT_ID trong
wp-config.php (sai token thì Telegram không nhận được, nhưng
lead vẫn lưu DB)
→ Kiểm tra Console trình duyệt (F12) để xem lỗi JS

Vấn đề: Nhận được lỗi “Nonce không hợp lệ” (403)
→ Xóa cache trang
→ Nếu dev local: thêm define(‘LTQ_DEV_MODE’, true)

Vấn đề: Lead lưu DB nhưng không nhận Telegram
→ Kiểm tra bot đã được thêm vào nhóm chưa
→ Kiểm tra Chat ID có đúng và đúng định dạng không
(nhóm thường có dấu âm -)
→ Thử gọi thủ công API Telegram trên trình duyệt để test

Vấn đề: Form không hiển thị đúng giao diện
→ Kiểm tra theme có conflict với Bootstrap 5 không
→ Có thể tắt enqueue Bootstrap trong plugin nếu theme đã có sẵn

Vấn đề: Bảng Liberty Leads không xuất hiện trong Admin menu
→ Deactivate → Activate lại plugin để chạy lại on_activate()
→ Kiểm tra user có quyền manage_options không

================================================================

Website: growstep.vn