Bubblewrap을 사용하여 웹사이트를 기본 Android 앱으로 변환

저처럼 앱 개발에 대해 모르는 웹 개발자라면 이 글이 도움이 될 것입니다. 새로운 프레임워크나 언어 없이 웹사이트를 기본 앱으로 전환하는 방법을 알려드리겠습니다. 웹사이트를 Play 스토어에 게시할 수 있는 PWA(프로그레시브 웹 앱)로 변환하는 방법을 배우게 됩니다.

먼저 귀하의 웹사이트를 프로그레시브 웹 앱(PWA)으로 전환하겠습니다. 그런 다음 Bubblewrap이라는 Google의 무료 명령줄 도구를 사용하겠습니다. 해당 PWA를 Android 앱에 패키징합니다. 시작해 보겠습니다.

전제조건

이 튜토리얼을 따라가려면 몇 가지 전제 조건이 있습니다:

웹 개발에 대한 기본 지식
귀하의 사이트는 대중에게 공개되어야 하며 해당 소스 코드에 액세스할 수 있어야 합니다.
npm을 사용하여 필요한 도구를 설치할 것이므로 Node.js가 설치되어 있는지 확인하세요.

참고: 이 튜토리얼은 Vite를 기반으로 합니다. 프로젝트이지만 Bubblewrap을 사용한 최종 단계는 모든 웹 프레임워크에서 동일합니다.

PWA란 무엇인가요?
버블랩이란 무엇입니까?
- TWA(신뢰할 수 있는 웹 활동)란 무엇입니까?
- TWA가 신뢰를 확인하는 방법
1단계 – Vite에서 PWA 구성
- 앱 아이콘 만들기
- Vite PWA 플러그인을 설치하세요.
- 플러그인 구성
2단계 - Android 앱 만들기
- 빌드 폴더 생성
- Bubblewrap CLI 설치
- 프로젝트 초기화
- init 명령 문제를 해결해 보겠습니다.
3단계 – 버블랩 질문에 답변
4단계 - 앱 구축
5단계 – TWA 검증 설정
- .well-known 폴더는 무엇인가요?
- Delegate_permission/common.handle_all_urls가 무엇인가요?
6단계(선택 사항) – 인앱 경험 사용자 정의
마무리

PWA란 무엇인가요?

PWA는 프로그레시브 웹 애플리케이션을 의미합니다. , 그리고 그 목표는 귀하의 웹 사이트가 기본 앱처럼 보이고 느껴지도록 만드는 것입니다. 브라우저에서 웹사이트를 방문하여 휴대폰이나 노트북에 다운로드할 수 있는 설치 아이콘이 표시된다면 PWA를 사용한 것입니다.

그러나 그것은 단지 모양과 느낌에 관한 것이 아닙니다. PWA에는 오프라인 작업, 푸시 알림 전송 등과 같은 앱과 유사한 기능도 있습니다.

PWA에는 두 가지 주요 구성요소가 있습니다.

매니페스트 파일은 이름, 아이콘, 시작 URL 등과 같은 앱을 설명합니다.
서비스 워커는 프록시 역할을 하는 백그라운드 JavaScript 파일입니다. 캐싱 및 푸시 알림은 메인 스레드와 별개로 다른 스레드로 실행되는 서비스 파일에 의해 처리됩니다.

이 두 가지 구성 요소가 없으면 브라우저에서 사용자가 로컬로 앱을 다운로드할 수 없습니다.

매니페스트 파일과 서비스 워커는 브라우저의 체크리스트와 같습니다. 웹 사이트를 방문하면 브라우저는 이 두 구성 요소를 모두 찾습니다. 해당 항목이 있고 올바르게 구성된 경우 브라우저는 해당 PWA가 실제 PWA임을 인식하고 '설치' 아이콘을 표시하여 사용자가 앱을 로컬로 다운로드할 수 있도록 합니다. 그렇지 않으면 브라우저는 일반 웹사이트만 볼 수 있으며 설치 옵션을 사용할 수 없습니다.

버블랩이란 무엇인가요?

Bubblewrap은 PWA를 가져와 TWA(신뢰할 수 있는 웹 활동)를 사용하여 Android 앱으로 바꾸는 Google에서 만든 명령줄 도구입니다.

Bubblewrap은 PWA의 매니페스트 파일을 Android 앱 패키지(APK 또는 AAB)로 변환하여 TWA 생성 프로세스를 단순화합니다.

TWA(신뢰할 수 있는 웹 활동)란 무엇인가요?

TWA(신뢰할 수 있는 웹 활동)는 Android 앱 내에서 라이브 웹사이트를 전체 화면으로 표시할 수 있는 최신 Android 기능입니다. 기본적으로 브라우저에서 웹사이트를 실행하지만 앱에서는 브라우저의 주소 표시줄을 표시하지 않습니다. 이렇게 하면 기본 앱처럼 느껴지게 됩니다.

이 전체 화면 기능을 잠금 해제하려면 앱이 "신뢰할 수 있음"이어야 합니다.

여기서 "비밀 악수"가 필요합니다. Android에서는 앱을 만든 사람과 웹사이트를 소유한 사람이 동일한지 확인해야 합니다. 이러한 소유권 증명이 없으면 TWA는 대체 모드로 실행되고 상단에 브라우저 주소 표시줄이 표시되어 기본 앱의 느낌이 손상됩니다.

TWA가 신뢰를 확인하는 방법

이 신뢰는 디지털 자산 링크라는 시스템을 통해 확인됩니다. . 앱의 고유한 디지털 지문이 포함된 특수 파일을 웹사이트에 배치합니다(이 작업은 구현 부분에서 수행함). 사용자가 앱을 열면 Android OS가 이 파일을 확인합니다. 지문이 일치하면 앱에 '신뢰할 수 있는' 상태가 부여되고 주소 표시줄이 제거되며 딥 링크와 같은 다른 기능이 활성화됩니다.

Google의 공식 테스트 도구인 Digital Asset Links Verifier를 사용하여 이 관계를 직접 확인할 수 있습니다.

이제 프로젝트와 도구를 이해했으므로 구축을 시작해 보겠습니다.

1단계 – Vite에서 PWA 구성

첫 번째 단계는 PWA의 두 가지 주요 구성 요소인 매니페스트 파일과 서비스 워커를 추가하는 것입니다. 이를 통해 브라우저는 이를 "설치 가능"으로 인식할 수 있습니다.

이 가이드는 Vite로 구축된 프로젝트를 기반으로 하며, 특별한 플러그인을 사용하여 이 프로세스를 쉽게 만듭니다. 다른 도구를 사용하는 경우 개념은 동일하지만 해당 환경의 특정 단계에 대한 다양한 리소스를 찾아봐야 합니다.

앱 아이콘 만들기

코드를 터치하기 전에 앱 아이콘이 필요합니다. Android에서는 앱 실행기 아이콘(홈 화면에 표시되는 것)과 스플래시 화면(앱이 시작될 때 표시되는 것)에 특정 크기가 필요합니다.

두 가지 기본 크기(192x192)가 필요합니다. 픽셀 및 512x512 픽셀. 이 파비콘 생성기를 사용하여 각각의 크기로 로고를 생성할 수 있습니다. 기본 로고를 업로드하면 필요한 모든 크기가 생성됩니다.

그런 다음 생성된 파일을 다운로드하고 192x192 그리고 512x512 파일을 public에 넣습니다. 프로젝트 폴더입니다.

Bubblewrap을 사용하여 웹사이트를 기본 Android 앱으로 변환 – 단계별 가이드

Vite PWA 플러그인을 설치하세요.

PWA에는 매니페스트 파일과 서비스 워커가 필요합니다. 수동으로 만들 수도 있지만 이 플러그인은 전체 프로세스를 자동화합니다. manifest.json이 자동으로 생성됩니다. 및 service-worker.js 프로젝트를 구축할 때마다 당신을 위해.

npm install vite-plugin-pwa -D

플러그인 구성

이 단계에서는 이 플러그인을 사용하고 앱의 매니페스트를 구성하겠습니다. vite.config.ts 편집 파일. 이 구성은 플러그인에 앱 이름, 사용할 아이콘 등을 알려줍니다.

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",
 },
 ],
 },
 }),
 ]

이제 npm run build을 실행하면 을 사용하면 플러그인이 자동으로 매니페스트 및 서비스 워커 파일을 생성합니다. 완료되면 변경 사항을 배포합니다. 이제 귀하의 웹사이트는 PWA입니다.

2단계 – Android 앱 만들기

이제 귀하의 웹사이트가 PWA이므로 Bubblewrap을 사용하여 이를 Android 앱으로 패키징해 보겠습니다.

빌드 폴더 생성

Android 프로젝트 파일을 위한 전용 폴더를 만듭니다. 프로젝트 루트에 새 폴더를 만듭니다. 내 전화는 android로 전화할게 .

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

이제 생성한 새 폴더로 이동하세요.

Bubblewrap CLI 설치

npm install -g @bubblewrap/cli

프로젝트 초기화

다음으로 init을 실행하세요. 명령. Bubblewrap이 귀하의 라이브 웹사이트에 연결됩니다. manifest.webmanifest을 읽어보세요. Vite가 생성한 파일을 생성하고 해당 정보를 사용하여 기본 Android 프로젝트를 생성합니다.

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

your-website-domain를 바꿔서 명령을 실행하세요. 실제 URL로:

`init` 문제를 해결해 보겠습니다. 명령

init을 실행하면 명령을 실행하려면 Bubblewrap에는 JDK(Java Development Kit)라는 두 가지 주요 소프트웨어 패키지가 필요합니다. 및 Android SDK . 설치를 제안할 것입니다.

JDK 설정:

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

내 경우에는 Bubblewrap이 JDK를 설치하도록 했을 때 프로세스가 파일을 다운로드했지만 "압축 해제" 단계에서 실패했습니다. 동일한 문제가 발생하더라도 걱정하지 마세요! 해결 방법은 수동으로 설치하는 것입니다.

아니요라고 말하세요 프롬프트에.
Adoptium과 같은 소스에서 권장 버전(보통 JDK 17)을 다운로드하세요.
이를 설치하고 JDK의 bin를 포함하도록 시스템의 환경 변수를 설정합니다. 경로. 환경 변수를 설정하는 방법을 잘 모르는 경우 환경 변수 설정 사이트를 확인하세요.
Bubblewrap이 경로를 요청하면 C:\java\jdk-17.0.16.8-hotspot와 같이 직접 제공하세요. .

안드로이드 SDK 설정:

JDK가 성공적으로 설정되면 다음 단계는 Android SDK를 구성하는 것입니다.

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

Android SDK가 없었으므로 예를 선택하여 Bubblewrap에서 이 문제를 처리하도록 했습니다. . 여기서는 아무런 문제가 발생하지 않았습니다.

Android SDK 설정 시 문제가 발생하면 JDK 설정과 마찬가지로 수동으로 설정하고 경로를 제공하세요.

3단계 – 버블랩 질문에 답변

SDK가 설정되면 Bubblewrap은 앱 구성을 위해 여러 가지 질문을 합니다. 이 정보는 twa-manifest.json을 생성하는 데 사용됩니다. 파일은 앱의 청사진입니다.

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

이러한 질문에서 중요한 부분은 키 저장소와 키입니다.

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

참고: 키 저장소와 키의 비밀번호는 동일해야 합니다. 그렇지 않으면 오류가 발생합니다. 이 문제를 참조하세요: 버블랩 문제.

4단계 – 앱 구축

bubblewrap build --universalApk

이 명령은 애플리케이션 빌드를 시작합니다. 여기서는 universalApk 플래그입니다. .apk을 생성합니다 및 .abb . Play 스토어에 애플리케이션을 게시하려면 .abb를 업로드하세요. Play 스토어에 파일을 업로드하세요. 테스트를 위해서는 APK 파일이 필요하므로 이 플래그는 universalApk입니다. 두 파일을 모두 생성합니다. 이 플래그를 제공하지 않으면 .abb만 제공됩니다. .

5단계 – TWA 검증 설정

빌드가 완료되면 APK를 받게 됩니다. 휴대폰으로 전송해서 테스트해 보세요. 앱을 열면 브라우저 주소 표시줄이 표시됩니다. 이는 귀하의 앱과 웹사이트 사이에 아직 '신뢰'가 설정되지 않았기 때문입니다. 지금 바로 수정해 보겠습니다.

프런트엔드 프로젝트에서 public으로 이동합니다. 폴더, .well-known이라는 새 폴더를 만듭니다. , 그 안에 assetlinks.json이라는 파일을 만듭니다. .

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

`.well-known`가 무엇인가요? 폴더?

잘 알려진 폴더는 프로토콜 구성을 정의하는 파일을 저장하는 데 사용됩니다. 외부 소스에서 웹 사이트의 유효성 검사를 찾는 데 사용되기 때문입니다. 우리의 경우 앱은 웹사이트에서 잘 알려진 폴더를 확인하고 유효성을 확인합니다.

다음을 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`이 무엇인가요? ?

이는 도메인 대신 앱의 모든 링크를 여는 특수 플래그입니다. 쉽게 말하면 딥링크 역할을 합니다. 앱을 설치한 후 WhatsApp이나 다른 곳에서 웹사이트 링크를 클릭하면 브라우저에서 열리지 않고 딥링크 역할을 하면서 앱이 열립니다.

package_name 필드는 packageId이어야 합니다. , twa-manifest.json의 Android 빌드 폴더에서 가져올 수 있습니다. .

이제 지문을 채취하세요. 이렇게 하려면 다음 명령을 실행하세요:

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

별칭 이름은 생성한 값이어야 합니다. 이 명령을 입력하면 키 저장소 비밀번호를 묻습니다. 이를 입력하면 SHA256를 얻게 됩니다. 지문. 이를 복사하여 assetslinks.json에 붙여넣으세요. sha256_cert_fingerprints의 파일 배열. 이제 이러한 변경 사항을 프로덕션에 적용하세요. 디지털 자산 링크에서 유효성 검사를 확인할 수 있습니다

그게 다야! 이제 앱을 설치하고 테스트할 수 있습니다.

6단계(선택사항) – 인앱 경험 맞춤설정

이제 웹사이트와 모바일 앱에서 사용자에게 서로 다른 콘텐츠를 보여주고 싶은 경우도 있을 것입니다. 우리가 그렇게 할 수 있나요? 그렇습니다!

Android 빌드 폴더의 twa-manifest.json , startUrl라는 필드가 있습니다. . 그렇지 않다면 추가하고 "startUrl": "/?twa=true" 값을 추가하세요. . startUrl 진입점이다. twa=true 값의 쿼리 매개변수가 있습니다. .

bubblewrap build --universalApk로 빌드를 다시 실행하세요. .

이제 앱을 열면 항목 URL이 yourwebsitedomain.com/?twa=true인 앱이 열립니다. .

프런트엔드에서:

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>
 )}

위 코드에서는 twa=true를 확인합니다. URL의 쿼리 매개변수입니다. 존재하는 경우 해당 정보를 로컬 저장소에 저장한 다음 조건부로 사용자를 위해 콘텐츠를 렌더링합니다.

그게 다야. 앱을 만들었습니다.

이름, 색상, 스플래시 화면을 변경하려면 twa-manifest.json에서 변경할 수 있습니다. 그리고 빌드를 다시 실행하세요.

마무리

Bubblewrap은 Android 전용입니다. 앱이 크로스 플랫폼을 지원하길 원한다면 Capacitor와 같은 다른 플랫폼이 있습니다. 이에 대해서는 다른 글에서 다루겠습니다.

그런데 제가 Bubblewrap을 사용하여 만든 앱인 Stranger Talk를 확인해 보세요.

틀린 부분이 있거나 궁금한 점이 있으면 LinkedIn이나 Instagram으로 연락주세요.

읽어주셔서 감사합니다!

무료로 코딩을 배우세요. freeCodeCamp의 오픈 소스 커리큘럼은 40,000명 이상의 사람들이 개발자로 취업하는 데 도움을 주었습니다. 시작하세요