Cấu Hình Zalo Mini App

Cập nhật lần cuối: 27/05/2022

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 navigation 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 Navigation bar
headerColor	string			Màu của NavigationBar (Hex code - ví dụ: #ffffff). Nếu để trống, NavigationBar sẽ chuyển sang dạng trong suốt.
leftButton	string		none	Nhận 1 trong các giá trị sau: "none": không hiển thị. "back": hiển thị nút trở lại. "home": hiển thị nút trang chủ. "both": hiển thị cả 2.
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
statusBarColor	string			Màu của thanh status bar khi thanh điều hướng bị ẩn, có giá trị hợp lệ là màu thập lục phân, ví dụ #000000
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": "#ffffff",
    "leftButton": "back",
    "textColor": "white",
    "statusBarColor": "#ffffff"
  },
  "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 "headerColor": "" để 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, statusBarColor 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"
    },
    "statusBarColor": {
      "light": "#ffffff",
      "dark": "#000000"
    }
  },
  ...
}

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"
    }
  },
  ...
}