Biến trang web của bạn thành ứng dụng Android gốc với Bubblewrap

Nếu bạn là nhà phát triển web chưa biết về Phát triển ứng dụng (như tôi!), thì bài viết này là dành cho bạn. Tôi sẽ hướng dẫn bạn cách biến trang web của bạn thành một ứng dụng gốc mà không cần khuôn khổ hoặc ngôn ngữ mới. Bạn sẽ tìm hiểu cách chuyển đổi một trang web thành PWA (Ứng dụng web lũy tiến) mà bạn có thể xuất bản trên Cửa hàng Play.

Đầu tiên, chúng tôi sẽ biến trang web của bạn thành Ứng dụng web lũy tiến (PWA). Sau đó, chúng ta sẽ sử dụng công cụ dòng lệnh miễn phí của Google có tên là Bubblewrap để đóng gói PWA đó vào một ứng dụng Android. Hãy bắt đầu.

Điều kiện tiên quyết

Nếu bạn làm theo hướng dẫn này thì sẽ có một số điều kiện tiên quyết:

Kiến thức cơ bản về phát triển web
Trang web của bạn phải được hiển thị công khai và bạn cần có quyền truy cập vào mã nguồn của trang web.
Chúng tôi sẽ sử dụng npm để cài đặt các công cụ cần thiết, vì vậy hãy đảm bảo bạn đã cài đặt Node.js.

Lưu ý: Hướng dẫn này dựa trên Vite dự án, nhưng các bước cuối cùng với Bubblewrap đều giống nhau đối với mọi khung web.

Mục lục

PWA là gì?
Bubblewrap là gì?
- TWA (Hoạt động web đáng tin cậy) là gì?
- Cách TWA xác minh sự tin cậy
Bước 1 – Định cấu hình PWA của bạn trong Vite
- Tạo biểu tượng ứng dụng của bạn
- Cài đặt plugin Vite PWA.
- Định cấu hình Plugin
Bước 2 – Tạo ứng dụng Android
- Tạo thư mục bản dựng
- Cài đặt Bubblewrap CLI
- Khởi tạo dự án
- Hãy khắc phục sự cố lệnh init.
Bước 3 – Trả lời các câu hỏi về Bubblewrap
Bước 4 – Xây dựng ứng dụng
Bước 5 – Thiết lập xác thực TWA
- Thư mục .well-known là gì?
- delegate_permission/common.handle_all_urls là gì?
Bước 6 (Tùy chọn) – Tùy chỉnh trải nghiệm trong ứng dụng
Kết thúc

PWA là gì?

PWA là viết tắt của Ứng dụng web lũy tiến và mục tiêu của nó là làm cho trang web của bạn trông giống như một ứng dụng gốc. Nếu bạn đã truy cập một trang web trong trình duyệt của mình và nhìn thấy biểu tượng cài đặt cho phép bạn tải trang web đó xuống điện thoại hoặc máy tính xách tay thì bạn đã sử dụng PWA.

Nhưng nó không chỉ là về giao diện. PWA cũng có các tính năng giống như ứng dụng, chẳng hạn như làm việc ngoại tuyến, gửi thông báo đẩy, v.v.

Có hai thành phần chính của PWA.

Tệp kê khai mô tả ứng dụng của bạn, chẳng hạn như tên, biểu tượng, URL bắt đầu, v.v.
Nhân viên dịch vụ là một tệp JavaScript nền hoạt động như một proxy. Bộ nhớ đệm và thông báo đẩy được xử lý bởi một tệp dịch vụ, tệp này chạy dưới dạng một luồng khác ngoài luồng chính.

Nếu không có hai thành phần này, trình duyệt sẽ không cho phép người dùng tải ứng dụng xuống cục bộ.

Tệp kê khai và nhân viên dịch vụ giống như một danh sách kiểm tra cho trình duyệt. Khi bạn truy cập một trang web, trình duyệt sẽ tìm kiếm cả hai thành phần này. Nếu chúng xuất hiện và được định cấu hình chính xác, trình duyệt sẽ biết đó là PWA thực sự và sẽ hiển thị biểu tượng "cài đặt", cho phép người dùng tải xuống ứng dụng cục bộ. Nếu không có chúng, trình duyệt chỉ nhìn thấy một trang web thông thường và sẽ không có tùy chọn cài đặt.

Bọc bong bóng là gì?

Bubblewrap là một công cụ dòng lệnh do Google tạo ra để lấy PWA của bạn và biến nó thành Ứng dụng Android bằng cách sử dụng Hoạt động web đáng tin cậy (TWA).

Bubblewrap đơn giản hóa quy trình tạo TWA, biến tệp kê khai của PWA thành gói ứng dụng Android (APK hoặc AAB).

TWA (Hoạt động web đáng tin cậy) là gì?

Hoạt động web đáng tin cậy (TWA) là một tính năng hiện đại của Android cho phép bạn hiển thị toàn màn hình trang web trực tiếp của mình bên trong ứng dụng Android. Về cơ bản nó chạy website trên trình duyệt nhưng không hiển thị thanh địa chỉ trình duyệt trên App. Điều này giúp nó có cảm giác giống như một ứng dụng gốc.

Để mở khóa tính năng toàn màn hình này, ứng dụng của bạn cần phải “Đáng tin cậy”.

Đây là lúc "cái bắt tay bí mật" xuất hiện. Android cần chắc chắn rằng người xây dựng ứng dụng và người sở hữu trang web đều giống nhau. Nếu không có bằng chứng về quyền sở hữu này, TWA sẽ chạy ở chế độ dự phòng và hiển thị thanh địa chỉ trình duyệt ở trên cùng, làm hỏng cảm giác của ứng dụng gốc.

Cách TWA xác minh sự tin cậy

Sự tin cậy này được xác minh bằng hệ thống có tên Liên kết tài sản kỹ thuật số . Bạn đặt một tệp đặc biệt trên trang web của mình (chúng tôi sẽ thực hiện việc này trong phần triển khai) có chứa dấu vân tay kỹ thuật số duy nhất của ứng dụng của bạn. Khi người dùng mở ứng dụng của bạn, hệ điều hành Android sẽ kiểm tra tệp này. Nếu dấu vân tay trùng khớp, nó sẽ cấp trạng thái "đáng tin cậy" cho ứng dụng của bạn, xóa thanh địa chỉ và bật các tính năng khác như liên kết sâu.

Bạn có thể tự kiểm tra mối quan hệ này bằng công cụ kiểm tra chính thức của Google:Trình xác minh liên kết tài sản kỹ thuật số.

Bây giờ bạn đã hiểu dự án và các công cụ, hãy bắt đầu xây dựng.

Bước 1 – Định cấu hình PWA của bạn trong Vite

Bước đầu tiên là thêm hai thành phần chính cho PWA:tệp kê khai và nhân viên dịch vụ. Đây là thứ sẽ cho phép trình duyệt nhận ra nó là "có thể cài đặt được".

Hướng dẫn này dựa trên một dự án được xây dựng bằng Vite, giúp quá trình này trở nên dễ dàng với một plugin đặc biệt. Nếu bạn đang sử dụng một công cụ khác thì các khái niệm sẽ giống nhau nhưng bạn sẽ cần tra cứu các tài nguyên khác nhau về các bước cụ thể cho môi trường của mình.

Tạo biểu tượng ứng dụng của bạn

Trước khi chạm vào bất kỳ mã nào, chúng tôi cần các biểu tượng cho ứng dụng của mình. Android yêu cầu kích thước cụ thể cho biểu tượng trình khởi chạy của ứng dụng (những gì bạn nhìn thấy trên màn hình chính) và màn hình chờ (những gì bạn nhìn thấy khi ứng dụng khởi động).

Bạn sẽ cần hai kích thước chính:192x192 pixel và 512x512 pixel. Bạn có thể sử dụng Trình tạo Favicon này để tạo logo của mình ở các kích thước tương ứng. Bạn có thể tải lên biểu tượng chính của mình và nó sẽ tạo ra tất cả các kích thước cần thiết cho bạn.

Sau đó, chỉ cần tải xuống các tệp đã tạo và đặt 192x192 và 512x512 tập tin vào public thư mục dự án của bạn.

Biến trang web của bạn thành ứng dụng Android gốc với Bubblewrap – Hướng dẫn từng bước

Cài đặt plugin Vite PWA.

PWA yêu cầu tệp kê khai và nhân viên dịch vụ. Chúng tôi có thể tạo những thứ này theo cách thủ công, nhưng plugin này sẽ tự động hóa toàn bộ quá trình đó. Nó sẽ tự động tạo ra một manifest.json và service-worker.js cho bạn mỗi khi bạn xây dựng dự án của mình.

npm install vite-plugin-pwa -D

Định cấu hình plugin

Trong bước này, chúng tôi sẽ sử dụng plugin này và định cấu hình tệp kê khai ứng dụng của chúng tôi. Chỉnh sửa vite.config.ts tập tin. Cấu hình này sẽ cho plugin biết nên đặt tên gì cho ứng dụng của bạn, sử dụng biểu tượng nào, v.v.

Trong vite.config.ts :

export default defineConfig({
 plugins: [
 VitePWA({
 registerType: "autoUpdate", 
 manifest: {
 name: "your app name",
 short_name: "your app short name",
 description: "write any description",
 theme_color: "#0d1117",
 background_color: "#ffffff",
 display: "standalone",
 start_url: "/",
 icons: [
 {
 src: "/web-app-manifest-192x192.png",
 sizes: "192x192",
 type: "image/png",
 },
 {
 src: "/web-app-manifest-512x512.png",
 sizes: "512x512",
 type: "image/png",
 },
 ],
 },
 }),
 ]

Bây giờ, khi bạn chạy npm run build , plugin sẽ tự động tạo tệp kê khai và tệp nhân viên dịch vụ cho bạn. Khi đã xong, hãy triển khai các thay đổi. Bây giờ trang web của bạn là PWA.

Bước 2 – Tạo ứng dụng Android

Bây giờ trang web của bạn là PWA, hãy sử dụng Bubblewrap để đóng gói trang web vào ứng dụng Android.

Tạo thư mục bản dựng

Tạo một thư mục dành riêng cho các tệp dự án Android của bạn. Trong thư mục gốc của dự án, hãy tạo một thư mục mới. Tôi sẽ gọi số android của tôi .

project/
├── client/
├── server/
└── android/

Bây giờ hãy điều hướng đến thư mục mới mà bạn đã tạo.

Cài đặt CLI Bubblewrap

npm install -g @bubblewrap/cli

Khởi tạo dự án

Tiếp theo, chạy init lệnh. Bubblewrap sẽ kết nối với trang web trực tiếp của bạn, hãy đọc manifest.webmanifest mà Vite đã tạo và sử dụng thông tin đó để tạo dự án Android cơ bản.

bubblewrap init --manifest=https://your-website-domain/manifest.webmanifest

Chạy lệnh, thay thế your-website-domain bằng URL thực của bạn:

Hãy khắc phục sự cố `init` lệnh

Khi bạn chạy init lệnh, Bubblewrap sẽ cần hai gói phần mềm chính:Bộ công cụ phát triển Java (JDK) và SDK Android . Nó sẽ đề nghị cài đặt chúng cho bạn.

Thiết lập JDK:

? Do you want Bubblewrap to install the JDK (recommended)?
 (Enter "No" to use your own JDK 17 installation) (Y/n)

Trong trường hợp của tôi, khi tôi để Bubblewrap cài đặt JDK, quá trình này đã tải xuống các tệp nhưng sau đó không thành công ở bước "giải nén". Nếu bạn gặp phải vấn đề tương tự, đừng lo lắng! Cách khắc phục là cài đặt thủ công.

Nói Không theo lời nhắc.
Tải xuống phiên bản được đề xuất (thường là JDK 17) từ nguồn như Adoptium.
Hãy cài đặt nó và thiết lập các biến môi trường trong hệ thống của bạn để bao gồm bin của JDK con đường. Nếu bạn không chắc chắn về cách đặt biến môi trường, bạn có thể xem trang web này:Đặt biến môi trường.
Khi Bubblewrap yêu cầu đường dẫn, hãy cung cấp trực tiếp, chẳng hạn như C:\java\jdk-17.0.16.8-hotspot .

Thiết lập SDK Android:

Sau khi thiết lập thành công JDK, bước tiếp theo là định cấu hình SDK Android.

? Do you want Bubblewrap to install the Android SDK (recommended)?
 (Enter "No" to use your own Android SDK installation) (Y/n)

Vì tôi không có SDK Android nên tôi để Bubblewrap xử lý việc này bằng cách chọn Có . Tôi không gặp phải bất kỳ vấn đề nào ở đây.

Nếu bạn gặp bất kỳ vấn đề nào khi thiết lập trên Android SDK, chỉ cần thiết lập thủ công và đưa ra đường dẫn, giống như thiết lập JDK.

Bước 3 – Trả lời các câu hỏi về Bubblewrap

Sau khi SDK được thiết lập, Bubblewrap sẽ hỏi một loạt câu hỏi để định cấu hình ứng dụng của bạn. Thông tin này được sử dụng để tạo twa-manifest.json tệp, đây là bản thiết kế cho Ứng dụng của bạn.

Domain: Press Enter (auto-filled from your manifest)
Application name: Your full app name
Application ID: (e.g, chat.yourapp.twa)
Display mode: standalone
Orientation: portrait
Status bar color: Press Enter (accepts default)
Splash screen color: Press Enter (accepts default)
Icon URL: Press Enter (accepts default)
Include support for Play Billing?: Type Y if your app uses Google Play in-app purchases. Otherwise, N
Request geolocation permission?: Type Y if your app needs location access. Otherwise, N

Trong những câu hỏi này, phần quan trọng là kho lưu trữ chìa khóa và chìa khóa.

First and Last names: Your full name
Organizational Unit: Developer or anything
Organization: Your organization name
Country (2-letter code): Your country code
Password for key store: Enter a new password
Password for key: Re-enter the same password

Lưu ý: Các mật khẩu này cho cả kho khóa và khóa phải giống nhau, nếu không nó sẽ báo lỗi. Tham khảo vấn đề này: Vấn đề về bọc bong bóng.

Bước 4 – Xây dựng ứng dụng

bubblewrap build --universalApk

Lệnh này bắt đầu xây dựng ứng dụng của bạn. Ở đây, cờ universalApk sẽ tạo ra .apk và .abb . Nếu bạn định xuất bản ứng dụng của mình trong Cửa hàng Play, hãy tải lên .abb tập tin vào Cửa hàng Play. Để thử nghiệm, chúng tôi cần tệp APK, vì vậy cờ này universalApk sẽ tạo ra cả hai tập tin. Nếu chúng ta không đưa ra lá cờ này thì nó sẽ chỉ cho chúng ta .abb .

Bước 5 – Thiết lập xác thực TWA

Sau khi quá trình xây dựng hoàn tất, bạn sẽ nhận được APK. Chuyển nó vào điện thoại của bạn và kiểm tra nó. Khi mở ứng dụng, bạn sẽ thấy thanh địa chỉ của trình duyệt. Điều này là do chúng tôi chưa thiết lập "sự tin cậy" giữa ứng dụng và trang web của bạn. Hãy khắc phục điều đó ngay bây giờ.

Trong dự án giao diện người dùng của bạn, hãy truy cập public thư mục, tạo một thư mục mới có tên .well-known , và bên trong đó, tạo một tệp có tên assetlinks.json .

frontend/
├── public/
 ├── .well-known/
 └── assetlinks.json

`.well-known` là gì thư mục?

Một thư mục nổi tiếng được sử dụng để lưu trữ các tệp xác định cấu hình cho các giao thức, vì nó được sử dụng cho các nguồn bên ngoài để tìm xác thực cho trang web của bạn. Trong trường hợp của chúng tôi, ứng dụng của chúng tôi sẽ kiểm tra thư mục nổi tiếng từ trang web của chúng tôi và xác minh tính xác thực.

Dán đoạn sau vào assetlinks.json :

[
 {
 "relation": ["delegate_permission/common.handle_all_urls"],
 "target": {
 "namespace": "android_app",
 "package_name": "chat.yourapp.twa",
 "sha256_cert_fingerprints": [
 "your_sha256_fingerprint"
 ]
 }
 }
]

`delegate_permission/common.handle_all_urls` là gì ?

Đây là một lá cờ đặc biệt mở tất cả các liên kết từ ứng dụng thay vì tên miền. Nói một cách đơn giản, nó hoạt động như một liên kết sâu. Sau khi cài đặt ứng dụng, nếu bạn nhấp vào liên kết trang web của mình từ WhatsApp hoặc từ nơi nào đó, ứng dụng đó sẽ mở ứng dụng của bạn thay vì mở trong trình duyệt, hoạt động như một liên kết sâu.

package_name trường phải là packageId , bạn có thể lấy từ thư mục bản dựng Android của mình trong twa-manifest.json .

Bây giờ, lấy dấu vân tay của bạn. Chạy lệnh sau để làm như vậy:

keytool -list -v -keystore android.keystore -alias android

Tên bí danh phải là giá trị mà bạn đã tạo. Khi bạn nhập lệnh này, nó sẽ yêu cầu mật khẩu lưu trữ khóa. Nhập vào đó và bạn sẽ nhận được SHA256 của mình dấu vân tay. Sao chép và dán vào assetslinks.json tập tin trong sha256_cert_fingerprints mảng. Bây giờ đẩy những thay đổi này vào sản xuất. Bạn có thể xác minh xác thực trong Liên kết tài sản kỹ thuật số

Thế thôi! Bây giờ bạn có thể cài đặt ứng dụng và dùng thử.

Bước 6 (Tùy chọn) – Tùy chỉnh trải nghiệm trong ứng dụng

Ngoài ra, bây giờ sẽ có một số trường hợp chúng tôi muốn hiển thị nội dung khác nhau cho người dùng trên trang web so với ứng dụng di động. Chúng ta có thể làm được điều đó không? Vâng!

Trong thư mục bản dựng Android của bạn, ở twa-manifest.json , sẽ có một trường tên là startUrl . Nếu không thì thêm vào và thêm giá trị "startUrl": "/?twa=true" . startUrl là điểm vào. Tôi có tham số truy vấn có giá trị twa=true .

Chạy lại bản dựng với bubblewrap build --universalApk .

Bây giờ, nếu bạn mở ứng dụng của mình, nó sẽ mở ứng dụng có URL mục nhập là yourwebsitedomain.com/?twa=true .

Trong giao diện người dùng của bạn:

const twaParam = queryParams.get("twa");
const [isTwa, setIsTwa] = useState<boolean>(() => {
 return localStorage.getItem("isTwa") === "true";
});
useEffect(() => {
 if (twaParam === "true") {
 localStorage.setItem("isTwa", "true"); // set the value to local storage
 setIsTwa(true);
 }
}, [twaParam]);

 {isTwa? (
 <Link to="/contact" className="underline hover:text-primary">
 Contact
 </Link> 
 ) : (
 <Link to="/download" className="underline hover:text-primary">
 Download App
 </Link>
 )}

Trong đoạn mã trên, chúng tôi kiểm tra twa=true tham số truy vấn trong URL. Nếu có, chúng tôi sẽ lưu thông tin đó vào bộ nhớ cục bộ, sau đó chúng tôi hiển thị nội dung cho người dùng theo điều kiện.

Thế thôi. Chúng tôi đã tạo một Ứng dụng.

Nếu bạn muốn thay đổi bất kỳ tên, màu sắc hoặc màn hình giật gân nào, bạn có thể thay đổi nó trong twa-manifest.json và chạy lại bản dựng.

Kết thúc

Bubblewrap chỉ dành cho Android. Nếu bạn muốn ứng dụng hỗ trợ đa nền tảng, thì có một số nền tảng khác, như Tụ điện, mà tôi sẽ viết trong một bài viết khác.

Nhân tiện, bạn có thể xem Ứng dụng mà tôi đã tạo bằng Bubblewrap tại đây:Stranger Talk.

Nếu có bất kỳ sai sót nào hoặc bạn có thắc mắc, hãy liên hệ với tôi trên LinkedIn hoặc Instagram.

Cảm ơn bạn đã đọc!

Học cách viết mã miễn phí. Chương trình giảng dạy mã nguồn mở của freeCodeCamp đã giúp hơn 40.000 người có được việc làm với tư cách là nhà phát triển. Bắt đầu