ỦY BAN NHÂN DÂN TỈNH THỪA THIÊN HUẾ -------	CỘNG HÒA XÃ HỘI CHỦ NGHĨA VIỆT NAM Độc lập - Tự do - Hạnh phúc ---------------
Số: 3071/QĐ-UBND	Thừa Thiên Huế, ngày 26 tháng 11 năm 2021

 

QUYẾT ĐỊNH

BAN HÀNH HƯỚNG DẪN KỸ THUẬT TÍCH HỢP ỨNG DỤNG VÀO ỨNG DỤNG DỊCH VỤ ĐÔ THỊ THÔNG MINH HUE-S

ỦY BAN NHÂN DÂN TỈNH THỪA THIÊN HUẾ

Căn cứ Luật Tổ chức chính quyền địa phương ngày 19 tháng 6 năm 2015; Căn cứ Luật sửa đổi, bổ sung một số điều của Luật Tổ chức Chính phủ và Luật Tổ chức chính quyền địa phương ngày 22 tháng 11 năm 2019;

Căn cứ Luật Giao dịch điện tử ngày 29 tháng 11 năm 2005;

Căn cứ Luật Công nghệ thông tin ngày 29 tháng 6 năm 2006;

Căn cứ Luật An toàn thông tin mạng ngày 19 tháng 11 năm 2015;

Căn cứ Nghị định số 64/2007/NĐ-CP ngày 10 tháng 4 năm 2007 của Chính phủ ứng dụng Công nghệ thông tin trong hoạt động của cơ quan nhà nước;

Căn cứ Nghị định số 47/2020/NĐ-CP ngày 09 tháng 4 năm 2020 của Chính phủ về quản lý, kết nối và chia sẻ dữ liệu số của cơ quan Nhà nước;

Căn cứ Nghị quyết số 12-NQ/TU ngày 12 tháng 11 năm 2021 của Hội nghị lần thứ năm Ban chấp hành Đảng bộ tỉnh khóa XVI về chuyển đổi số tỉnh Thừa Thiên Huế đến năm 2025, định hướng đến năm 2030;

Căn cứ Quyết định số 62/2021/QĐ-UBND ngày 04 tháng 10 năm 2021 của UBND tỉnh Thừa Thiên Huế về việc Ban hành Quy định Quản lý, vận hành và tích hợp ứng dụng Hue-S;

Theo đề nghị của Giám đốc Sở Thông tin và Truyền thông tỉnh tại Tờ trình số: 2462/TTr-STTTT ngày 01 tháng 11 năm 2021.

QUYẾT ĐỊNH:

Điều 1. Ban hành kèm theo Quyết định này Hướng dẫn kỹ thuật tích hợp ứng dụng vào ứng dụng dịch vụ đô thị thông minh Hue-S .

Điều 2. Hiệu lực thi hành

Quyết định này có hiệu lực thi hành kể từ ngày ký.

Điều 3. Trách nhiệm thi hành

Chánh Văn phòng Ủy ban nhân dân tỉnh; Giám đốc Sở Thông tin và Truyền thông; Thủ trưởng các Sở, ban, ngành, đoàn thể cấp tỉnh; Chủ tịch Ủy ban nhân dân các huyện, thị xã, thành phố Huế; Chủ tịch Ủy ban nhân dân các xã, phường, thị trấn; Thủ trưởng các cơ quan, đơn vị; tổ chức, cá nhân có liên quan chịu trách nhiệm thi hành Quyết định này./.

 

Nơi nhận: - Như Điều 3; - Thường vụ Tỉnh ủy; - Thường trực HĐND tỉnh; - CT và các PCT UBND tỉnh; - Báo Thừa Thiên Huế; - Đài TRT; - Cổng TTDT tỉnh; - Công báo tỉnh; - VP: CVP và các PCVP; - Lưu: VT, CN.

TM. ỦY BAN NHÂN DÂN KT. CHỦ TỊCH PHÓ CHỦ TỊCH Nguyễn Thanh Bình

 

PHỤ LỤC

HƯỚNG DẪN KỸ THUẬT
TÍCH HỢP ỨNG DỤNG VÀO HẠNG MỤC DỊCH VỤ ĐÔ THỊ THÔNG MINH HUE-S
(Kèm theo Quyết định số 3071/QĐ-UBND ngày 26/11/2021 của Ủy ban nhân dân tỉnh Thừa Thiên Huế)

I. TỔNG QUAN

1. Phạm vi đối tượng áp dụng

Tài liệu này nhằm hướng dẫn các cơ quan, đơn vị phát triển các ứng dụng sẽ tích hợp lên nền tảng ứng dụng Hue-S.

2. Các nền tảng hỗ trợ tích hợp

STT	Nền tảng ứng dụng bên thứ 3	Tích hợp được Hue-S	Ghi chú
1.	Android	Android	Nên dùng cho mục đích tích hợp các phần module native
2.	iOS	iOS	Nên dùng cho mục đích tích hợp các phần module native
3.	Flutter	Android iOS	Cần ưu tiên đóng gói ứng dụng tích hợp vào Hue-S bằng công nghệ Flutter

3. Giải thích từ viết tắt

Trong hướng dẫn này các từ ngữ sau đây được hiểu như sau:

STT	Tên viết tắt	Mô tả
1.	Hue-S	Ứng dụng dịch vụ đô thị thông minh Thừa Thiên Huế trên các nền tảng di động
2.	NSD	Người sử dụng: người thao tác với ứng dụng Hue-S trên các thiết bị di động
3.	Android	Hệ điều hành Android của hãng Google dành cho các dòng thiết bị di động
4.	IOS	Hệ điều hành iOS của hãng Apple dành cho các dòng thiết bị di động của hãng Apple
5.	appId	Package name đối với Android, Bundleld đối với iOS. Giá trị này cần được định danh duy nhất

II. MÔ HÌNH KẾT NỐI

Các ứng dụng của bên thứ 3 hoàn toàn chủ động về mặt nghiệp vụ, tuy nhiên các thông tin tương tác cơ bản sẽ được trao đổi với ứng dụng chính Hue-S thông qua các lớp thành phần có thể tương tác được, với các phương thức như:

1. Component dùng chung

2. Sự kiện (Event) để trao đổi dữ liệu

3. Tạo các kênh kết nối

Ứng dụng Hue-S (Android/iOS)

Hình 1 Mô hình thành phần ứng dụng di động Hue-S

III. QUY TRÌNH TÍCH HỢP CÁC ỨNG DỤNG VÀO NỀN TẢNG ỨNG DỤNG HUE-S

IV. ĐẶC TẢ CÁC CÁC THÀNH PHẦN KỸ THUẬT TÍCH HỢP

1. Đóng gói ứng dụng

- Ứng dụng Hue-S hỗ trợ tích hợp các ứng dụng được viết dưới dạng native cho từng hệ điều hành Android và IOS hoặc được viết bằng công nghệ đa nền tảng Flutter (Ưu tiên).

- Để tích hợp vào Hue-S thì ứng dụng cần được đóng gói thành 1 module có thể hoạt động độc lập riêng biệt cụ thể như sau:

Đối với Android thì sẽ đóng gói dưới dạng Android Library. Màn hình Activity chính của ứng dụng cần có tên là MainActivity và nằm ở thư mục mã nguồn gốc của ứng dụng. Ngoài ra ứng dụng cần cung cấp ProGuard rules cho quá trình shrink, obfuscate module.

Đối với IOS sẽ đóng gói dưới dạng Framework. ViewController chính của ứng dụng cần có tên là MainViewController.

Đối với đa nền tảng sử dụng Flutter thì cần đóng gói dưới dạng package. Root Widget của ứng dụng cần được đặt tên là MainApp

- Ứng dụng tích hợp cần phát triển dựa trên công nghệ đa nền tảng Flutter để đảm bảo hiệu năng tổng thể của ứng dụng Hue-S. Trong trường hợp ứng dụng tích hợp cần được phát triển dưới dạng Native thì sẽ cần trao đổi thêm để có hướng tích hợp phù hợp.

- Để module ứng dụng có thể giao tiếp được với các thành phần bên trong Hue-S (đăng nhập, lấy thông tin tài khoản, thông báo...) thì sẽ cần thêm SĐK core của Hue-S. Ngoài ra, ứng dụng Hue-S cũng cung cấp khung căn bản của ứng dụng Hue-S để các đơn vị tiến hành tích hợp thử trước khi bàn giao hay cập nhật mã nguồn ứng dụng và khi bàn giao mã nguồn ứng dụng cần cung cấp dưới dạng đã tích hợp thành công vào khung Hue-S này.

- Mã nguồn ứng dụng phải được cung cấp ở dạng minh bạch có thể đọc được. Trong trường hợp cần giấu mã nguồn vì lý do bảo mật hoặc bảo vệ tài sản trí tuệ thì sẽ cần trao đổi trực tiếp để có phương hướng tích hợp phù hợp.

- Mã nguồn ứng dụng tích hợp sẽ được đẩy lên Git Repositoty do Hue-S cung cấp. Yêu cầu cần tạo các branch để giữ các phiên bản cũ (tối thiểu 5 phiên bản) để đề phòng trường hợp có lỗi nghiêm trọng không thể khắc phục sớm thì có thể tạm thời quay về bản cũ và cũng để phục vụ cho việc Hue-S cần kiểm tra giám sát sự thay đổi của các phiên bản.

- Trong quá trình Hue-S review code ứng dụng, nếu nhận ra có phần nào đó chưa phù hợp, chưa đảm bảo các yêu cầu chất lượng kỹ thuật thì có thể yêu cầu phía cung cấp ứng dụng tiến hành chỉnh sửa. Ngoài các yêu cầu về kỹ thuật, chất lượng ứng dụng được mô tả trong tài liệu thì về cơ bản các ứng dụng tích hợp vào Hue-S cần tuân thủ theo các yêu cầu, khuyến nghị về hiệu năng, bảo mật, trải nghiệm... do Apple và Google đưa ra dành cho việc phát triển ứng dụng di động.

2. Các thành phần tích hợp do ứng dụng Hue-S cung cấp

a. Tài khoản người dùng hệ thống

Thông tin tài khoản Hue-S bao gồm các trường dữ liệu sau (một số thông tin sẽ được bổ sung sau):

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
Lớp (class) User
username	String	X	Tên đăng nhập
name	String	X	Họ và tên người dùng
gender	Byte	X	Giới tính. 1: Nam; 2 Nữ;
birthday	String	X	Năm sinh người dùng định dạng dd/MM/yyyy
address	String		Địa chỉ thường trú của người dùng
email	String		Email
phone	String	X	Điện thoại di động
avatar			Url ảnh đại diện của người dùng

Ứng dụng tích hợp vào Hue-S có thể cần thêm một số trường thông tin khác liên quan đến dịch vụ của mình. Trong trường hợp này ứng dụng có thể tự bổ sung thêm màn hình cập nhật thông tin trong ứng dụng và tự quản lý các thông tin này (cập nhật, đồng bộ, lưu trữ...) mà không thông qua Hue-S. Tuy nhiên đơn vị cung cấp ứng dụng cần phải cung cấp API để Hue-S có thể truy xuất dữ liệu này khi cần thiết và cũng cần nêu rõ các trường dữ liệu cần thêm trước khi tích hợp ứng dụng. Lưu ý, cần tránh bắt buộc người dùng nhập các thông tin thêm của ứng dụng ngay từ lần đầu người dùng sử dụng ứng dụng nếu không thật sự cần thiết.

Ứng dụng Hue-S chỉ cho phép đăng nhập bằng tài khoản công dân Huế. Trong trường hợp phía cung cấp ứng dụng tích hợp đã có khối lượng dữ liệu tài khoản người dùng lớn và muốn tận dụng dữ liệu này thì có thể dựa vào thông tin người dùng tài khoản Hue-S (ví dụ số điện thoại, địa chỉ email) để kiểm tra xem người dùng này đã tồn tại trên hệ thống hay chưa và sẽ gợi ý người dùng tiến hành đồng bộ dữ liệu giữa 2 tài khoản công dân Huế và tài khoản của phía cung cấp ứng dụng tích hợp.

Thư viện tích hợp Hue-S sẽ bao gồm aAPI tài khoản để các ứng dụng tích hợp có thể lấy được thông tin tài khoản hiện tại đang đăng nhập và token xác thực của tài khoản (xác thực thông tin người dùng trên hệ thống quản lý tài khoản công dân Huế) dành cho ứng dụng tích hợp. Lưu ý, các ứng dụng tích hợp khác nhau sẽ có token xác thực người dùng khác nhau.

b. Hệ thống Menu điều hướng chính (Navigation Menu)

Là hệ thống Menu điều hướng thống nhất của ứng dụng Hue-S. Từ các ứng dụng tích hợp đều có thể gọi Menu này nhằm thực hiện các điều hướng (navigative): về màn hình chính của ứng dụng, các ứng dụng ngang cấp khác, các chức năng thông tin cơ bản. Việc gọi menu chính sẽ được cài đặt ở nút menu (dạng Hamburger = ) hoặc vuốt từ cạnh trái màn hình sang phải. Các ứng dụng tích hợp chủ động thiết lập menu hamburger tại các vị trí cần thiết của ứng dụng.

Navigation Menu này được cung cấp trong SDK tích hợp Hue-S. Ngoài các Menu điều hướng cố định của Hue-S thì các đơn vị tích hợp cũng có thể bổ sung thêm các Menu điều hướng riêng của ứng dụng thông qua API.

Ngoài ra trong Navigation Menu còn có 2 Menu cố định sẵn dành riêng cho từng ứng dụng tích hợp là Hướng dẫn (dành cho việc điều hướng đến màn hình hướng dẫn cũng như giới thiệu ứng dụng nếu có) và Cài đặt (dành cho việc điều hướng đến màn hình cài đặt riêng của ứng dụng tích hợp nếu ứng dụng tích hợp có các cấu hình cho phép người dùng tùy chỉnh). Các ứng dụng tích hợp chủ động ẩn/hiện 2 Menu này tùy theo ứng dụng có các mục trên hay không thông qua API.

c. Màn hình đăng nhập, đăng ký

Ứng dụng tích hợp khi cần thực hiện các chức năng yêu cầu phải chứng thực người dùng có thể tiến hành điều hướng đến màn hình đăng nhập hoặc màn hình đăng ký thông qua API do Hue-S cung cấp. Sau khi người dùng đăng nhập thành công thì tất cả các ứng dụng tích hợp sẽ nhận được sự kiện đăng nhập bao

gồm thông tin về tài khoản của người dùng vừa đăng nhập

d. Thành phần tiếp nhận và phân phối thông báo (Notification)

Ứng dụng Hue-S sẽ là nơi tiếp nhận tất cả các thông báo được đẩy đến, và sau đó Hue-S sẽ phân phối thông báo cho ứng dụng tích hợp tương ứng

e. Chia sẻ dữ liệu (bao gồm local data và remote)

Hue-S sẽ cung cấp kênh trao đổi dữ liệu để các ứng dụng tích hợp có thể thực hiện chia sẻ dữ liệu cho nhau cũng như cung cấp dữ liệu cho Hue-S khi cần thiết.

3. Tích hợp tài khoản

a. Nguyên tắc

Mỗi khi người dùng đăng nhập hoặc đăng xuất Hue-S sẽ phát ra 1 sự kiện thông báo cho toàn bộ các ứng dụng tích hợp được biết. Các ứng dụng cần dựa vào sự kiện này để có cách hành động phù hợp nếu cần. Ví dụ như xóa các dữ liệu cache cá nhân của tài khoản vừa đăng xuất, hủy đăng 1 số topic firebase liên quan đến tài khoản vừa đăng xuất, dừng các request liên quan đến tài khoản vừa đăng xuất...

Các tác vụ của các ứng dụng tích hợp cần thực hiện khi nhận sự kiện đăng nhập/đăng xuất nên cố gắng thực hiện nhanh. Các tác vụ lâu hoặc nặng nên chờ đến khi người dùng vào app cụ thể mới tiến hành thực hiện.

b. Sơ đồ tuần tự đăng nhập (login)

Hình 2 Sơ đồ tuần tự đăng nhập từ hệ thống Hue-S

c. Sơ đồ tuần tự đăng xuất (logout)

Hình 3 Sơ đồ tuần tự quá trình đăng xuất ứng dụng trên các module tích hợp

4. Quy tắc đặt tên tránh xung đột

Các ứng dụng tích hợp vào Hue-S phải cần đảm bảo có các giá trị tên riêng biệt sau đây:

- Tên miền của đơn vị cung cấp ứng dụng tích hợp

- Tên ứng dụng

- Prefix name (dùng cho đặt tên file, tag...) riêng biệt. Ví dụ ứng dụng có prefix name là cmv và cần đặt giá trị tag là waitUpload thì giá trị cuối cùng của tag sẽ là cmvWaitUpload hoặc cmv_waitUpload...

Về cơ bản để tránh xung đột thì mỗi khi ứng dụng cần 1 giá trị để sử dụng cho đặt tên File hoặc Tag cho các api thì giá trị đó cần bao gồm package name (hoặc Bundle Identifier) hoặc prefix name (trong trường hợp tên hoặc tag cần ngắn gọn) riêng biệt mà ứng dụng đã đăng ký trước khi tích hợp vào Hue-S. Trong đó có các trường hợp được quy định cụ thể như sau.

a. Android

- Module package name

Các module được tạo (bao gồm cả module chính tích hợp và các module tự tạo khác) cần được đặt tên package theo quy tắc topleveldomain.applicationname để tránh xung đột với các module khác

Ví dụ công ty có tên miền là example.com và chức năng feedback là upload sẽ được đặt tên com.example.feedback

- File, Folder (bao gồm cả database, SharedPreferences) được sinh ra trong quá trình sử dụng ứng dụng cần là con của thư mục gốc cha có đường dẫn như sau:

Internal Storage (bao gồm cả đường dẫn cache và data): đường_dẫn_gốc_internal/ {Tên_ứng_dụng}

External Storage: đường_dẫn_gốc_external/HueS/{Tên_ứng_dụng}

(Lưu ý: cần kiểm tra xem thư mục Hue-S đã tồn tại chưa)

- Resource (drawable, string, style....)

Cần đặt tên có prefix riêng biệt và quy định giá trị prefix này trong gradle thông qua key “resourcePrefix” (có thể lấy tên viết tắt của app làm prefix)

- Các name, tag cần phải riêng biệt như Intent Action, Content Uri Authority, WakeLock Tag, Permission Name...

Đặt tên cần bao gồm cả package name của module để tránh xung đột

- Universal Links

Phần domain của link cho tất cả các ứng dụng có giá trị là domain của Hue-S. Các ứng dụng tích hợp sẽ sử dụng phần path của link để phân biệt link giữa các ứng dụng. Giá trị phần path này cần đặt riêng biệt để không xung đột với các ứng dụng khác

- Notification channel Id

Id kênh thông báo cần được đặt theo quy tắc {package_name}_{id}. Ví dụ com.example.feedback_hotSale

- Process name:

Đặt tên process cần bao gồm prefix name riêng biệt của ứng dụng. Lưu ý hiện tại Hue-S chưa hỗ trợ app tích hợp tạo thêm process.

b. IOS

- File, Folder được sinh ra trong quá trình sử dụng ứng dụng cần là con của thư mục gốc cha có đường dẫn như sau: đường_dẫn_gốc_internal/(Tên_ứng_dụng). Trong đó có 1 số lưu ý như sau:

Đường_dẫn_gốc_internal là đường dẫn đến các loại thư mục lưu trữ nội bộ gốc của ứng dụng bao gồm: Documents, Library, Library/Caches, tmp.

Các File, Folder được lưu trữ trong Documents sẽ được chia sẻ để người dùng có thể truy xuất khi cần thiết (qua ứng dụng quản lý Files). Vì vậy không nên lưu trữ các nội dung mà không muốn người dùng truy cập trực tiếp ở thư mục Documents

- UserDefault

Bắt buộc khởi tạo UserDefaults kèm suiteName bao gồm prefix name riêng biệt của ứng dụng.

- Local Notification(UNNotification)

Trong trường hợp không sử dụng UUID cho identifier mà cần tùy biến tên thì cần đặt tên bao gồm bundle identifier

- NotificationCenter

Giá trị tên được dùng để post cần bao gồm prefix name riêng biệt của ứng dụng

- KeyChain

Giá trị key phải bao gồm prefix name riêng biệt của ứng dụng.

- Framework bundle id

Cách đặt giá trị bundle id cho framework (bao gồm cả framework chính tích hợp và các framework tự tạo khác) giống với đặt tên package module cho Android

c. Flutter

- Package name: Để tránh xung đột tên cần đặt tên cho package (library) ngắn gọn có liên quan đến tên của ứng dụng và bao gồm prefix name riêng biệt của ứng dụng đã đăng ký từ đầu. Các plugin, package flutter tự tạo khác thì cần đặt tên bao gồm Prefix Name riêng biệt của ứng dụng.

- Method Channel: Các tên method channel được sử dụng cần bao gồm package name có tên miền ngược của ứng dụng.

- Route: Các ứng dụng tích hợp quy định tên route cần có prefix là base route có dạng /{package_name} (truy cập route này sẽ vào màn hình chính ứng dụng tích hợp). Ví dụ App A tích hợp vào Hue-S có các route như sau /appA/featureA, /appA/featureB

5. Deep Links

a. Android

Chỉ cần khai báo Activity tương ứng với Link của ứng dụng trong file AndroidManifest

b. IOS

Chỉ sử dụng Universal Links không sử dụng Url Scheme.

Khi ứng dụng Hue -S kích hoạt từ Universal Links, Hue-S sẽ gọi Class xử lý link của ứng dụng liên quan (Class này sẽ phải đặt tên theo quy ước từ trước) dựa vào phần path của link.

6. Tích hợp notification

a. Local Notification

Đối với IOS thì chỉ cần đặt giá trị identifier () theo quy ước đã được nêu ở phần đặt tên sao cho tránh xung đột

Đối với Android sẽ có 2 trường hợp cần tạo Local Notification là khi nhận được thông báo data Firebase do Hue-S làm trung gian chuyển do ứng dụng và ứng dụng tự tạo thông báo local (Ví dụ người dùng đặt lịch nhắc nhở). Việc tạo thông báo local trên Android cần tuân thủ 1 số quy tắc sau đây:

- Cần tạo các kênh thông báo riêng biệt cho từng loại thông báo khác nhau (Notification Channel) để người dùng có thể tùy chọn bật tắt thông báo không cần thiết với bản thân.

- Mỗi ứng dụng cần tích hợp vào Hue-S sẽ được cung cấp sẵn nhóm kênh thông báo (Notification channel group) trước khi tiến hành tích hợp ứng dụng. Các ứng tích hợp bắt buộc phải sử dụng groupId của nhóm thông báo cung cấp sẵn để tạo kênh thông báo.

- Thông báo local bắt buộc phải được khởi tạo kèm theo tag là package name của ứng dụng còn id có giá trị tùy ý: notify (String package_name, int id, Notification notification)

b. Remote Notification

Khi các ứng dụng tích hợp cần đẩy thông báo cho người dùng, thay vì gửi trực tiếp lên firebase sẽ được đưa tập trung về Server của Hue-S và Server Hue-S sẽ thực hiện việc push notification lên Firebase. Việc này nhằm kiểm soát tần suất đẩy thông báo, giảm tính phức tạp trong cấu hình thông báo ứng dụng và giúp cho ứng dụng Hue-S có thể lấy danh sách thông báo (xem lại các thông báo đã đẩy) nhanh chóng từ 1 nguồn duy nhất.

POST https:/tuongtac.thuathienhue.gov.vn /dichvu/push

to: Xác định thông báo này sẽ gửi cho ai. Giá trị có thể là tên topic (/topics/{tên_topic}) hoặc usemame của người dùng cụ thể muốn gửi. Hiện tại chưa hỗ trợ gửi theo nhóm. Lưu ý tên topic cần thêm tiền tố prefix name riêng biệt của ứng dụng để tránh xung đột. Ví dụ cần gửi thông báo đến topic có tên hotSale (to: /topics/hotSale) và ứng dụng có prefix name là caro thì tên topic sẽ là caro_hotSale

priority: Chỉ định mức độ quan trọng của thông báo gồm 2 giá trị normal và high. Lưu ý đối với cái thông báo không quan trọng, mang tính quảng cáo, giới thiệu, phạm vi đối tượng nhắm đến là cộng đồng thì không đặt giá trị high.

title: Tiêu đề thông báo. Tiêu đề nên mang tính đặc trưng của ứng dụng nếu không thì sử dụng tên ứng dụng làm tiêu đề thông báo.

message: Nội dung thông báo. Nội dung này nên ngắn gọn, cụ thể.

data (có thể null): Dữ liệu gửi kèm thông báo có kích thước không vượt quá 3 KB. Trong trường hợp vượt quá 3 KB thì có thể dùng gzip để nén dung lượng text data

channel_id (có thể null): Chỉ định notification channel id của Android. Mặc định thì thông báo Android từ firebase sẽ được đẩy vào kênh thông báo có id là appId của ứng dụng tích hợp. Nếu channel_id có giá trị thì thông báo sẽ được đẩy vào kênh thông báo có id là {appId}_{id}. Các ứng dụng tích hợp cân chủ động tạo các kênh thông báo của mình.

c. Firebase

Hiện tại chỉ hỗ trợ tích hợp Crashlytics cho việc log lỗi. Trong 1 khoảng thời gian định kỳ nhất định Hue-S tiến hành rà soát lỗi ứng dụng và sẽ gửi các lỗi liên quan đến ứng dụng cho bên cung cấp ứng dụng để tiến hành vá lỗi. Các dịch vụ khác về sau sẽ tiến hành tích hợp thông qua Firebase BigQuery và Firebase Api nếu được hỗ trợ

7. Lưu trữ và đồng bộ dữ liệu

Mỗi ứng dụng sẽ sử dụng file database riêng để tránh xung đột dữ liệu. Vì sử dụng database riêng nên mỗi ứng dụng có thể tùy ý sử dụng loại database (file, sql, nosql) Hue-S sẽ phát 1 sự kiện khi người dùng mở ứng dụng Hue-S để các ứng dụng tích hợp có thể tiến hành đồng bộ các dữ liệu quan trọng, cần thiết đối với người dùng. Các ứng dụng tích hợp nhận sự kiện này thông qua việc kế thừa class AppDelegateImpI. Tuy nhiên cần tránh thực hiện nhiều request hoặc các tác vụ lâu nếu không thật sự cần thiết trong thời gian này.

Nếu ứng dụng có các tác vụ định kỳ cần thực hiện ở background (khi ứng dụng không ở trạng thái active đối với IOS hoặc thậm chí khi ứng dụng không được bật trước đó đối với Android) thì cần trao đổi thêm trực tiếp để có phương án tích hợp phù hợp.

Android và IOS có cung cấp nhiều loại vùng nhớ cho từng loại dữ liệu khác nhau. Cần phải lựa chọn đúng loại vùng nhớ theo khuyến nghị của Apple và Google vì Hue-S sẽ chủ động dọn dẹp các vùng nhớ (tùy theo từng hoàn cảnh sẽ chọn các vùng nhớ khác nhau) của các ứng dụng khi cần thiết. Ngoài ra dung lượng bộ nhớ trong cho các vùng nhớ lâu dài (không phải cache hoặc temporary) tối đa mà các ứng dụng được sử dụng là 100MB.

8. Bảo mật

- Hạn chế lưu trữ các dữ liệu mang tính chất nhạy cảm của người dùng nếu không cần thiết. Nếu có lưu trữ thì dữ liệu cần được mã hóa bởi cơ chế sinh khóa bảo mật cao hoặc lưu trữ trong các vùng nhớ bảo mật cao do hệ điều hành cung cấp (Keychain đối với ios và Keystore đối với Android). Đối với database (sql, nosql) thì có thể sử dụng các thư viện hỗ trợ mã hóa là sqlcipher hay Realm.

- Các request network nếu có gửi nhận dữ liệu hay thao tác mang tính nhạy cảm thì bắt buộc phải sử dụng HTTPS. Server luôn phải xác thực, kiểm tra tính hợp lệ của request, tuyệt đối không tin tưởng vào client.

- Tránh trả dữ liệu dư thừa cho người dùng để không lãng phí dung lượng của người dùng và tăng tính bảo mật dữ liệu. Những dữ liệu người dùng không nên thấy thì không trả về cho dù có chặn hiển thị trên app.

- Đối với các chức năng, thao tác cần tính bảo mật cao trên Android thì khuyến nghị nên kiểm tra độ tin cậy của thiết bị thông qua SafetyNet Api. Phần này sẽ do Hue-S cung cấp trung gian thông qua API tích hợp.

- Webview chỉ được sử dụng để hiển thị nội dung html tĩnh. Không được sử dụng Webview để hiển thị hoặc tải nội dung của các bên khác. Trong trường hợp cần tải nội dung trang web ngoài thì sử dụng Chrome Custom Tabs hoặc mở trình duyệt của thiết bị

- Đối với các file được upload từ ứng dụng cần đổi tên file trước hoặc sau khi upload để tránh trường hợp lộ thông tin người dùng từ tên file trừ khi có yêu cầu giữ tên từ người dùng hoặc việc giữ tên là cần thiết đối với người dùng. Đối với các file ảnh và video khi tải lên server cần phải xóa các thông tin metadata có liên quan đến người dùng (ngày tạo, chỉnh sửa, vị trí, thông số camera...)

- Khi người dùng đăng xuất tài khoản thì ứng dụng cần xóa hết các dữ liệu liên quan đến tài khoản. Nếu cần giữ lại thì phải mã hóa để chỉ khi tài khoản đó đăng nhập lại mới có thể khai thác dữ liệu được.

9. Hiệu năng

- Các request network thông thường (tổng dữ liệu gửi/nhận nhỏ hơn 100KB và không thực hiện các tính toán phức tạp) có thời gian trung bình không quá 2 giây

- Tuyệt đối không thực hiện các tác vụ nặng hoặc mất nhiều thời gian (network, truy xuất file/database...) ở thread UI

- Cố gắng kiểm soát memory ứng dụng để không bị đẩy lên quá nhanh hoặc quá cao gần ngưỡng crash. Hạn chế tối đa memory leak. Ngoài ra cần hạn chế việc tạo thêm process trên Android và mỗi khi kết thúc process thì nên chủ động kết thúc (kill) process nếu process không được cần mở thường xuyên hoặc không phải process quan trọng.

- Khi ứng dụng rơi vào trạng thái không kích hoạt thì nên dừng các tác vụ không cần thiết (nhất là các request network hoặc tác vụ nặng, sensor) để giảm hao phí dung lượng pin, cpu. Ngoài ra, khi người dùng thoát khỏi màn hình chức năng cũng cần phải dừng các tác vụ không cần thiết được phát sinh ở màn hình này.

- Tuyệt đối không lạm dụng đẩy thông báo ở dạng im lặng (data Android và silent IOS) để kích hoạt thiết bị active cho mục đích đồng bộ dữ liệu. Nếu cần dựa vào thông báo để đồng bộ dữ liệu lớn và thường xuyên thì cần trao đổi thêm.

- Tuyệt đối không tự tạo các lịch task chạy ngầm bên Android (bao gồm cả Service) hoặc các các background task bên IOS để đồng bộ dữ liệu. Như đã ghi trên phần lưu trữ và đồng bộ dữ liệu, việc này cần trao đổi thêm.

- Cố gắng cache dữ liệu để tránh việc request network liên tục trong thời gian ngắn. Ngoài ra nên tạo các phiên bản nhỏ của dữ liệu. Ví dụ như Ảnh thì sẽ có ảnh thumb để hiển thị ở danh sách thay vì sử dụng ảnh đầy đủ. Danh sách bài viết thì chỉ cần 1 vài thông tin như tiêu đề, tóm tắt, ngày đăng chứ không cần toàn bộ nội dung bài viết. Như vậy không chỉ giảm dung lượng dữ liệu mà còn giảm thiểu CPU sử dụng để xử lý dữ liệu

- Đối với các tác vụ xử lý nặng thì nên có các phương hướng xử lý, các hạn chế ràng buộc dữ liệu cho từng phân khúc cấu hình thiết bị nếu có thể. Ví dụ với tác vụ nén ảnh thì các thiết bị có memory lớn sẽ cho phép thực hiện 3 tác vụ nén ảnh chạy song song, còn với các thiết bị có dung lượng memory nhỏ thì chỉ cho phép thực hiện 1 tác vụ nén trong 1 thời điểm.

10. Tích hợp các dịch vụ ứng dụng di động

a. Thanh toán trong ứng dụng (in-app purchase)

Thanh toán trong ứng dụng Hue-S sẽ không thông qua các dịch vụ thanh toán của bên thứ 3 nào khác (kể cả dịch vụ thanh toán trong ứng dụng của Apple và Google) mà sử dụng cổng thanh toán riêng. Các ứng dụng tích hợp sẽ sử dụng các api thanh toán do Hue-S cung cấp để tiến hành thanh toán trong ứng dụng.

Trong trường hợp ứng dụng có các nội dung số cần thanh toán mà theo chính sách phát triển ứng dụng bắt buộc phải sử dụng dịch vụ in-app purchase của Google/Apple thì phải tự tìm cách chuyển đổi phù hợp.

b. Bản đồ

Hue-S sẽ cung cấp cho các đơn vị phát triển ứng dụng dịch vụ bản đồ miễn phí bao gồm sdk và dữ liệu bản đồ trong phạm vi tỉnh Thừa Thiên Huế. Các ứng dụng tích hợp vào Hue-S bắt buộc sẽ phải sử dụng bản đồ này. Trong trường hợp dịch vụ bản đồ của Hue-S chưa đáp ứng đủ yêu cầu thì sẽ tiến hành trao đổi thêm để có phương án tích hợp bản đồ phù hợp.

V. YÊU GIAO DIỆN ỨNG DỤNG TÍCH HỢP

1. Bố cục màu sắc

Cần dựa theo các guideline của Apple (ios) và Google material (android). Trong đó có một số yêu cầu cụ thể như sau:

- Cần nhất quán giao diện ứng dụng trên các nền tảng khác nhau (Android và IOS) để người dùng có thể dễ dàng sử dụng ứng dụng trên nhiều thiết bị di động. Đối với các giao diện dành cho các thiết bị di động quá khác biệt (đồng hồ thông minh, ti vi thông minh...) hay trên máy tính thì cũng cần có những sự tương đồng nhất định với giao diện trên điện thoại.

- Không sử dụng quá 3 màu chính (không tính màu đen, trắng và gradient) và cần nhất quán trong việc sử dụng màu. Tuyệt đối không lạm dụng màu sắc khiến cho người dùng khó đọc được nội dung trừ trường hợp màn hình có ít nội dung chữ cần đọc

- Không sử dụng nhiều loại font chữ trong ứng dụng, cần sử dụng các loại font, kích thước font và màu chữ sao cho dễ đọc.

- Sử dụng các icon đơn giản và hiện đại ví dụ như material icon của google

- Bố cục sắp xếp các nội dung ứng dụng cần gọn gàng, dễ nhìn trên nhiều kích thước màn hình và scaling. Phải có sự phân tách rõ ràng giữa các nhóm nội dung trên màn hình

- Với mỗi màn hình chức năng, các thành phần tương tác được định hướng là chức năng chính tại màn hình đó thì cần được thể hiện nổi bật hơn (bởi màu sắc hoặc kích thước) so với các thành phần khác.

- Ứng dụng cần có navigation menu bên trái. Ngoài các thông tin bắt buộc của Hue-S bao gồm: header, danh sách ứng dụng, giới thiệu ứng dụng hiện tại (thông tin ứng dụng, hướng dẫn sử dụng...) và cài đặt (nếu có) thì vẫn có thể tùy ý thêm các menu điều hướng riêng của ứng dụng vào navigation.

- Hạn chế nhét các điều hướng, chức năng quan trọng hoặc được dùng thường xuyên của ứng dụng ở navigation menu, cố gắng thể hiện các chức năng đó ở màn hình chính

- Không nên thể hiện quá nhiều nội dung trong 1 màn hình nếu không thật sự cần thiết. Nên chia nhỏ các nhóm nội dung ra nhiều màn hình để người dùng dễ đọc và thao tác. Trong trường hợp thiết kế cho máy tính bảng thì 1 màn hình giao diện của máy tính bảng có thể là tổng hợp nhiều màn hình giao diện điện thoại.

- Màn hình đầu ứng dụng cần có tên ứng dụng (tên có thể biểu diễn cả dạng text hoặc hình ảnh miễn sao có thể nhận dạng được đây là ứng dụng gì) và nút hamburger để mở navigation menu (cũng có thể mở bằng cách vuốt từ mép trái màn hình.

2. Trải nghiệm

- Không sử dụng webview để thể hiện màn hình chức năng trừ trường hợp cần hiển thị nội dung html tĩnh. Nên lập trình các màn hình chức năng dưới dạng native hoặc đa nền tảng flutter để đem lại trải nghiệm tốt cho người dùng và đảm bảo tính bảo mật.

- Cố gắng tối ưu để tránh việc giật, khựng khung hình trong quá trình sử dụng ứng dụng.

- Các thao tác load dữ liệu hoặc xử lý dữ liệu nên phải có nút dừng để người dùng có thể dừng thao tác (khi cảm thấy lâu hoặc không cần nữa). Ngoài ra nên cố gắng hạn chế các loading indicator toàn màn hình khi không thật sự cần thiết.

- Các nút, chữ...cho phép người dùng tương tác (nhấn, kéo...) phải có kích thước vùng bấm (tương tác) đủ lớn để người dùng dễ thao tác

- Thông báo lỗi thân thiện và dễ hiểu đồng thời kèm hướng giải quyết nếu có thể.

- Các nội dung text chi tiết nội dung nên cho người dùng có thể copy được

- Màn hình xem chi tiết nội dung phải cho người dùng có thể mở bằng trình duyệt để xem ở dạng web nếu có trang web

- Yêu cầu quyền:

Thực hiện yêu cầu quyền theo hoàn cảnh và phải giải thích vì sao cần quyền

Khi cần người dùng nhảy tới Settings (yêu cầu quyền bị deny, bật GPS...) cần giải thích rõ và cho phép người dùng quyết định có đến màn hình Settings hay không

Khi vào 1 màn hình nội dung và màn hình đó cần yêu cầu 1 quyền nào đó. Nếu quyền đó không quá quan trọng (hoặc đã từng bị deny nhiều lần) thì không nên hiển thị dialog yêu cầu quyền ngay khi vào màn hình để tránh việc làm phiền người dùng. Có thể hiển thị message yêu cầu cấp quyền cùng với nội dung của màn hình đó để người dùng cảm thấy cần thì mới bấm cấp quyền.

- Khi vào màn hình cần bật GPS thì không nên bắt buộc người dùng phải bật nếu không quá cần thiết, cần hiển thị message lý do vì sao cần bật GPS. Đối với Android thì nên bật thông qua api google chứ không nhảy đến Settings.

- Cache các dữ liệu cần thiết với người dùng hoặc các dữ liệu ít thay đổi để có thể sử dụng offline hoặc cho hiện trước dữ liệu cache trước khi request dữ liệu từ mạng để tạo cảm giác tải dữ liệu nhanh (hình ảnh, ghi chú đánh dấu... thông tin tài khoản...).