웹사이트를 플레이스토어 앱으로 감쌀 때 막히는 곳 (TWA, Bubblewrap, 윈도우 빌드와 주소창)

이미 운영 중인 웹사이트를 TWA로 감싸 구글 플레이스토어 앱으로 올릴 때, 윈도우에서 Bubblewrap 빌드가 막히는 지점과 앱 상단에 주소창이 남는 문제를 정리한 글입니다.

모바일 웹으로 만든 서비스를 플레이스토어에도 올리고 싶을 때 가장 가벼운 방법이 TWA(Trusted Web Activity) 입니다. 앱 안에 웹사이트를 크롬으로 전체 화면으로 띄우는 방식이라, 코드를 새로 짤 필요 없이 사이트 그대로 앱이 됩니다.

구글이 만든 Bubblewrap 이라는 도구를 쓰면 설정 몇 가지로 플레이스토어용 AAB 파일까지 만들어 줍니다. 문서대로라면 명령 몇 줄인데, 윈도우에서 해 보니 중간중간 설명에 없는 곳에서 막혔습니다.

- 빌드가 gradlew.bat 를 못 찾는다면 NoDefaultCurrentDirectoryInExePath 환경 변수를 의심한다

- 서명 단계에서 jarsigner 를 못 찾으면 JDK의 bin 폴더를 PATH에 넣는다

- 앱 상단에 주소창이 보이면 사이트와 앱의 연결(assetlinks)이 안 된 것이다

- 플레이에 올린 뒤에는 구글이 다시 서명한 키의 지문도 assetlinks에 추가해야 한다

1. TWA가 동작하는 조건

TWA는 "이 앱과 이 웹사이트는 같은 주인"이라는 것을 양쪽에서 증명해야 주소창 없이 열립니다. 앱 쪽은 빌드할 때 사이트 주소를 넣고, 사이트 쪽은 /.well-known/assetlinks.json 파일에 앱 패키지 이름과 서명 키 지문을 올려 둡니다.

그 밖에 사이트는 HTTPS여야 하고, 아이콘과 이름을 담은 웹 앱 매니페스트가 있어야 합니다. Bubblewrap은 이 매니페스트를 읽어 앱 이름, 아이콘, 시작 주소를 채워 줍니다.

2. 윈도우에서 gradlew.bat를 못 찾는다

bubblewrap build 를 실행했더니 프로젝트 폴더에 분명히 있는 gradlew.bat 를 찾을 수 없다는 오류가 났습니다. 파일도 있고 경로도 맞는데 실행만 안 되는 상황이었습니다.

원인은 NoDefaultCurrentDirectoryInExePath 라는 환경 변수였습니다. 이 값이 설정돼 있으면 윈도우 명령 프롬프트가 현재 폴더에 있는 실행 파일을 찾지 않습니다. 보안상 일부 도구나 개발 환경이 이 값을 켜 두는데, Bubblewrap은 gradlew.bat 를 경로 없이 이름만으로 부르기 때문에 여기서 막힙니다.

빌드하는 셸에서만 이 변수를 지우면 해결됩니다. 시스템 전체 설정을 바꿀 필요는 없고, 빌드 명령 앞에서 그 세션에서만 지우는 편이 안전합니다.

3. 서명 단계에서 jarsigner가 없다

빌드가 끝나갈 무렵 AAB에 서명하는 단계에서 jarsigner 를 찾지 못해 멈췄습니다. Bubblewrap이 JDK를 받아 두긴 했지만, 서명 도구는 PATH에서 찾기 때문입니다.

JDK 폴더 안의 bin 을 PATH 앞쪽에 넣어 주면 됩니다. 키스토어 비밀번호도 BUBBLEWRAP_KEYSTORE_PASSWORD, BUBBLEWRAP_KEY_PASSWORD 환경 변수로 넘기면 빌드 중에 묻지 않아서, 위 그림처럼 한 번에 끝까지 돌릴 수 있습니다.

안드로이드 SDK를 직접 받아 둔 경우에는 Bubblewrap이 기대하는 폴더 구조와 다르면 SDK를 못 알아보는 일도 있었습니다. 경로를 알려 줬는데도 SDK가 없다고 하면, 안내된 폴더 배치(tools/bin 아래 명령줄 도구)와 실제 구조를 먼저 비교해 봐야 합니다.

4. 앱 위에 주소창이 보인다

앱을 설치해서 열었는데 화면 위에 크롬 주소창이 그대로 붙어 있다면 TWA가 아니라 일반 크롬 탭처럼 열린 것입니다. 사이트와 앱의 연결 확인에 실패했다는 뜻입니다.

assetlinks.json 에는 앱을 서명한 키의 SHA-256 지문이 들어가야 합니다. 그리고 구글이 제공하는 확인 API에 사이트 주소, 패키지 이름, 지문을 넣어 보면 연결이 됐는지 linked 값으로 바로 알려 줍니다. 앱을 다시 빌드하지 않고 사이트 파일만 고쳐서 확인할 수 있어 편합니다.

5. 플레이에 올리면 키가 바뀐다

직접 빌드한 앱으로 확인할 때는 잘 되다가, 플레이스토어에서 받은 앱만 주소창이 다시 보이는 경우가 있습니다. 플레이 앱 서명을 쓰면 구글이 업로드된 앱을 구글이 관리하는 키로 다시 서명해서 배포하기 때문입니다.

그래서 첫 업로드 뒤에는 플레이 콘솔의 앱 무결성 메뉴에서 앱 서명 키의 SHA-256 지문을 확인해 assetlinks.json 에 추가해야 합니다. 업로드 키 지문과 앱 서명 키 지문을 둘 다 넣어 두면, 직접 설치한 앱과 스토어에서 받은 앱이 모두 주소창 없이 열립니다.

6. 정리

TWA는 웹사이트를 그대로 앱으로 만들 수 있는 가장 가벼운 방법이지만, 윈도우에서는 NoDefaultCurrentDirectoryInExePath 와 jarsigner 경로 같은 환경 문제에서 먼저 막히기 쉽습니다. 빌드하는 셸에서만 환경을 정리해 주면 대부분 풀립니다.

그다음은 주소창입니다. 사이트의 assetlinks.json 에 업로드 키와 플레이 앱 서명 키 지문을 모두 넣고, 확인 API로 linked 가 나오는지 보면 앱을 다시 빌드하지 않고도 연결 상태를 점검할 수 있습니다.

여기까지 웹사이트를 TWA로 감싸 플레이스토어 앱으로 만들 때 막히는 곳에 대해서 작성해봤습니다. 여기까지 읽어주셔서 감사합니다!