MiniApp 패키징

MiniApp 루트 디렉터리는 MiniApp 패키지 파일 시스템의 기본 디렉터리입니다.

루트 디렉터리는 MiniApp 패키지에서 MiniApp의 전역 데이터와 생명주기 관리에 관한 정보를 포함하는 여러 예약 파일을 보관하며, 여기에는 다음이 포함됩니다:

manifest.json

MiniApp 매니페스트는 MiniApp의 전역 구성을 담당하는 JSON 문서입니다. 매니페스트 파일은 MiniApp Manifest 명세 [MINIAPP-MANIFEST]에 따라, 페이지의 경로와 라우트 및 MiniApp의 창 구성(예: 탐색 표시줄 스타일, 배경 이미지, 배경색, 페이지 제목 등)을 포함하여 MiniApp의 설정을 나타내는 필수 및 선택 속성의 모음을 포함합니다.

app.css

이 파일은 애플리케이션의 기본 스타일시트로, 개발자가 MiniApp 내 페이지의 공통 스타일과 모양 및 느낌의 측면을 정의하는 곳입니다. 비어 있을 MAY 있습니다.

app.js

이 스크립트 문서는 MiniApp의 기본 서비스 로직을 가지며, MiniApp Lifecycle [MINIAPP-LIFECYCLE]에 따른 MiniApp 실행, 표시 및 숨김 이벤트의 관리를 포함하여 MiniApp 생명주기의 필수 구성과 제어를 포함합니다.

pages 디렉터리는 MiniApp 페이지의 표시와 사용자 상호작용을 위한 파일 집합을 포함합니다.

MiniApp 페이지는 고유한 파일명(예: intro)과 특정 확장자로 식별되는 리소스 집합으로 정의됩니다. 확장자는 애플리케이션의 비즈니스 로직 (예: intro.js), 구조와 콘텐츠(예: intro.html), 범위가 지정된 스타일시트 (예: intro.css)와 같은 리소스 유형을 정의합니다.

개발자는 필요에 따라 다른 유형의 리소스를 포함할 MAY 있습니다. 또한, 페이지와 관련된 파일(동일한 파일명으로 식별됨)은 각 페이지별 특정 하위 디렉터리에 구성하거나 pages 디렉터리 바로 아래에 저장할 MAY 있습니다.

/
|___manifest.json
|___app.js
|___app.css
|___pages/
        |___detail.js
        |___detail.html
        |___detail.css
        |___list.js
        |___list.html
        |___list.css

/
|___manifest.json
|___app.js
|___app.css
|___pages/
        |___detail/
                |___detail.js
                |___detail.html
                |___detail.css
        |___list
                |___list.js
                |___list.html
                |___list.css

• .html 리소스는 MiniApp 페이지의 구조와 콘텐츠를 정의합니다. HTML을 기반으로, 이 유형의 파일에 대한 구문, 구조 및 기타 요구사항은 HTML 리소스 섹션에서 정의됩니다.
• .css 리소스는 MiniApp 페이지의 스타일시트를 정의합니다. 이 유형의 리소스에 대한 구문, 구조 및 기타 요구사항은 CSS 리소스 섹션에서 정의됩니다.
• .js 리소스는 MiniApp 페이지의 비즈니스 로직을 포함하며, 여기에는 애플리케이션 동작에 필요한 함수, 데이터 및 기타 구성 측면이 포함됩니다. 이 유형의 리소스는 MiniApp Lifecycle 명세 [MINIAPP-LIFECYCLE]에서 정의한 대로 MiniApp 페이지의 설정 및 생명주기 관리를 담당합니다. 이러한 유형의 파일의 구문과 형식은 스크립팅 리소스 섹션에서 정의됩니다.

선택적 common 디렉터리는 MiniApp의 페이지에서 접근할 수 있는 구성요소, 멀티미디어 리소스, 문서 및 라이브러리와 같은 리소스를 포함합니다. 이 디렉터리의 내부 구조는 유연하므로, 이러한 공통 리소스는 필요에 따라 사용자 지정 하위 디렉터리에 구성하고 서로 다른 이름 규칙을 사용할 MAY 있습니다.

선택적 i18n 디렉터리는 루트 디렉터리의 하위 디렉터리로, MiniApp 패키지의 현지화 리소스를 포함합니다.

i18n 디렉터리는 MiniApp 콘텐츠의 국제화를 지원하기 위한 다국어 현지화 리소스를 포함합니다. 이 디렉터리에 있는 각 .json 문서의 파일명은 [BCP47]에서 정의한 Language-Tag 표기법을 따르며, 해당 특정 언어에 대한 구성을 나타냅니다.

i18n 디렉터리는 MiniApp이 지원하는 언어 또는 로케일 수만큼 많은 현지화 리소스를 포함할 MAY 있습니다. 이러한 파일의 형식은 현지화 리소스 섹션에서 정의됩니다.

MiniApp 패키지 안의 모든 파일명과 경로명은, Internationalization Best Practices for Spec Developers에서 명시한 것처럼 운영체제의 잠재적 제한을 수용하고 대부분의 플랫폼 및 파일 시스템과의 상호운용성을 촉진하기 위해 다음 제한사항을 준수해야 MUST 합니다.

• 파일명과 파일 경로는 대소문자를 구분합니다.
• 파일명과 파일 경로는 UTF-8 [Unicode]로 인코딩되어야 MUST 합니다.
• 파일명은 길이가 255바이트를 초과하지 않는 것이 SHOULD NOT 좋습니다.
• 경로명은 길이가 65535바이트를 초과하지 않는 것이 SHOULD NOT 좋습니다.
• 파일명과 경로명은 다음 [Unicode] 포인트를 사용해서는 MUST NOT 안 됩니다:
  • " [U+0022 QUOTATION MARK]
  • * [U+002A ASTERISK]
  • / [U+002F SOLIDUS]
  • : [U+003A COLON]
  • < [U+003C LESS-THAN SIGN]
  • > [U+003E GREATER-THAN SIGN]
  • \ [U+005C REVERSE SOLIDUS]
  • | [U+007C VERTICAL LINE]
  • U+007F DEL
  • U+E0001 LANGUAGE TAG
  • U+E007F CANCEL TAG
  • 다음 범위의 코드 포인트:
    • C0 Controls [U+0000...U+001F]
    • C1 Controls [U+0080...U+009F]
    • Private Use [U+E000...U+F8FF]
    • Specials [U+FFF0...U+FFFF]
    • Supplementary Private Use [U+F0000...U+FFFFF]
    • Supplementary Private Use [U+100000...U+10FFFF]
  • . [U+002E FULL STOP]
  • 모든 Unicode 비문자 코드 포인트, 구체적으로:
    • 기본 다국어 평면의 32개 연속 문자(U+FDD0 … U+FDEF)
    • 기본 다국어 평면의 마지막 두 코드 포인트(U+FFFE 및 U+FFFF)
    • 보조 평면 끝의 마지막 두 코드 포인트(U+1FFFE, U+1FFFF … U+EFFFE, U+EFFFF)

동일한 디렉터리 안의 모든 파일명은 Unicode 정규 정규화 [UAX15]와 그 이후의 전체 대소문자 폴딩 [Unicode]에 따라 고유해야 MUST 합니다. (자세한 내용은 Unicode Canonical Case Fold Normalization Step [CHARMOD-NORM]를 참조하십시오.)

HTML 리소스는 MiniApp 페이지와 그 사용자 인터페이스를 정의하기 위한 마크업과 정보를 포함하는 문서이며, 여기에는 구조, 시각적 구성요소 및 상호작용 요소가 포함됩니다.

HTML 리소스는 다음 기준을 모두 충족해야 MUST 합니다:

구문 및 콘텐츠

HTML 리소스는 [HTML]에 정의된 HTML 구문을 사용해야 MUST 합니다.

파일명

HTML 리소스는 단일 MiniApp 페이지를 식별하고, 존재하는 경우 해당 페이지의 대응하는 CSS 리소스 및 스크립팅 리소스와 일치하는 고유한 파일명을 갖는 것이 SHOULD 좋습니다.

파일 확장자

HTML 리소스는 파일 확장자 .html을 사용하는 것이 SHOULD 좋습니다.

CSS 리소스는 MiniApp 페이지의 렌더링과 외형을 설명하는 스타일시트입니다. CSS 리소스는 전역적일 수 있어 MiniApp의 모든 페이지에 영향을 미치거나(즉, 루트 디렉터리의 app.css), 특정 페이지에만 영향을 미치는 로컬 범위를 가질 수 있습니다.

이 명세는 [CSS-SNAPSHOT]에 정의된 CSS 모듈을 지원합니다.

CSS 리소스는 다음 기준을 모두 충족해야 MUST 합니다:

구문 및 콘텐츠

CSS 리소스는 [CSS-SNAPSHOT]에 설명된 CSS의 구문과 정의를 사용하여 설명된 것을 따라야 MUST 합니다.

파일명

MiniApp의 모든 페이지에 영향을 미치는 전역 CSS 리소스는 app.css라는 이름을 가져야 하고 루트 디렉터리에 저장되어야 MUST 합니다.

페이지와 연결된 로컬 CSS 리소스는 MiniApp 페이지를 식별하고, 존재하는 경우 대응하는 HTML 리소스 및 스크립팅 리소스와 일치하는 고유한 파일명을 갖는 것이 SHOULD 좋습니다.

파일 확장자

CSS 리소스 파일명은 파일 확장자 .css를 사용하는 것이 SHOULD 좋습니다.

스크립팅 리소스는 애플리케이션의 비즈니스 로직과 기능을 제어하고, 상호작용성을 추가하며 MiniApp의 생명주기를 관리하기 위한 스크립트 요소와 데이터를 포함하는 문서입니다. 모든 페이지에서 사용할 수 있는 데이터와 함수를 포함하고 애플리케이션의 생명주기를 제어하기 위한 특정 로직을 포함하는 전역 스크립팅 리소스(즉, 루트 디렉터리의 app.js)가 있습니다. 각 MiniApp 페이지는 구체적인 페이지로 범위가 제한된 특정 스크립팅 리소스를 연결할 MAY 있습니다.

스크립팅 리소스는 다음 기준을 모두 충족해야 MUST 합니다:

구문 및 콘텐츠

스크립팅 리소스는 ECMAScript 명세 [ECMA-262]의 요구사항을 준수해야 MUST 합니다.

전역 스크립팅 리소스는 app.js라는 이름을 가져야 하고 루트 디렉터리에 저장되어야 MUST 합니다.

페이지와 연결된 로컬 스크립팅 리소스는 MiniApp 페이지를 식별하고, 존재하는 경우 대응하는 HTML 리소스 및 CSS 리소스와 일치하는 고유한 파일명을 갖는 것이 SHOULD 좋습니다.

파일 확장자

스크립팅 리소스 파일명은 파일 확장자 .js를 사용하는 것이 SHOULD 좋습니다.

MiniApp 현지화 리소스는 MiniApp의 국제화 메커니즘의 일부로 현지화된 콘텐츠를 포함한 MiniApp 패키지의 문서입니다.

다국어 MiniApp은 시스템 로케일 또는 사용자의 언어 기본 설정에 따라 콘텐츠를 렌더링하기 위해 사용자 에이전트가 현지화 과정에서 사용할 여러 현지화 리소스를 가질 MAY 있습니다. 이러한 리소스는 현지화 가능한 용어나 표현의 고유 식별자(키)와 구체적인 언어에서의 표현(값)을 포함하는 키-값 쌍의 JSON 객체를 포함합니다.

{
    "title": "멋진 MiniApp",
    "about": "이 MiniApp 정보",
    "intro-page": {
        "title" : "소개",
        "main" : "이것은 페이지의 본문입니다"
    }
}

현지화 리소스는 다음 기준을 모두 충족해야 MUST 합니다:

파일 확장자

현지화 리소스 파일명은 파일 확장자 .json을 사용하는 것이 SHOULD 좋습니다.

형식

현지화 리소스는 유효한 JSON 문서 [JSON]여야 MUST 합니다.

구조

현지화 리소스는 키-값 쌍으로 구성되어야 MUST 합니다. 각 키는 각각의 현지화 가능한 문자열(값)에 대한 고유 식별자를 나타냅니다.

MiniApp ZIP 컨테이너는 하나 이상의 서명을 포함하는 서명 블록을 포함할 MAY 있습니다. 서명 체계와 암호화 메커니즘은 사용자 에이전트의 구체적인 구현에 따라 달라집니다.

서명 체계는 MiniApp ZIP 컨테이너에 포함된 매직 넘버 섹션으로 식별되며, 이는 ZIP 패키지의 중앙 디렉터리 바로 앞에 위치한 16바이트 시퀀스입니다.

디지털 서명을 처리하려면, MiniApp ZIP 컨테이너 miniapp_zip_file가 주어졌을 때 다음 단계를 수행합니다:

1. magic_numbers를 byte sequence로 둡니다.
2. eocd_pointer를, miniapp_zip_file에서 중앙 디렉터리의 끝을 표시하는 0x06054b50(리틀 엔디언으로 읽음) 바이트 시퀀스를 찾은 결과인 byte sequence로 둡니다 [ZIP].
3. eocd_pointer를 eocd_pointer + 0x00000010으로 설정합니다.
4. cd_pointer를 eocd_pointer에서 4바이트 시퀀스를 읽은 결과로 둡니다.
5. magic_numbers_pointer를 eocd_pointer - 0x00000010으로 둡니다.
6. magic_numbers를 magic_numbers_pointer의 16바이트 블록으로 설정합니다.
7. magic_numbers와 miniapp_zip_file로 디지털 서명을 처리합니다.

사용자 에이전트는 MiniApp이 자신들과 호환되고 해당 플랫폼에서 제대로 실행될 수 있는지 검증해야 MUST 합니다. 이 검증은 플랫폼의 지원 버전과 실행에 필요한 페이지 및 리소스 확인을 포함하여 MiniApp 매니페스트에 지정된 메타데이터를 사용하여 수행됩니다.

플랫폼 호환성을 검증하려면, MiniApp Package miniapp_package와 ordered map manifest가 주어졌을 때 다음 단계를 수행합니다:

1. platform_required를 manifest["platform_version"]으로 설정합니다.
2. platform_required가 사용자 에이전트 구성과 호환되지 않으면 실패를 반환합니다.
3. manifest["pages"]의 list page마다 반복합니다:
   1. page가 miniapp_package에 존재하지 않으면 실패를 반환합니다.
4. manifest["widgets"]가 존재하면 다음을 수행합니다:
   manifest["widgets"]의 list widget_path마다 반복합니다:
   1. widget_path가 miniapp_package에 존재하지 않으면 실패를 반환합니다.

기본적으로, 사용자 에이전트는 MiniApp이 실행될 때 MiniApp 매니페스트에 표시된 시작 페이지를 진입점으로 로드해야 MUST 합니다. 이 기본 시작 페이지는 다음 알고리즘에 명시된 것처럼, MiniApp URI에 유효한 페이지가 지정된 경우 재정의되어야 MUST 합니다.

시작 페이지를 결정하려면, MiniApp Package miniapp_package, URL miniapp_uri, 및 ordered map manifest가 주어졌을 때 다음 단계를 수행합니다. 이는 URL을 반환합니다.

1. start_page를 miniapp_uri를 전달하여 URI에서 시작 페이지를 추출한 결과로 둡니다.
2. start_page가 설정되어 있지 않거나, start_page가 null과 같거나, start_page가 miniapp_package에 존재하지 않으면 다음을 수행합니다:
   manifest를 전달하여 매니페스트에서 시작 페이지를 추출한 결과로 start_page를 설정합니다.
3. start_page를 반환합니다

로케일을 추출하려면, ordered map manifest가 주어졌을 때 다음 단계를 수행합니다. 이는 string을 반환합니다.

1. string locale을 사용자 에이전트의 기본 로케일로 둡니다.
2. manifest["lang"]이 존재하고, manifest["lang"]이 사용자 에이전트에서 지원되면 다음을 수행합니다:
   locale을 manifest["lang"]으로 설정합니다.
3. locale을 반환합니다.