Cấu Hình Zalo Mini App

Cập nhật lần cuối: 19/07/2023

File app-config.json được dùng để cấu hình chung cho Zalo Mini App. Nội dung của file là một JSON object với các properties như sau:

Cấu hình

Property	Type	Required	Description	Minimum Version
pages	string[]	yes	Đường dẫn đến các trang trong Zalo Mini App
app	Object	yes	Cấu hình giao diện của Zalo Mini App

Pages

Được dùng để cấu hình các trang mà Zalo Mini App của bạn có. Tên của trang không cần có phần mở rộng. Nếu trang không có trong cấu hình này sẽ không thể truy cập tới.

index.jsx sẽ là trang đầu tiên của Zalo Mini App (homepage) và không cần phải config

Giả sử Project của bạn có cấu trúc như bên dưới:

Zalo Mini App
├── src
│   ├── app.js
│   ├── store.js
│   ├── components
│   │   └── app.jsx
│   ├── css
│   │   └── app.css
│   └── pages
│       ├── index.jsx
│       ├── page1.jsx
│       └── page2.jsx
├── app-config.json
└── package.json

Trong trường hợp này, bạn phải cấu hình như sau:

{
  "pages": ["/page1", "/page2"]
}

App

Được đùng để cấu hình action bar, titles của Zalo Mini App.

Property	Type	Required	Default Value	Description	Minimum Version
title	string	yes		Tên của ứng dụng
headerTitle	string			Tên sẽ hiển thị trên Action bar bar
headerColor	string			Màu của Action bar và status bar (trường hợp "statusBar": "normal") (Hex code - ví dụ: #ffffff).
leftButton	string		back	Nhận 1 trong các giá trị sau: "none": không hiển thị. "back": hiển thị nút trở lại.
textAlign	string		center	Nhận 1 trong các giá trị sau: "left": căn trái. "center": căn giữa.
textColor	string			Màu của text và icon trên thanh action bar và status bar. Nhận giá trị hợp lệ là: `white` hoặc `black`. Trên thiết bị IOS, chỉ có thể thay đổi màu icon ở thanh action bar
statusBar	string	'normal'		Kiểu hiển thị status bar. Nhận các giá trị: `normal`: mặc định `hidden`: ẩn status bar `transparent`: status bar dạng transparent	API: 2.25.0 Zalo: 23.02.01.r2
actionBarHidden	boolean		false	Ẩn Action bar	API: 2.25.0 Zalo: 23.02.01.r2
hideAndroidBottomNavigationBar	boolean		false	Ẩn Bottom Navigation trên android	API: 2.25.0 Zalo: 23.02.01.r2
hideIOSSafeAreaBottom	boolean		false	Ẩn phần Safe Area Inset Bottom trên iOS	API: 2.25.0 Zalo: 23.02.01.r2
selfControlLoading	boolean		false	Nếu giá trị là true thì màn hình Splash Loading lúc mở ứng dụng sẽ không tự động tắt, thay vào đó nhà phát triển phải gọi api closeLoading để tắt khi cần	API: 2.17.0

Ví dụ file app-config.json cấu hình Zalo Mini App:

{
  "pages": ["/page1", "/page2"],
  "app": {
    "title": "My App",
    "headerColor": "#1843EF",
    "headerTitle": "My App",
    "textColor": "white",
    "leftButton": "back",
    "textAlign": "center",
    "statusBar": "normal",
    "actionBarHidden": false,
    "hideAndroidBottomNavigationBar": true,
    "hideIOSSafeAreaBottom": true
  },
  "listCSS": ["assets/index.1b624b32.css"],
  "listSyncJS": [],
  "listAsyncJS": [
    "assets/index.7880e0ba.module.js",
    "assets/vendor.bbcbe36d.module.js"
  ]
}

Mẹo

Để có thể gắn các tương tác đặc biệt trên thanh điều hướng, ta có thể set "actionBarHidden": true để làm trong suốt thanh điều hướng mặc định của Zalo, sau đó custom lại header của ứng dụng cho phù hợp với nhu cầu:

Header mặc định của Zalo	Header tuỳ biến của ứng dụng

Zalo Theme

Bắt đầu hỗ trợ:

IOS: 22.03.01.r2

Android: 21.09.01

Để thay đổi màu của navigation bar, title, status bar icon theo theme của ứng dụng Zalo bạn có thể cấu hình headerColor, textColor như sau:

Property	Type	Description
light	string	Màu ứng với theme light
dark	string	Màu ứng với theme dark

Lưu ý: nếu phiên bản Zalo chưa hỗ trợ cấu hình theo theme thì giá trị của light sẽ được sử dụng.

Ví dụ file app-config.json cấu hình Zalo Mini App theo theme:

{
  ...
  "app": {
    "title": "My App",
    "headerColor": {
      "light": "#ffffff",
      "dark": "#000000"
    },
    "textColor": {
      "light": "black",
      "dark": "white"
    },
  },
  ...
}

Zalo Language

Bắt đầu hỗ trợ:

IOS: 22.03.01.r2

Android: 21.09.01

Để thay đổi ngôn ngữ của title theo ngôn ngữ của ứng dụng Zalo bạn có thể cấu hình headerTitle như sau:

Property	Type	Description
en	string	Ngôn ngữ ứng với tiếng Anh
vi	string	Ngôn ngữ ứng với tiếng Việt
my	string	Ngôn ngữ ứng với tiếng Myanmar (Chỉ hỗ trợ trên android )

Lưu ý: nếu phiên bản Zalo chưa hỗ trợ cấu hình theo ngôn ngữ thì giá trị của vi sẽ được sử dụng.

Ví dụ file app-config.json cấu hình Zalo Mini App theo ngôn ngữ:

{
  ...
  "app": {
    "title": "My App",
    "headerTitle": {
      "en": "My App Title",
      "vi": "App Thử Nghiệm"
    }
  },
  ...
}

Cấu hình​

Pages​

App​

Zalo Theme​

Zalo Language​