Nhiều doanh nghiệp đã có sẵn Web App hoạt động tốt trên điện thoại và máy tính bảng nhưng chưa muốn đầu tư ngay một dự án Zalo Mini App. Trong trường hợp này, chuyển đổi Web App có sẵn thành Zalo Mini App là giải pháp phù hợp để tiết kiệm thời gian phát triển và tối ưu chi phí. Tuy nhiên, để Web App hoạt động ổn định trong môi trường Zalo Mini App, nhà phát triển cần thực hiện một số cấu hình quan trọng. Trong bài viết này, Abenla sẽ hướng dẫn chi tiết cách chuyển đổi.

1. Có nên chuyển đổi Web App có sẵn thành Zalo Mini App?

Chuyển đổi Web App có sẵn thành Zalo Mini App phù hợp trong các trường hợp như:

Doanh nghiệp đã có Web App tối ưu tốt cho thiết bị di động.
Cần triển khai Mini App nhanh để phục vụ chiến dịch hoặc thử nghiệm thị trường.
Muốn tiết kiệm chi phí trước khi đầu tư bản Mini App hoàn chỉnh.
Cần mở rộng thêm điểm chạm khách hàng trên Zalo.
Muốn tận dụng Web App hiện có để triển khai tạm thời trong giai đoạn phát triển hệ thống mới.

Tuy nhiên, Web App cần có giao diện responsive tốt trên mobile và tablet. Nếu giao diện hiện tại chỉ phù hợp với máy tính, doanh nghiệp nên tối ưu lại trải nghiệm trước khi chuyển đổi.

2. Chuẩn bị trước khi chuyển đổi Web App

Trước khi bắt đầu, doanh nghiệp và đội ngũ phát triển cần chuẩn bị một số yếu tố cơ bản:

Một project Web App đang hoạt động ổn định.
Giao diện tối ưu cho điện thoại và máy tính bảng.
Zalo Mini App đã được tạo trên hệ thống.
Tên Mini App, logo và ảnh bìa phù hợp.
Công cụ phát triển Zalo Mini App, đặc biệt là zmp-cli.
Quyền truy cập vào source code và thư mục build của Web App.

Việc chuẩn bị đầy đủ ngay từ đầu giúp quá trình chuyển đổi diễn ra thuận lợi hơn, đồng thời hạn chế lỗi khi deploy phiên bản thử nghiệm.

3. Khởi tạo Zalo Mini App trên project Web App có sẵn

Sau khi cài đặt công cụ zmp-cli, hãy di chuyển đến thư mục gốc của project Web App và chạy lệnh:

zmp init

Ví dụ, nếu project có tên my-app được đặt tại thư mục ~/miniapp/my-app, bạn cần di chuyển đến đúng thư mục project trước khi chạy lệnh khởi tạo.

Sau khi đăng nhập thành công, hãy chọn tùy chọn:

Using ZMP to deploy only

Khi quá trình khởi tạo hoàn tất, project sẽ có thêm hai file quan trọng tại thư mục gốc:

.env: Chứa các biến môi trường cần thiết cho quá trình deploy.
app-config.json: Dùng để cấu hình chung cho Zalo Mini App.

4. Cấu hình file app-config.json

Sau khi khởi tạo, file app-config.json sẽ được thêm vào project. Đây là nơi cấu hình một số thông tin liên quan đến giao diện và tài nguyên của Mini App.

Ví dụ cấu trúc cơ bản:

{

“app”: {

“title”: “My App”,

“headerColor”: “#1843EF”,

“headerTitle”: “My App Title”,

“textColor”: “white”,

“leftButton”: “back”,

“statusBar”: “normal”,

“actionBarHidden”: false

“debug”: false,

“listCSS”: [],

“listSyncJS”: [],

“listAsyncJS”: []

}

Trong đó, nhóm app được dùng để cấu hình thanh điều hướng và trạng thái hiển thị của Mini App.

Một số trường thường được sử dụng gồm:

title: Tên ứng dụng.
headerTitle: Tiêu đề trên thanh điều hướng.
headerColor: Màu nền thanh điều hướng.
textColor: Màu chữ hiển thị.
leftButton: Cấu hình nút quay lại.
statusBar: Trạng thái thanh trạng thái.
actionBarHidden: Ẩn hoặc hiển thị action bar.
listCSS: Danh sách file CSS cần tải.
listSyncJS: Danh sách file JavaScript tải đồng bộ.
listAsyncJS: Danh sách file JavaScript tải bất đồng bộ.

5. Cập nhật root element selector

Sau khi deploy, Zalo Mini App sử dụng file index do hệ thống tạo thay vì file index gốc từ project Web App.

Root element mặc định trong môi trường Zalo Mini App có ID là app. Vì vậy, nếu Web App hiện tại đang sử dụng một ID khác, nhà phát triển cần cập nhật lại.

Ví dụ với React 18:

const root = createRoot(document.getElementById(“app”));

root.render(React.createElement(App));

Nếu không cập nhật root element đúng, Mini App có thể không render giao diện hoặc chỉ hiển thị màn hình trống sau khi deploy.

6. Cấu hình Vite khi chuyển Web App thành Zalo Mini App

Một lỗi phổ biến khi deploy Web App lên Zalo Mini App là không tải được static files hoặc module được tách bằng code splitting. Nguyên nhân thường xuất phát từ cấu hình public path chưa phù hợp.

Với project sử dụng Vite, cần thiết lập base: “./” trong file cấu hình.

Ví dụ file vite.config.js:

import { defineConfig } from “vite”;

import react from “@vitejs/plugin-react”;

export default defineConfig({

plugins: [react()],

base: “./”,

build: {

rollupOptions: {

output: {

entryFileNames: “assets/[name].[hash].module.js”,

chunkFileNames: “assets/[name].[hash].module.js”,

});

Cấu hình này giúp Mini App tải đúng các file tài nguyên sau khi source code được đưa lên CDN của Zalo.

7. Cấu hình Webpack cho Zalo Mini App

Với project sử dụng Webpack, cần chỉ rõ đúng đường dẫn chứa assets tương ứng với phiên bản Mini App đang chạy.

Có thể sử dụng biến toàn cục __webpack_public_path__ và lấy version của Mini App từ window.APP_VERSION.

Ví dụ:

import React from “react”;

import { createRoot } from “react-dom/client”;

import App from “./App”;

/* eslint-disable */

__webpack_public_path__ = `./${window.APP_VERSION}/`;

const root = createRoot(document.getElementById(“app”));

root.render(React.createElement(App));

Thiết lập này giúp Webpack tìm đúng thư mục assets của phiên bản hiện tại khi Mini App chạy trên Zalo.

8. Khắc phục lỗi dynamic import trên iOS với Vite

Một số project sử dụng dynamic import có thể gặp lỗi không tải được trang trên iOS khi đóng gói bằng Vite.

Trong trường hợp này, có thể tắt polyfillModulePreload trong cấu hình build:

import { defineConfig } from “vite”;

import react from “@vitejs/plugin-react”;

export default defineConfig({

plugins: [react()],

base: “./”,

build: {

polyfillModulePreload: false,

rollupOptions: {

output: {

entryFileNames: “assets/[name].[hash].module.js”,

chunkFileNames: “assets/[name].[hash].module.js”,

});

Sau khi cập nhật, hãy build lại project và kiểm tra Mini App trên thiết bị iOS trước khi phát hành.

9. Cấu hình Router cho Web App

Các Web App tự xử lý routing có thể gặp lỗi không tải được trang chủ hoặc lỗi khi chuyển trang trên Zalo Mini App. Nguyên nhân thường do base URL mặc định chưa phù hợp với môi trường Mini App.

Base URL cần được điều chỉnh theo cấu trúc:

/zapps/[ZALO_MINI_APP_ID]

Ví dụ với React Router

Ví dụ với Reach Router

Ví dụ với Angular

import { Component, NgModule } from “@angular/core”;

import { APP_BASE_HREF } from “@angular/common”;

@NgModule({

providers: [

{ provide: APP_BASE_HREF, useValue: “/zapps/[ZALO_MINI_APP_ID]” },

})

class AppModule {}

Việc cấu hình đúng Router sẽ giúp người dùng có thể mở trang chủ, chuyển trang và quay lại các màn hình trong Mini App ổn định hơn.

10. Lưu ý khi xác thực người dùng qua API

Một số Mini App cần xác thực người dùng sau khi lấy thông tin từ Zalo. Nhà phát triển có thể xác thực theo hai cách:

Sử dụng trực tiếp Access Token.
Tạo Authentication Token riêng cho hệ thống, trong đó JWT là phương án thường được khuyến nghị.

Zalo Mini App không hỗ trợ các cơ chế lưu trữ mặc định của trình duyệt như:

LocalStorage.
SessionStorage.
Cookie.

Vì vậy, thay vì sử dụng Cookie, nhà phát triển nên truyền thông tin xác thực qua Header khi gửi request đến server.

Ví dụ:

const API_URL = “https://yourapidomain.com/”;

fetch(API_URL, {

method: “POST”,

headers: {

“Content-Type”: “application/x-www-form-urlencoded”,

“Authorization”: “Bearer {Your JWT here}”

body: {}

});

Cách triển khai này giúp hệ thống xác thực người dùng phù hợp hơn với môi trường Zalo Mini App.

11. Khai báo CSS và JavaScript trong app-config.json

Sau khi deploy, Mini App không sử dụng trực tiếp file index.html được tạo từ project Web App. Vì vậy, nhà phát triển cần khai báo các file CSS và JavaScript cần thiết trong app-config.json.

Ví dụ, sau khi build project Vite, file index.html có thể chứa:

Khi đó, cần đưa các file này vào app-config.json:

{

“app”: {

“title”: “My App”,

“headerColor”: “#ffffff”,

“leftButton”: “back”,

“textColor”: “white”,

“statusBarColor”: “#ffffff”

“listCSS”: [

“assets/index.3fce1f81.css”

“listSyncJS”: [

“assets/index.cafa2549.module.js”

“listAsyncJS”: []

}

Nhà phát triển nên kiểm tra file index.html sau khi build để xác định chính xác các file CSS và JavaScript cần khai báo.

12. Cấu hình CORS ở phía server

Khi Web App được chuyển thành Zalo Mini App, ứng dụng sẽ chạy trên domain của hệ thống Zalo. Do đó, server của doanh nghiệp cần cấu hình CORS phù hợp để cho phép request từ Mini App.

Origin cần được cho phép là:

https://h5.zdn.vn

Ví dụ cấu hình với Node.js và Express:

var express = require(“express”);

var cors = require(“cors”);

var app = express();

var corsOptions = {

origin: “https://h5.zdn.vn”,

};

app.use(cors(corsOptions));

Nếu không cấu hình CORS đúng, Mini App có thể gọi API thất bại dù request vẫn hoạt động bình thường trên Postman hoặc môi trường localhost.

13. Deploy Web App lên Zalo Mini App

Sau khi kiểm tra source code, build project và hoàn tất các cấu hình cần thiết, nhà phát triển có thể deploy bằng lệnh:

zmp deploy

Sau đó, chọn tùy chọn:

Deploy your existing project

Tiếp theo, nhập đường dẫn đến thư mục build của Web App, chẳng hạn như dist hoặc build tùy theo framework đang sử dụng.

Khi quá trình deploy hoàn tất, hệ thống sẽ hiển thị QR Code để Nhà phát triển quét và trải nghiệm thử Mini App trên ứng dụng Zalo.

14. Checklist trước khi phát hành Mini App

Trước khi gửi xét duyệt hoặc phát hành phiên bản chính thức, Nhà phát triển nên kiểm tra:

Web App đã tối ưu tốt trên điện thoại và tablet.
Root element đã sử dụng ID app.
Cấu hình base hoặc public path đã đúng.
Router đã thiết lập theo đường dẫn /zapps/[ZALO_MINI_APP_ID].
File CSS và JavaScript đã khai báo trong app-config.json.
Dynamic import hoạt động tốt trên iOS nếu sử dụng Vite.
Server đã cấu hình CORS cho https://h5.zdn.vn.
Cơ chế xác thực API không phụ thuộc vào LocalStorage, SessionStorage hoặc Cookie.
Luồng điều hướng, hiển thị hình ảnh và tải tài nguyên hoạt động ổn định.
Mini App đã được kiểm tra trên thiết bị thật trước khi phát hành.

Chuyển đổi Web App có sẵn thành Zalo Mini App là giải pháp giúp doanh nghiệp nhanh chóng tiếp cận người dùng trên Zalo mà không cần xây dựng ứng dụng hoàn toàn từ đầu. Tuy nhiên, để Mini App vận hành ổn định, đội ngũ phát triển cần chú ý đến cấu hình root element, module bundler, Router, static files, API xác thực và CORS phía server. Abenla hy vọng hướng dẫn này giúp doanh nghiệp và đội ngũ kỹ thuật chủ động hơn khi chuyển đổi Web App thành Zalo Mini App.

Xem thêm:

Thông tin liên hệ:

Công ty TNHH ABENLA