Bạn đã có một Web App hoạt động ổn định trên mobile và tablet, nhưng muốn tiếp cận nhiều người dùng hơn, đặc biệt trên nền tảng Zalo? Việc chuyển đổi nhanh Web App có sẵn thành Zalo Mini App chính là giải pháp tối ưu giúp bạn tiết kiệm thời gian, chi phí và rút ngắn quá trình triển khai. Thay vì phát triển Mini App từ đầu, bạn hoàn toàn có thể tái sử dụng phần lớn giao diện và logic hiện có để tích hợp vào hệ sinh thái Zalo – nơi hàng triệu người dùng truy cập mỗi ngày. Trong bài viết này, chúng tôi sẽ hướng dẫn bạn từng bước thực hiện việc chuyển đổi hiệu quả và chuyên nghiệp.
1. Yêu cầu và bước chuẩn bị
Trước tiên, điều kiện tiên quyết là bạn đã có một Web App hoạt động ổn định với trải nghiệm người dùng tốt trên thiết bị di động và máy tính bảng.
Tiếp theo, bạn cần tạo một Mini App mới trên nền tảng Zalo. Hãy chọn tên gọi ấn tượng, logo rõ ràng và ảnh bìa chỉn chu để tạo ấn tượng đầu tiên khi người dùng tìm thấy bạn trên Zalo Mini App Store.
Nếu bạn chưa biết cách tạo Mini App, có thể tham khảo hướng dẫn chi tiết từ tài liệu chính thức tại miniapp.vn hoặc trung tâm tài liệu của Zalo.
Sau khi đã hoàn tất bước chuẩn bị, hãy cùng bắt đầu với những lưu ý kỹ thuật quan trọng khi tích hợp Mini App vào project sẵn có.
2. Phía client
1. Khởi tạo Zalo Mini App trên project Web App có sẵn
Để tích hợp Mini App vào Web App hiện tại, bạn cần sử dụng bộ công cụ dành cho nhà phát triển: zmp-cli. Hướng dẫn cài đặt và sử dụng công cụ này có thể tìm thấy trong tài liệu Zalo Mini App SDK.
Sau khi đã cài đặt thành công zmp-cli, mở Terminal và chuyển đến thư mục gốc (root folder) của project web app, sau đó khởi tạo project Mini App bằng cách chạy lệnh:
Ví dụ cần chuyển project my-app đặt tại ~/miniapp/my-app thành Mini App:
Sau khi đăng nhập thành công chọn Using ZMP to deploy only:
Giao diện sau khi deploy thành công:
Lúc này project của bạn sẽ được tạo thêm file .env và app-config.json tại root folder
File .env: chứa các biến môi trường cần thiết phục vụ cho việc deploy File app-config.json: được dùng để cấu hình chung cho Zalo Mini App.
Trong đó file app-config.json có cấu trúc như sau:
Trong file cấu hình của Mini App, phần app đóng vai trò quan trọng trong việc định hình giao diện cơ bản. Tại đây, bạn sẽ thấy một loạt các trường như:
headerTitle,headerColor,textColor,statusBar,actionBarHidden,leftButton
Đây là những tham số dùng để tùy chỉnh thanh trạng thái (Status Bar) và thanh điều hướng (Navigation Bar) trên Zalo Mini App, giúp bạn tạo giao diện nhất quán và thân thiện với người dùng.
Ngoài ra, một số trường khác như listCSS, listSyncJS, listAsyncJS cũng đóng vai trò quan trọng trong việc đồng bộ và tối ưu hóa tài nguyên — chúng sẽ được trình bày chi tiết ở phần dưới. (Bạn có thể xem thêm hướng dẫn chi tiết tại tài liệu chính thức nếu cần.)
2. Cập nhật lại root element selector
Một điểm quan trọng mà nhiều lập trình viên dễ bỏ qua khi tích hợp Mini App: sau khi deploy, Mini App sẽ không dùng file index.html gốc của bạn, mà sử dụng index mặc định do nền tảng Zalo Mini App cung cấp.
Trong index này, root element mặc định sẽ có id="app". Vì vậy, nếu ứng dụng Web của bạn sử dụng root hoặc bất kỳ ID nào khác, bạn cần chỉnh lại selector để khớp với ID "app" – nếu không, toàn bộ app sẽ không được mount đúng.
Ví dụ với React 18:
3. Cấu hình module bundler
Một số vấn đề thường gặp đối với project tự build và deploy lên Zalo Mini App là không tải được các static files hay các module khi sử dụng code splitting, nguyên nhân có thể do public path chưa đúng. Bởi lẽ source code sau khi build sẽ được đưa lên cdn của Zalo, đặt trong folder tương ứng với Mini App Id, version, khi build bằng dev tools của Zalo Mini App, public path đã được config sẵn tương ứng với từng version của app, vậy đối với các project tự cấu hình build thì giải quyết thế nào?
- Đối với project sử dụng Vite module bundler, đơn giản chỉ cần set base=”./” trong file config
Đối với Project đóng gói bằng webpack thì có chút khác biệt, cần chỉ rõ version của Mini App để chỉ đúng thư mục chứa các assets ứng với version, có thể sử dụng global variable __webpack_public_path__ của webpack để giải quyết vấn đề này, lấy version của Mini App đang chạy tại window.APP_VERSION, xem ví dụ sau:
4. Vấn đề không tải được module khi sử dụng dynamic import khi đóng gói bằng Vite trên iOS
Khi gặp lỗi không tải được trang khi sử dụng dynamic import trên iOS với project đóng gói bằng Vite, có thể tắt option polyfillModulePreload tại file config để khắc phục, như sau:
5. Vấn đề về Router
Đối với project tự xử lý vấn đề routing của app, có thể gặp lỗi không tải được trang chủ hay khi navigate không tải được trang, nguyên nhân có thể do base URL mặc định không đúng, cần điều chỉnh lại thành /zapps/[APP_ID]
Ví dụ sử dụng react-router:
Tương tự với project Angular có thể config lại APP_BASE_HREF
6. Lưu ý về xác thực thông tin người dùng khi gọi API
Đổi với một số Mini App cần xác thực thông tin người dùng sau khi lấy được thông tin người dùng thông qua API của Zalo, bạn có thể định danh user khi request tới API bằng 1 trong những cách sau:
- Sử dụng trực tiếp Access Token.
- Tạo ra Authentication Token riêng cho hệ thống của bạn, chúng tôi khuyến nghị bạn nên sử dụng JWT – JSON Web Token.Với tất cả ứng dụng Zalo Mini App, các API mặc định của trình duyệt sau sẽ không được hỗ trợ:
- LocalStorage
- SessionStorage
- Cookie Vì vậy vui lòng sử dụng Header thay cho Cookie để truyền thông tin xác thực người dùng lên Server của bạn.
7. Khai báo các assets cần thiết khi tải trang tại app-config.json
Như đã đề cập ở trên, sau khi deploy, Mini App sẽ sử dụng file index do hệ thống của Zalo Mini App tạo ra, nên cần liệt kê các files cần thiết để khởi tạo app, như css, js module,… bạn có thể xem các file cần thiết được khai báo tại file index.html được build ra trong chính project của bạn và liệt kê trong app-config tại các trường: listCSS, listSyncJS, listAsyncJS, như dưới đây
Ví dụ sau khi build hoàn tất, build folder (ở trong trường hợp này là dist) có cấu trúc như sau:
File index.html có nội dung như sau:
Quan sát file index.html sau khi build phía trên, nhận thấy index cần tải script ./assets/index.cafa2549.module.js và css file ./assets/index.3fce1f81.css, vậy ta cần khai báo đường dẫn tới 2 file này vào các trường tương ứng trong app-config.json như sau:
3. Phía Server
Do ứng dụng của bạn chạy trên hệ thống domain của hệ thống Zalo, vì vậy để gọi được API, yêu cầu Server của bạn trả thêm Header Access-Control-Allow-Origin như sau (Ví dụ với Nodejs)
4. Deploy
Sau kiểm tra lại các lưu ý nêu trên và tiến hành buid, bạn đã thể deploy Mini App của mình, rất đơn giản với lệnh
Chọn Deploy your existing project, điền build folder tương ứng
Việc chuyển đổi nhanh Web App có sẵn thành Zalo Mini App không chỉ giúp bạn tận dụng tối đa tài nguyên hiện có mà còn mở ra cơ hội tiếp cận tệp người dùng khổng lồ từ Zalo với chi phí cực thấp. Với một vài bước chuẩn bị đơn giản và lưu ý kỹ thuật quan trọng, bạn có thể nhanh chóng triển khai Mini App, duy trì trải nghiệm người dùng mượt mà và bắt đầu chiến dịch số hóa doanh nghiệp ngay hôm nay. Nếu bạn muốn tăng tốc quá trình này, hãy cân nhắc sử dụng các nền tảng hỗ trợ như MiniApp.vn để tối ưu hóa thời gian và hiệu suất triển khai.
Liên hệ để được tư vấn:
- Hotline: 0901 888 903
- Website: https://miniapp.vn/
- Địa chỉ: Tòa nhà Thanh Long, 456 Xô Viết Nghệ Tĩnh, phường 25, Quận Bình Thạnh, Hồ Chí Minh
