Polar Games
가이드

앱에 게임 추가하기: WebView로 HTML5 게임 실행

이미 운영 중인 Android·iOS 앱에 완성된 HTML5 게임을 넣는 방법: 로컬 또는 호스팅 파일, 저장, 뒤로 가기 버튼, 라이선스.

앱 WebView 안에서 실행할 수 있는 HTML5 게임, 채굴 퍼즐 Deepforge 아트워크

앱에 게임을 추가하는 데 게임 엔진은 필요 없습니다. 필요한 것은 WebView입니다. Android와 iOS가 네이티브 화면 안에 웹 콘텐츠를 보여 주려고 제공하는 컴포넌트입니다. 완성된 HTML5 게임 폴더를 앱 패키지 안이나 자사 HTTPS 서버에 두고 WebView가 그 index.html을 열게 하면, 브라우저 버전과 같은 코드로 돌아가는 게임 섹션이 앱에 생깁니다.

이 가이드는 이미 앱(리테일 앱, 은행, 학교 플랫폼, 클럽, 미디어 브랜드)을 운영하면서 스토어에 새 앱을 내는 대신 기능으로 인앱 게임을 넣고 싶은 팀을 위한 것입니다. 로컬 파일과 호스팅 파일 중 선택, 잘못 설정하면 게임이 망가지는 WebView 설정, 진행 저장, 뒤로 가기 버튼, 적합한 템플릿, 라이선스가 앱을 세는 방식을 다룹니다. 플랫폼 세부 내용은 2026년 10월 30일에 확인한 Android Developers와 Apple Developer 문서를 기준으로 합니다.

앱에 게임 추가하기: WebView 방식의 작동 원리

WebView는 브라우저 껍데기를 뺀 브라우저 엔진입니다. 네이티브 코드가 WebView를 만들고, 크기와 설정을 정하고, 무엇을 불러올지 지시합니다. Android에서는 WebView 클래스, iOS에서는 WKWebView입니다. HTML5 게임은 차이를 모릅니다. Chrome이나 Safari에서처럼 페이지, 캔버스, 저장소를 볼 뿐입니다.

그래서 인앱 게임에 이 방식이 많이 쓰입니다. 게임 팀은 HTML, CSS, JavaScript로 작업하고, 앱 팀은 화면 하나와 설정 몇 가지를 추가하며, 같은 게임 폴더를 웹사이트에도 올릴 수 있습니다. 계획할 요소는 세 가지입니다.

  1. 파일 위치: 앱 안에 포함하거나 HTTPS 서버에서 제공.
  2. WebView 설정: JavaScript, 저장소, 게임이 실행되는 주소.
  3. 게임과 앱의 소통: 열기, 일시정지, 뒤로 가기 버튼, 닫기.

저희 템플릿은 이 구조에 맞습니다. 각 템플릿에는 index.html이 든 game/ 폴더가 준비되어 있고, 정적 호스팅용이라 게임 자체에는 PHP나 데이터베이스가 필요 없습니다. 다만 네이티브 부분은 어느 템플릿에도 없습니다. 모든 에디션이 네이티브 앱이나 스토어용 빌드를 'Not included in this edition'에 적어 두었으므로, WebView 화면은 귀사 팀이 만들거나 저희가 별도로 견적을 드리는 작업입니다.

HTML5 게임 템플릿 둘러보기

로컬 또는 호스팅: 게임 파일을 어디에 둘까

로컬: 게임을 앱 안에 포함

Android의 인앱 콘텐츠 로딩 가이드에 따르면, 앱에 컴파일된 웹 콘텐츠는 인터넷 연결이 필요 없고 사용자의 데이터를 쓰지 않습니다. game/ 폴더를 앱의 assets에 복사하고 거기서 불러오면 됩니다. 대가는 용량입니다. 게임만큼 다운로드 크기가 늘고, 게임을 업데이트할 때마다 스토어 심사를 거치는 새 앱 버전이 필요합니다.

호스팅: 앱이 서버에서 게임을 불러옴

WebView가 자사 도메인의 HTTPS 주소를 엽니다. 새 앱 빌드 없이 게임을 업데이트할 수 있고 앱은 가볍게 유지됩니다. 대가는 연결이 필요하다는 점이며, 네트워크가 느리면 첫 로딩도 느려집니다.

Apple에는 별도 규칙이 있습니다. App Review Guidelines 4.7은 바이너리에 포함되지 않은 HTML5·JavaScript 미니 게임을 다룹니다. 조건 중에는 Apple의 허가 없이 그 소프트웨어에 네이티브 플랫폼 API를 확장하거나 노출하지 말 것, 제공하는 소프트웨어의 목록을 유니버설 링크와 함께 제공할 것이 있습니다. iOS에서 호스팅 방식을 고르기 전에 4.7 전문을 읽어 보세요.

  • 앱 용량: 로컬은 게임 용량만큼 늘고, 호스팅은 거의 늘지 않습니다.
  • 업데이트: 로컬은 앱 출시가 필요하고, 호스팅은 업로드하면 바로 바뀝니다.
  • 연결: 로컬은 설치 후 네트워크 없이 시작할 수 있고, 호스팅은 연결이 필요합니다.
  • 심사: 로컬 게임은 앱과 함께 심사되고, iOS의 호스팅 게임은 가이드라인 4.7의 적용을 받습니다.

게임의 성패를 가르는 Android WebView 설정

'게임이 흰 화면만 보인다'는 문의 대부분은 세 가지 기본값에서 나옵니다. 세 가지 모두 Android Developers에 문서화되어 있습니다.

  1. JavaScript가 꺼져 있습니다. WebView 가이드에 따르면 WebView에서 JavaScript는 기본으로 비활성화되어 있습니다. 모든 HTML5 게임에 필요하니 WebSettings에서 켜세요.
  2. 저장소가 꺼져 있습니다. WebSettings 레퍼런스에 따르면 setDomStorageEnabled의 기본값은 false입니다. localStorage에 진행 상황을 저장하는 게임은 이 값을 켜야 하며, 그렇지 않으면 매번 처음부터 시작합니다.
  3. file://은 잘못된 주소입니다. Android의 인앱 콘텐츠 가이드는 file:// URL이 fetch()나 XMLHttpRequest 같은 API를 쓸 수 없는 불투명 출처(opaque origin)라고 설명하며, 파일 접근 우회 설정을 켜지 말라고 권합니다. 저희 상품 페이지도 게임 쪽에서 같은 말을 합니다. Gridspark와 Twirldrop 같은 에디션은 file://에서 실행되지 않습니다.

세 번째 문제의 해결책은 AndroidX Webkit 라이브러리의 WebViewAssetLoader입니다. 앱 assets의 파일을 HTTPS 주소로 제공하며, Android 공식 예제는 https://appassets.androidplatform.net/assets/index.html을 불러옵니다. 게임 입장에서는 일반 웹사이트처럼 보이므로 ES 모듈, fetch, 저장소가 서버에서와 똑같이 작동합니다.

iOS: WKWebView, 로컬 파일, 데이터 저장소

iOS의 컴포넌트는 WKWebView입니다. Apple은 로컬 콘텐츠용으로 loadFileURL(_:allowingReadAccessTo:)를 문서화하고 있습니다. 두 번째 인수는 WebKit이 읽을 수 있는 파일이나 폴더이며, 폴더를 넘기면 페이지가 주변 파일을 불러올 수 있습니다.

저희 에디션은 file://로 여는 것을 지원하지 않으므로 이 경로는 꼼꼼히 테스트하거나 피하세요. Apple은 WebKit이 처리하지 않는 URL 스킴으로 리소스를 불러오는 프로토콜인 WKURLSchemeHandler도 제공하므로, 앱이 자체 스킴으로 게임 폴더를 제공할 수 있습니다. Capacitor는 이를 대신 처리하며, iOS의 기본 스킴은 capacitor입니다.

저장소는 WKWebsiteDataStore에 있습니다. Apple 문서에 따르면 기본 저장소는 웹사이트 데이터를 디스크에 영구 저장하고, 비영구 저장소는 데이터를 메모리에만 두며 비공개 브라우징용입니다. 팀원이 비영구 저장소를 설정하면 앱을 닫을 때마다 플레이어의 진행 상황이 사라집니다.

iOS에는 시스템 뒤로 가기 버튼이 없으므로 게임 화면에 나가는 방법을 따로 두어야 합니다. 네이티브 바의 닫기 버튼, 또는 게임이 메시지 핸들러로 호출하는 버튼입니다.

앱 안에서 진행 상황 저장

저희 게임은 서버가 아니라 플레이어의 브라우저 저장소에 저장합니다. Solitaire Links와 Deepforge는 페이지에 분명히 적고 있습니다. 진행 상황은 localStorage에 저장되며 계정이나 클라우드 동기화는 없습니다. 앱 안에서는 세 가지 결과가 따릅니다.

  • 주소가 저장 데이터의 일부입니다. 브라우저 저장소는 출처(origin)에 속합니다. 테스트 도메인에서 appassets.androidplatform.net으로 옮기는 것처럼 스킴이나 호스트를 바꾸면 플레이어는 처음부터 시작합니다. 주소는 한 번만 정하세요.
  • 저장 키가 저장 데이터의 일부입니다. Tenguin 상품 페이지는 운영 중인 게임의 저장 키를 바꾸지 말라고 안내합니다. 바꾸면 플레이어가 진행 상황을 잃습니다. 여러 TypeScript 에디션은 저장 키를 brand.ts에 둡니다. 출시 전에 의도적으로 바꾸고, 출시 후에는 절대 바꾸지 마세요.
  • 앱 데이터를 지우면 게임도 지워집니다. 앱을 삭제하거나 앱 저장소를 비우면 브라우저를 비울 때처럼 저장 데이터가 사라집니다.

여러 기기에서 진행 상황이 이어져야 한다면 서버 기능이 필요한데, 저희 에디션에는 포함되어 있지 않습니다. 모든 에디션이 클라우드 저장이나 계정을 미포함으로 적고 있습니다. 가장 시작하기 좋은 것은 Deepforge입니다. 상품 페이지에 따르면 메뉴에서 저장 데이터를 내보내고 가져올 수 있고, 호스트 페이지가 일시정지, 재개, 저장 데이터 읽기, 저장 이벤트 수신을 할 수 있는 작은 window.DeepForge API가 있습니다.

Deepforge와 호스트 페이지 API 보기

뒤로 가기 버튼, 일시정지, 게임 나가기

HTML5 게임은 대개 단일 페이지입니다. 뒤로 가기 버튼이 WebView의 방문 기록을 거슬러 가는 Android에서는 이 점이 중요합니다. Android WebView 가이드는 canGoBack()을 확인하고 goBack()을 호출하거나 시스템이 이벤트를 처리하게 하는 패턴을 보여 주며, AndroidX에서는 같은 로직을 OnBackPressedDispatcher에 등록합니다. 단일 페이지 게임은 기록이 비어 있는 경우가 많아, 뒤로 가기를 누르면 레벨 도중에 게임 화면이 바로 닫힙니다.

뒤로 가기 동작을 정하고 문서로 남기세요.

  • 첫 번째 누름은 게임의 일시정지 메뉴를 열고, 두 번째 누름은 게임 화면을 나갑니다.
  • 또는 게임이 저장한 뒤 뒤로 가기는 항상 나갑니다. 모든 에디션이 로컬에 저장하지만, 레벨 끝에 저장하는지 플레이 중에 저장하는지 확인하세요.
  • 앱이 백그라운드로 가면 게임을 일시정지하세요. 그러지 않으면 앱의 다른 화면 뒤에서 타이머가 계속 돌아갑니다.

저희 에디션에는 앱 브리지가 없습니다. 일부는 페이지 쪽 진입점을 제공합니다. Gridspark와 Ricopop에는 설정 파일에서 켜고 끌 수 있는 '탭하여 시작' 화면과 전체 화면 버튼이 있고, Deepforge는 일시정지와 재개를 페이지에 노출합니다. 레벨이 끝날 때 네이티브 코드에 메시지를 보내는 것 같은 나머지는 귀사 팀이나 저희 견적 작업으로 추가하는 소스 코드의 작은 변경입니다.

빌드 단계 없는 순수 JavaScript 게임 Gridspark 보기

라이선스: 게임 하나, 앱 하나, 먼저 물어볼 것

저희 약관은 본인 또는 고객 한 곳을 위해 최종 제품 하나에 에디션을 사용할 수 있는 영구·비독점 라이선스를 부여합니다. 게임 섹션이 들어간 귀사 앱이 그 최종 제품입니다. 플레이어는 무료로 또는 광고 수익화를 통해 이용할 수 있습니다. 코드, 그래픽, 오디오를 수정할 수 있고, 화이트 라벨이 허용되어 귀사 브랜드가 저희 브랜드를 대신합니다.

세 가지 상황은 좀 더 살펴봐야 합니다.

  • 여러 앱. 같은 게임을 고객 앱 세 개에 넣는 에이전시는 라이선스 세 개가 필요합니다. 한 주문에 여러 템플릿을 사면 묶음 할인이 적용됩니다. 2개 5%, 3개 10%, 4개 15%, 5개 이상 20%.
  • 같은 앱의 Android·iOS 버전. 라이선스 하나로 그 게임을 Google Play와 App Store를 포함해 원하는 곳 어디에나 게시할 수 있습니다. 최종 제품당 라이선스 하나라는 원칙은 같습니다.
  • 다른 개발자용 게임 SDK. 약관은 개발자 대상의 다른 제품 안에 템플릿이나 코드를 재배포하는 것을 금지합니다. 다른 앱 제작사에 판매하는 게임 모듈이 바로 그런 제품입니다.

앱에서 게임 섹션을 유료로 하거나 그 안에서 아이템을 판매한다면 이 경우에도 먼저 문의해 주세요. 약관은 무료 이용과 광고 수익화를 명시하고 있으며, 여러 에디션이 실제 결제를 미포함으로 적고 있습니다. iOS 가이드라인 3.1.1은 게임 레벨을 포함한 기능이나 콘텐츠 잠금 해제에 인앱 결제를 사용해야 한다고 규정합니다.

기업용 라이선스, 인보이스, 견적

자주 묻는 질문

Android나 iOS 앱 안에 HTML5 게임을 넣을 수 있나요?

네. 게임 폴더를 앱에 번들하거나 HTTPS 서버에서 WebView(Android는 WebView, iOS는 WKWebView)로 불러오면 됩니다. JavaScript와 저장소를 켜고, file:// 대신 HTTPS 형식의 주소로 파일을 제공하세요.

앱 안에서 게임이 오프라인으로 작동하나요?

파일을 번들하고 에디션이 네트워크에서 아무것도 불러오지 않을 때만 가능합니다. 여러 에디션이 그림, 오디오, 폰트를 로컬에 두지만, Ricopop 페이지는 연결이 필요하다고 밝힙니다. 약속하기 전에 비행기 모드로 테스트하세요.

앱을 업데이트하면 플레이어의 진행 상황이 사라지나요?

주소와 저장 키가 그대로라면 사라지지 않습니다. 저장 데이터는 해당 출처의 WebView 저장소에 있습니다. 스킴, 호스트, 저장 키를 바꾸면 모두 처음부터 시작합니다.

앱에 라이선스가 몇 개 필요한가요?

최종 제품당 하나입니다. 게임 하나가 든 앱 하나는 라이선스 하나, 같은 게임을 고객 세 곳의 앱에 넣으면 세 개입니다. 같은 앱을 Google Play와 App Store에 내는 데는 두 번째 라이선스가 필요 없습니다. 라이선스를 받은 게임은 원하는 곳 어디에나 게시할 수 있습니다.

다음 단계

게임을 고르고 휴대폰으로 데모를 플레이한 다음, 'Not included in this edition' 목록과 매뉴얼의 저장 관련 장을 읽어 보세요. 게임 화면을 앱에 직접 넣어 주기를 원하시면 앱, 플랫폼, 원하는 게임을 보내 주세요. 범위, 가격, 일정을 회신해 드립니다.

모든 게임 템플릿 보기

앱 통합 견적 문의