Điểm nổi bật

  • Tự động hóa: Tự động cập nhật và đẩy các thay đổi vào bucket output khi có thay đổi trong thư mục uploads hoặc tệp pwa.config.ts bằng Github Actions.
  • Tạo tự động: Tự động tạo ra các biểu tượng có kích thước khác nhau từ một biểu tượng duy nhất favicon.png.
  • Linh hoạt: Bạn có thể xây dựng PWA cho bất kỳ trang web Blogger (blogspot.com) nào.

Yêu cầu

  • Một tài khoản Github.
  • Chuẩn bị một biểu tượng cho blog của bạn ở dạng .png có kích thước tối thiểu là 512x512. Đổi tên tệp thành favicon.png.
  • Chuẩn bị một vài ảnh chụp màn hình trang web của bạn ở định dạng .png.
    • Ít nhất 3 ảnh chụp màn hình cho thiết bị hẹp (narrow) với kích thước 540x720. Đặt tên theo thứ tự: screenshot-narrow-1.png, screenshot-narrow-2.png, v.v.
    • Ít nhất 3 ảnh chụp màn hình cho thiết bị rộng (wide) với kích thước 720x540. Đặt tên theo thứ tự: screenshot-wide-1.png, screenshot-wide-2.png, v.v.

Cài đặt PWA

Có hai cách để cài đặt PWA:

  1. Sử dụng Cloudflare Workers: Hỗ trợ đầy đủ các tính năng, bao gồm Trang ngoại tuyến và Thông báo đẩy OneSignal.
  2. Sử dụng JsDelivr: Không hỗ trợ các tính năng trên. Phù hợp nếu DNS của bạn không được quản lý bởi Cloudflare hoặc bạn đang dùng tên miền phụ blogspot.com.

1. Phân nhánh (Fork) và Cài đặt

Thực hiện theo các bước dưới đây dựa trên lựa chọn của bạn.

Nếu sử dụng Cloudflare Workers:

Bạn có thể làm theo các bước tại kho lưu trữ gốc để triển khai Workers và cấu hình route. Các bước này bao gồm việc nhấn nút "Deploy to Cloudflare Workers", cung cấp ID tài khoản và API Token.

Nếu không sử dụng Cloudflare Workers:

  1. Phân nhánh (fork) kho lưu trữ này.
  2. Đi đến kho lưu trữ đã phân nhánh và vào tab Actions.
  3. Bật quy trình công việc bằng cách nhấp vào "I understand my workflows, go ahead and enable them".

Thực hiện thay đổi

Bất cứ khi nào bạn thực hiện thay đổi nào đối với kho lưu trữ, Github Actions sẽ tự động triển khai lại các worker (nếu có) và cập nhật các tệp cần thiết.

1. Tải lên Favicon

Trong kho lưu trữ đã phân nhánh của bạn, tải lên tệp favicon.png đã tạo vào thư mục uploads.

2. Tải lên ảnh chụp màn hình

  • Tải lên ảnh chụp màn hình kích thước hẹp (540x720) vào thư mục uploads/screenshots/narrow.
  • Tải lên ảnh chụp màn hình kích thước rộng (720x540) trong thư mục uploads/screenshots/wide.

3. Cấu hình ứng dụng

Mở và chỉnh sửa tệp pwa.config.ts trong kho lưu trữ của bạn.

import type { Config } from './types';

export default {
  id: '/',
  name: 'Tên Blog Của Bạn',
  shortName: 'Tên Ngắn',
  description: 'Mô tả chi tiết về blog của bạn...',
  direction: 'auto',
  language: 'vi-VN',
  backgroundColor: '#fff',
  themeColor: '#fff',
  display: 'standalone',
  orientation: 'natural',
  scope: '/',
  startUrl: '/?utm_source=homescreen',
  appleStatusBarStyle: 'black-translucent',
  preferRelatedApplications: false,
  shortcuts: [
    {
      name: 'Lối tắt 1',
      shortName: 'Lối tắt 1',
      description: 'Mô tả lối tắt 1...',
      url: '/search/label/ten-nhan-1?utm_source=homescreen',
    },
    {
      name: 'Lối tắt 2',
      shortName: 'Lối tắt 2',
      description: 'Mô tả lối tắt 2...',
      url: '/search/label/ten-nhan-2?utm_source=homescreen',
    },
  ],
  pwa: {
    logs: true,
    // OneSignal chỉ khả dụng khi bạn sử dụng Cloudflare Workers
    oneSignalEnabled: false, // Đặt là true để bật OneSignal
    oneSignalConfig: {
      appId: '********-****-****-****-************', // Thay bằng OneSignal App Id của bạn
      allowLocalhostAsSecureOrigin: true,
    },
  },
  // Vui lòng thay thế bằng URL blog của bạn nếu sử dụng CDN (JsDelivr)
  origin: 'https://ten-blog-cua-ban.blogspot.com',
} satisfies Config;

Mô tả các khóa cấu hình:

Khóa (key) Kiểu (type) Bắt buộc Mô tả
name string Có Tên ứng dụng của bạn (Tên blog)
shortName string Có Tên viết tắt của ứng dụng
description string Có Mô tả ứng dụng của bạn
backgroundColor string Không Màu nền HEX của ứng dụng
themeColor string Không Màu chủ đề HEX của ứng dụng
startUrl string Không URL để mở khi ứng dụng được khởi chạy
shortcuts Array Không Danh sách các lối tắt của ứng dụng
origin string Không Nguồn gốc của blog của bạn (bắt buộc khi sử dụng JsDelivr)

Tích hợp OneSignal (Chỉ dành cho Cloudflare Workers)

Không áp dụng cho các mẫu AMP vì nó sử dụng OneSignal JavaScript SDK.

Nếu bạn đang sử dụng Cloudflare Workers, bạn có thể tích hợp thông báo đẩy OneSignal. Hãy làm theo hướng dẫn trên trang OneSignal để lấy App Id và cấu hình trong tệp pwa.config.ts.

Chỉnh sửa XML chủ đề Blogger

Sau khi thực hiện tất cả các thay đổi trên, hãy đợi Github Actions chạy xong. Sau đó, vào Bảng điều khiển Blogger → Chủ đề → Chỉnh sửa HTML.

1. Thêm thẻ Meta

Tìm tệp tương ứng trong kho lưu trữ của bạn (trong thư mục output) dựa trên lựa chọn cài đặt:

  • Nếu dùng Cloudflare workers: output/pwa-metatags.html
  • Nếu dùng JsDelivr (CDN): output/cdn-metatags.html

Sao chép toàn bộ nội dung của tệp trên và dán vào ngay bên dưới thẻ <head> trong trình chỉnh sửa HTML của Blogger.

2. Thêm Script cài đặt

Đối với mẫu không phải AMP (Non-AMP):

Thêm đoạn mã sau ngay bên dưới các thẻ meta bạn vừa thêm:

<!-- [ Start: Progressive Web App Script ] -->
<script async='' defer='' type='module' src='/app/pwa.js'></script>
<!-- [ End: Progressive Web App Script ] -->

Đối với mẫu AMP:

Thêm đoạn mã sau ngay bên dưới thẻ meta:

<script async='async' custom-element='amp-install-serviceworker' src='https://cdn.ampproject.org/v0/amp-install-serviceworker-0.1.js'/>

Và dán mã sau ngay phía trên thẻ đóng </body>:

<amp-install-serviceworker data-iframe-src='/app/offline' layout='nodisplay' src='/app/serviceworker.js'/>

Nút cài đặt tùy chỉnh (Tùy chọn)

Bạn không nên sử dụng tính năng này nếu đang sử dụng mẫu AMP.

Để thêm một nút cài đặt PWA đẹp mắt, hãy thêm mã sau:

Thêm đoạn CSS sau vào ngay phía trên thẻ </head>:

<style>/*<![CDATA[*/
/*! Custom PWA install button by Fineshop Design */
.pwa-button{position:fixed;z-index:999;left:20px;bottom:75px;display:flex;align-items:center;justify-content:center;width:40px;height:40px;border:none;border-radius:50%;background:#1900ff;visibility:visible;opacity:1;transition:visibility .5s,opacity .5s}
.pwa-button[hidden]{display:flex;visibility:hidden;opacity:0}
.pwa-button:not([disabled])::before{content:'';position:absolute;z-index:-1;inset:0;background:inherit;border-radius:inherit;animation:1s cubic-bezier(0,0,.2,1) infinite pwa-button-ping}
.pwa-button svg.flash{width:22px;height:22px;fill:none;stroke:#fff;stroke-linecap:round;stroke-linejoin:round;stroke-width:1.4}
@keyframes pwa-button-ping{75%,to{transform:scale(1.6);opacity:0}}
/*]]>*/</style>

Thêm đoạn JavaScript sau ngay phía trên thẻ </body>:

<script type='module'>/*<![CDATA[*/
/*! Custom PWA install button by Fineshop Design */
(({button:t,onInstall:n})=>{let i=null;var e=()=>{i&&(t.disabled=!0,i.prompt().then(e=>{"accepted"===e.outcome&&o()}).finally(()=>{t.disabled=!1}),i=null)},l=e=>{e.preventDefault(),i=e,t.hidden=!1};const o=()=>{t.hidden=!0,t.removeEventListener("click",e),window.removeEventListener("beforeinstallprompt",l)};t instanceof HTMLElement&&(t.hidden=!0,t.addEventListener("click",e),window.addEventListener("beforeinstallprompt",l));const d=e=>{t instanceof HTMLElement&&o(),"function"==typeof n&&n(e),window.removeEventListener("appinstalled",d)};window.addEventListener("appinstalled",d)})({
  button: document.getElementById("app_install_button")||Object.assign(document.body.appendChild(document.createElement("button")),{hidden:!0,type:"button",className:"pwa-button",innerHTML:"<svg class='flash' viewBox='0 0 24 24'><path d='M6.08998 13.28H9.17998V20.48C9.17998 22.16 10.09 22.5 11.2 21.24L18.77 12.64C19.7 11.59 19.31 10.72 17.9 10.72H14.81V3.52002C14.81 1.84002 13.9 1.50002 12.79 2.76002L5.21998 11.36C4.29998 12.42 4.68998 13.28 6.08998 13.28Z' stroke-miterlimit='10'></path></svg>"}),
  onInstall(){
    /**
     * Bạn có thể làm gì đó khi ứng dụng được cài đặt
     * Ví dụ: Hiển thị thông báo cảm ơn
     */
  }
});
/*]]>*/</script>

Sau khi lưu các thay đổi, nút cài đặt sẽ xuất hiện trên trang web của bạn khi có thể.

Phần kết luận

⭐ Hãy đánh dấu sao cho kho lưu trữ này nếu bạn thấy nó hữu ích.

🐞 Nếu bạn gặp bất kỳ vấn đề nào, hãy thoải mái mở một issue trên Github.