개념

• 창 컨트롤: 운영체제가 애플리케이션 전반에서 일관되게 사용하여 사용자가 애플리케이션을 제어하기 위한 특정 작업을 수행할 수 있게 하는 인터페이스 요소. [=window controls=]의 일반적인 작업에는 최소화, 최대화/복원 및 닫기 버튼이 포함된다.

Display mode 확장

일반적인 display modes에 추가로, [=manifest/display_override=]는 이에 대한 특정 확장도 지원한다.

unframed

격리된 웹 애플리케이션에는 표시되는 host-native title bar나 [=window controls=]가 없으며, 웹 콘텐츠가 전체 title bar 영역까지 확장된다. 앱은 웹 콘텐츠에 [=draggable region=]을 지정하여 사용자 지정 title bar를 만들 수 있다.

[=display mode/window-controls-overlay=]

tabbed

웹 애플리케이션은 여러 [=application contexts=]를 하나의 운영체제 수준 창에 결합할 수 있다. 예를 들어, 이는 사용자 에이전트가 사용자가 application contexts 사이를 전환할 수 있도록 tab strip UI를 표시한다는 의미일 수 있다.

            {
              "name": "Recipe Zone",
              "description": "All of the recipes!",
              "icons": [{
                "src": "icon/hd_hi",
                "sizes": "128x128"
              }],
              "start_url": "/index.html",
              "display_override": ["minimal-ui"],
              "display": "standalone",
              "theme_color": "yellow",
              "background_color": "red"
            }
          

드래그 가능한 영역 정의

[=app-region=] CSS 속성은 어떤 사용자 에이전트에서도 구현되지 않았으므로 at risk 상태이다. 일부 사용자 에이전트는 같은 목적을 위해 비표준 CSS 속성 `-webkit-app-region`을 사용한다는 점에 유의한다.

`app-region` 속성은 예를 들어 title bar에서 어떤 영역이나 요소가 드래그 가능한지 CSS로 정의하는 데 사용할 수 있다.

• 요소의 드래그를 활성화하려면 `drag`로 설정해야 한다.
• 요소의 드래그를 비활성화하려면 `no-drag`로 설정해야 한다.

home_tab 멤버

[=tab_strip=] object의 `home_tab` 멤버는 애플리케이션의 최상위 메뉴로 작동하도록 의도된 특별한 "home tab"에 대한 정보를 담는 ordered map이다. 다음 멤버들을 포함한다:

• [=home_tab/scope_patterns=]

scope_patterns 멤버는 [=manifest URL=]을 기준으로 [=within home tab scope|home tab의 scope=]를 정의하는 {{URLPatternInput}}의 리스트이다.

애플리케이션의 적용된 [=display mode=]가 [=display mode/tabbed=]이고 [=Document/processed manifest=]가 [=tab_strip=] 멤버의 null이 아닌 [=home_tab=] 멤버를 포함하는 경우, 애플리케이션은 home tab을 가진다.

home tab context는 다른 application contexts와 비교하여 특별한 속성을 가지는 선택적 [=application context=]이다. 애플리케이션이 [=has a home tab=]이면, 모든 application window는 [=home tab context=]를 포함해야 한다(SHOULD). 그렇지 않으면, application windows는 [=home tab context=]를 가져서는 안 된다(SHOULD NOT).

[=home tab context=]가 어떻게 표시되는지는 사용자 에이전트의 재량에 맡겨지지만, 일반 application contexts와 다른 외형을 가져야 한다(SHOULD).

[=URL=] |url:URL|은 다음 경우에만 within home tab scope라고 한다:

• 애플리케이션이 [=has a home tab=]이고,
• |url|이 manifest의 [=manifest/within scope=]이며,
• 다음 중 적어도 하나가 참인 경우:
  • |url|이 [=URL/equals/exclude fragments=]를 true로 설정했을 때 [=start URL=]과 [=URL/equals=]하거나,
  • [=Document/processed manifest=]의 [=tab_strip=] 멤버의 [=home_tab=] 멤버의 [=scope_patterns=] 멤버의 임의의 요소가 주어지고 |url|에 대해 [=URL pattern/match=]를 적용하면 {{URLPatternResult}}를 반환하는 경우.

URL이 [=within home tab scope=]가 아니면 outside of home tab scope이다.

new_tab_button 멤버

[=tab_strip/new_tab_button=] 멤버는 클릭/활성화되었을 때 application window 내에 새 [=application context=]를 여는 UI affordance (예: 버튼)의 동작을 설명하는 ordered map이다. 다음 멤버들을 가진다:

• [=new_tab_button/url=]

url 멤버는 [=Document/processed manifest=]의 [=manifest/within scope=]인 [=manifest URL=] 기준의 URL을 나타내는 문자열이다.

애플리케이션은 [=Document/processed manifest=]의 [=new_tab_button=]의 [=new_tab_button/url=] 멤버가 [=outside of home tab scope=]이면 new tab button을 가진다. 애플리케이션이 [=has a new tab button|new tab button을 가지지=] 않으면, 사용자 에이전트는 최종 사용자에게 "new tab" affordance를 제공해서는 안 된다(SHOULD NOT).

최종 사용자가 new tab button을 활성화하면, 다음 단계들이 실행된다:

1. 현재 창에 [=Create a new application context=]하고 포커스한다.
2. 이를 [=new_tab_button=]의 [=new_tab_button/url=] 멤버 값으로 탐색한다.

`tab_strip` 멤버 처리

[=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map| 및 [=URL=] |manifest URL:URL|가 주어졌을 때 process the `tab_strip` member하려면, [=processing a manifest=]의 extension point 중에 다음을 실행한다:

1. |manifest|["tab_strip"]를 새 [=ordered map=]으로 설정한다.
2. |json|["tab_strip"]가 존재하지 않거나 |json|["tab_strip"]가 [=ordered map=]이 아니면:
   1. |manifest|["tab_strip"]["new_tab_button"]["url"]을 |manifest|["start_url"]로 설정한다.
   2. 반환한다.
3. |json|["tab_strip"], |manifest|["tab_strip"] 및 |manifest URL|을 전달하여 [=Process the `home_tab` member=]를 수행한다.
4. |json|["tab_strip"], |manifest|["tab_strip"], |manifest URL| 및 |manifest|["start_url"]를 전달하여 [=Process the `new_tab_button` member=]를 수행한다.

new_note_url 멤버

[=note_taking=] `new_note_url` 멤버는 사용자가 웹 애플리케이션을 사용하여 새 note를 작성하려고 할 때(예: 운영체제 바로 가기 아이콘이나 키보드 단축키에서) 개발자가 사용자 에이전트가 로드하기를 선호하는 URL을 나타내는 [=string=]이다.

`new_note_url` 멤버는 순수하게 권고적인 것이며, 사용자 에이전트는 이를 무시하거나 최종 사용자에게 사용할지 여부를 선택하게 할 수 있다(MAY). 사용자 에이전트는 최종 사용자에게 이를 수정할 선택권을 제공할 수 있다(MAY).

`note_taking` 멤버 처리

[=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|, [=URL=] |manifest_URL:URL|가 주어졌을 때 process the `note_taking` member하려면, [=processing a manifest=]의 extension point 중에 다음을 실행한다:

1. |json|["note_taking"]이 [=map/exist=]하지 않으면, 반환한다.
2. |json|["note_taking"]의 타입이 [=ordered map=]이 아니면, 반환한다.
3. |manifest|["note_taking"]을 새 [=ordered map=]으로 설정한다.
4. |json|["note_taking"], |manifest|["note_taking"] 및 |manifest URL|을 전달하여 [=process the `new_note_url` member=]를 수행한다.

`new_note_url` 멤버 처리

[=ordered map=] |json_note_taking:ordered map|, [=ordered map=] |manifest_note_taking:ordered map|, [=URL=] |manifest_URL:URL|가 주어졌을 때 process the `new_note_url` member하려면, 다음을 실행한다:

1. |json_note_taking|["new_note_url"]이 [=map/exist=]하지 않으면, 반환한다.
2. |json_note_taking|["new_note_url"]의 타입이 [=string=]이 아니면, 반환한다.
3. |new_note_url:URL|을 |manifest URL|을 base URL로 하여 |json_note_taking|["new_note_url"]을 [=URL Parser|파싱=]한 결과로 둔다.
4. |new_note_url|이 failure이면, 반환한다.
5. |new_note_url|이 |manifest URL|의 [=manifest/within scope=]가 아니면, 반환한다.
6. manifest_note_taking["new_note_url"]을 |new_note_url|로 설정한다.

`new_note_url` 실행

processed manifest |manifest:processed manifest|가 주어졌을 때 launch the `new_note_url`하려면, 다음 단계를 실행한다:

1. |manifest|["note_taking"]이 [=map/exist=]하지 않으면, 반환한다.
2. |manifest|["note_taking"]["new_note_url"]이 [=map/exist=]하지 않으면, 반환한다.
3. |manifest|["note_taking"]["new_note_url"]의 타입이 [=URL=]이 아니면, 반환한다.
4. |manifest|를 |manifest|로, |target URL|을 |manifest|["note_taking"]["new_note_url"]로 설정하여 [=launch a web application=] 단계를 실행한다.

사용자 에이전트는 주어진 [=installed web application=]에 대해 언제든지, 일반적으로 사용자 affordance에 대한 응답으로 [=launch the `new_note_url`=]할 수 있다(MAY).

`protocol_handlers` 멤버 처리

[=object=] |json:JSON|, |manifest:ordered map|가 주어졌을 때 process the `protocol_handlers` member하려면:

1. |processedProtocolHandlers|를 |json:JSON|["|protocol_handlers|"]의 새 [=list=]로 둔다.
2. manifest["|protocol_handlers|"]를 |processedProtocolHandlers|로 설정한다.
3. 각 |protocol_handler| (protocol handler description)에 대해 [=list/For each=]:
   1. |protocol_handler|["protocol"] 또는 |protocol_handler|["url"]가 undefined이면, [=iteration/continue=]한다.
   2. (|normalizedProtocol:string|, |normalizedUrl:URL|)을 |manifest URL|을 base URL로 하고 [=this=]의 relevant [=environment settings object=]를 사용하여 |protocol_handler|["protocol"], | protocol_handler|["url"]로 [=normalize protocol handler parameters=]를 실행한 결과로 둔다. 결과가 failure이면, [=iteration/continue=]한다.
   3. |normalizedUrl|이 |manifest|의 [=manifest/within scope=]가 아니면, [=iteration/continue=]한다.
   4. |processedProtocolHandlers|가 |normalizedUrl|을 [=list/contains=]하면, [=iteration/continue=]한다.
   5. |protocol_handler|를 |processedProtocolHandlers|에 [=List/Append=]한다.
4. |processedProtocolHandlers|의 각 항목에 대해 [=list/For each=], 사용자 에이전트는 [=register a protocol handler=]해야 한다(SHOULD).

사용자 에이전트는 host 운영체제에서 protocol의 기본 handler로 [=protocol handler description=] protocol_handler들을 등록하기 전에 사용자에게 권한을 요청해야 한다(SHOULD). 사용자 에이전트는 host 운영체제의 관례나 제한과 일관되게 유지하기 위해 표시되는 [=protocol handler description=] protocol_handlers 목록을 잘라낼 수 있다(MAY).

Protocol handler 항목

각 protocol handler description은 웹 애플리케이션이 처리하려는 protocol을 나타내는 [=object=]이며, [=manifest/protocol_handlers=] 멤버에 대응한다. 다음 멤버들을 가진다:

• [=protocol handler description/protocol=]
• [=protocol handler description/url=]

사용자 에이전트는 이러한 값을 사용하여 웹 애플리케이션을 운영체제에 handler로 등록해야 한다(SHOULD). 사용자가 protocol handler URL을 활성화하면, 사용자 에이전트는 handling a protocol launch를 실행해야 한다(SHOULD).

[[HTML]]의 {{NavigatorContentUtils/registerProtocolHandler()}}는 웹 사이트가 특정 protocols에 대한 가능한 handler로 자신을 등록할 수 있게 한다. protocol handler description의 유효한 [=protocol handler description/protocol=] 및 [=protocol handler description/url=] 값이 무엇인지는 해당 API에서 정의된다. 또한 [[HTML]] API는 여기서 사용하는 [=protocol handler description/protocol=] 대신 scheme을 사용하지만, 동일한 제한이 적용된다는 점에 유의한다.

개인정보 고려 사항: 기본 protocol handler

운영체제의 기능에 따라, protocol handler는 사용자의 명시적 인지 없이 주어진 protocol의 'default' handler(예: 주어진 protocol의 실행을 자동으로 처리)가 될 수 있다. 가능한 오용을 방지하기 위해, 사용자 에이전트는 다음과 같은 보호 조치를 사용할 수 있다(MAY):

• [=invoke a protocol handler=] 과정을 실행하기 전에 명시적 사용자 동의를 요구한다.
• 위 dialog에 대한 응답 또는 사용자 조작으로, 웹 애플리케이션의 OS protocol handling entity 등록을 제거한다.
• [=installation=] 시 protocol handler 등록을 확인한다.

사용자 에이전트가 protocol handler entity의 등록을 제거하는 경우, 사용자가 웹 앱과 protocol을 운영체제에 다시 등록할 수 있는 UX를 제공해야 한다(SHOULD).

File Handler 항목

각 file handler는 자신이 수락하는 [=file types=]로 실행을 처리할 수 있는 애플리케이션 scope 내의 URL을 나타낸다. 다음 멤버들을 가진다:

• [=file handler/action=]
• [=file handler/name=]
• [=file handler/accept=]
• [=file handler/icons=]

사용자 에이전트는 이러한 멤버를 사용하여 웹 애플리케이션을 운영체제의 [=file type=]과 연결할 수 있다.

file type은 [=MIME type=] 및/또는 [=file extension=]으로 정의될 수 있다. OS가 파일에 [=MIME type=]이 있다고 판단하거나 그 이름이 특정 [=file extension=]으로 끝나는 경우, 파일은 file type에 속한다. file extension은 "."로 시작하고 valid suffix code points만 포함하는 문자열이다. 또한 [=file extensions=]는 16 code points 길이로 제한된다.

File handler 항목 처리

[=ordered map=] |item:ordered map|, [=URL=] |start_url:URL|, [=URL=] |scope:URL| 및 [=URL=] |manifest URL:URL|가 주어졌을 때 process a file handler item하려면:

1. 다음 중 하나라도 참이면 failure를 반환한다:
   • |item|["action"]이 [=map/exist=]하지 않거나 [=string=]이 아니다.
   • |item|["accept"]가 [=map/exist=]하지 않는다.
   • |item|["accept"]가 [=dictionary=]가 아니다.
   • |item|["accept"]가 [=map/is empty=]이다.
2. |url:URL|을 |manifest_url URL|을 base URL로 하여 |item|["action"]을 [=URL Parser|파싱=]한 결과로 둔다.
3. |url|이 failure이면, failure를 반환한다.
4. |url|이 |scope|의 [=manifest/within scope=]가 아니면, failure를 반환한다.
5. |launch_type:string|을 "single-client"로 초기화된 새 [=string=]으로 둔다.
6. |item|["launch_type"]이 [=map/exists=]하고 "multiple-clients"이면, |launch_type|을 |item|["launch_type"]으로 설정한다.
7. |accept:ordered map|을 새 [=ordered map=]으로 둔다.
8. |item|["accept"]의 각 |mime_type_string:string| → |extensions|에 대해 [=map/for each=]
   1. |extensions|가 [=list=]가 아니면, [=iteration/continue=]한다.
   2. |extensions|가 [=list/empty=]이면, [=iteration/continue=]한다.
   3. |extensions|가 [=string=]이 아닌 항목을 [=list/contains=]하면, [=iteration/continue=]한다.
   4. |extensions|가 문자 `.`로 시작하지 않는 문자열을 [=list/contains=]하면, [=iteration/continue=]한다.
   5. |extensions|가 16자보다 긴 문자열을 [=list/contains=]하면, [=iteration/continue=]한다.
   6. |mime_type_parsed:mime type|을 |mime_type_string|에 대해 [=parse a mime type=] 단계를 실행한 결과로 둔다.
   7. |mime_type_parsed:mime type|이 failure이면, [=iteration/continue=]한다.
   8. |mime_type_parsed/type|이 [[IANA-MEDIA-TYPES]]의 top-level type으로 나열되어 있지 않으면, [=iteration/continue=]한다.
   9. |accept|[|mime_type_string|]을 |extensions|로 설정한다.
9. |accept:ordered map|이 비어 있으면, failure를 반환한다.
10. |file_handler:ordered map|을 |ordered map| «[ "action" → |url|, "name" → |item|["name"], "launch_type" → |launch_type|, "accept" → |accept| ]»로 둔다.
11. |item|["icons"], |file_handler|, |manifest URL| 및 "icons"를 전달하여 Process image resources한다.
12. |file_handler|를 반환한다.

File handler launch 실행

execute a file handler launch 단계는 다음 알고리즘으로 주어진다. 이 알고리즘은 [=list=] |files:list|와 [=processing a manifest=]의 결과를 보유하는 [=ordered map=] |manifest:ordered_map|을 취한다.

1. |file_handlers:list|를 |manifest|["file_handlers"]로 둔다.
2. |file_handlers:list|가 null이면, 반환한다.
3. |launches:ordered map|을 [=ordered map=]으로 둔다.
4. |files|의 각 |filename:string|에 대해 [=list/for each=]
   1. |file_handlers:list|의 각 |file_handler:ordered_map|에 대해 [=list/for each=]:
      1. |file_handler|["accept"]의 각 |mime_type_string:string| → |extensions:list|에 대해 [=map/for each=]
         1. |extensions|의 각 |extension:string|에 대해 [=list/for each=]:
            1. |filename|이 |extension|으로 끝나지 않으면, [=iteration/continue=]한다.
            2. |launches|[|file_handler|]가 [=map/exists=]하면, |filename|을 |launches|[|file_handler|]에 [=list/append=]한다.
            3. 그렇지 않으면, |launches|[|file_handler|]를 단일 요소 |filename|을 가진 [=list=]로 설정한다.
            4. |files|의 다음 요소로 [=iteration/Continue=]한다.
5. |launches|의 각 |file_handler| → |files:list|에 대해 [=map/for each=]
   1. |file_handler|["launch_type"]이 "multiple-clients"와 같으면
      1. |files|의 각 |file|에 대해 [=list/for each=]
         1. |params:LaunchParams|를 {{LaunchParams/targetURL}}가 |file_handler|["action"]으로 설정되고 {{LaunchParams/files}}가 |file|에 대응하는 단일 요소 {{FileSystemHandle}}를 가진 {{FrozenArray}}로 설정된 새 {{LaunchParams}}로 둔다.
         2. |manifest| 및 |params|를 전달하여 [=Launch a web application with handling=]한다.
   2. 그렇지 않으면,
      1. |params:LaunchParams|를 {{LaunchParams/targetURL}}가 |file_handler|["action"]으로 설정되고 {{LaunchParams/files}}가 |files|로 명명된 파일 경로에 대응하는 {{FileSystemHandle}}들의 {{FrozenArray}}로 설정된 새 {{LaunchParams}}로 둔다.
      2. |manifest| 및 |params|를 전달하여 [=Launch a web application with handling=]한다.

File handlers 등록

사용자 에이전트는 다음과 일관되게 host 운영체제에 register file handlers해야 한다(SHOULD):

• 앱은 native file browser 및 주어진 파일이나 file type을 처리할 수 있는 앱 목록을 표시하는 기타 surfaces와 같은 적절한 OS surfaces에 노출된다.
• 앱은 연결된 file types에 대한 시스템 기본 handler가 될 후보이다.

사용자 에이전트는 기능을 보존하고 남용을 방지하기 위해 [=file extensions=]의 전체 집합을 잘라낼 수 있다(MAY). 사용자 에이전트는 특정 filetypes와의 연결을 방지할 수 있다(MAY).

개인정보 고려 사항: 기본 file handler.

운영체제의 기능에 따라, [=file handler=]는 사용자의 명시적 인지 없이 주어진 [=file type=]의 기본 handler가 되어 해당 file type의 실행을 자동으로 처리할 수 있다. 가능한 오용을 방지하기 위해, [=user agents=]는 [=execute a file handler launch=] 과정을 시작하기 전에 명시적 사용자 동의를 요구할 수 있다(MAY). 동의를 요청하는 경우, 사용자 에이전트는 사용자가 그 결정을 영구적으로 지정할 수 있도록 허용해야 하며(SHOULD), 그렇게 지정된 경우 웹 애플리케이션의 OS file handling entity 등록을 제거해야 한다(SHOULD).

개인정보 고려 사항: 이름과 아이콘.

각 file handler의 이름과 아이콘은 개인정보 및 보안에 민감할 수 있다. 사용자가 이를 보고 확인하는 지정된 방법이 없기 때문이다. 이로 인해, [=user agents=]는 대체 문자열과 아이콘을 선호하거나 OS 기본값으로 fallback하기 위해 이를 무시하도록 선택할 수 있다(MAY).

`scope_extensions` 멤버 처리

[=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map| 및 [=URL=] |manifest_id:URL|가 주어졌을 때 process the `scope_extensions` member하려면:

1. |processedScopeExtensions:list|를 새 [=list=]로 둔다.
2. |manifest|["scope_extensions"]를 |processedScopeExtensions|로 설정한다.
3. |json|["scope_extensions"]가 [=map/exist=]하지 않거나 [=list=]가 아니면, 반환한다.
4. |json|["scope_extensions"]의 각 |entry:ordered map|에 대해 [=list/For each=]:
   1. |entry|["type"] 또는 |entry|["origin"]이 [=map/exist=]하지 않으면, [=iteration/continue=]한다.
   2. |entry|["type"]이 "origin"이 아니면, [=iteration/continue=]한다.
   3. |entry|["origin"]이 [=string=]이 아니면, [=iteration/continue=]한다.
   4. [=URL=] |origin_url:URL|을 |entry|["origin"]을 [=URL Parser|파싱=]한 결과로 둔다.
   5. |origin_url|이 [=URL/scheme=] "https"를 가진 유효한 |URL|이면, |entry|["origin"]을 |origin_url|의 [=URL/origin=]으로 설정한다.
   6. 그렇지 않으면 [=iteration/continue=]한다.
   7. [=ordered map=] |entry:ordered map| 및 [=URL=] |manifest_id:URL|가 주어졌을 때 [=validate scope extensions=]의 알고리즘을 사용하여 |entry|를 검증한다.
   8. 이전 단계가 error를 반환했으면, [=iteration/continue=]한다.
   9. 그렇지 않으면, |entry|["scope"]를 반환된 [=URL=]로 설정한다.
   10. |entry|를 |processedScopeExtensions|에 [=list/Append=]한다.

Scope extensions 검증

[=ordered map=] |extension:ordered map| 및 [=URL=] |manifest_id:URL|가 주어졌을 때 validate scope extensions하려면:

1. [=URL=] |origin_url:URL|을 |extension|["origin"]의 [=URL/origin=]의 [=URL=]로 둔다.
2. [=URL=] |download_url:URL|을 |origin_url|을 base [=URL=]로 사용하여 "/.well-known/web-app-origin-association"을 [=URL Parser|파싱=]한 결과로 둔다.
3. [=ordered map=] |json:ordered map|을 |download_url|가 주어진 [=fetch=]의 결과로 둔다.
4. [=fetch=]가 실패했으면, error를 반환한다.
5. |json|[|manifest_id|]가 [=map/exist=]하지 않거나 [=ordered map=]이 아니면, error를 반환한다.
6. [=string=] |scope:string|를 "/"로 둔다.
7. |json|[|manifest_id|]["scope"]가 [=map/exists=]하고 [=string=]이면, |scope|를 |json|[|manifest_id|]["scope"]로 설정한다.
8. [=URL=] |resolved_scope:URL|을 |extension|["origin"]을 base [=URL=]로 하여 |scope|를 [=URL Parser|파싱=]한 결과로 둔다.
9. |resolved_scope|를 반환한다.

Scope extensions 적용

사용자 에이전트는 어떤 시나리오에서는 apply extended scope를 적용하고 다른 시나리오에서는 [=manifest/scope=]를 적용하도록 선택할 수 있다(MAY).

[=application context=]의 [=navigable/active document=]의 [=URL=]이 [=manifest/within scope=]가 아니지만 [=within extended scope=]이면, 사용자 에이전트는 사용자가 [=URL=] 또는 적어도 그 [=origin=]을, secure connection을 통해 제공되는지 여부를 포함하여 확인할 수 있게 하는 UI를 제공해야 한다(SHOULD). 이 UI는 [=URL=]이 [=application context=]의 [=Document/processed manifest=]의 [=manifest/within scope=]가 아닐 때 사용되는 UI와 달라야 하며(SHOULD), 사용자가 여전히 애플리케이션의 의도된 콘텐츠를 탐색하고 있음을 분명히 하면서도 다른 [=origin=]으로 탐색하는 것의 개인정보 및 보안 영향을 계속 알 수 있게 해야 한다.

migrate_from 멤버

[=manifest/migrate_from=] 멤버는 migration 대상이 되는 이전 웹 애플리케이션을 식별하는 [=strings=] 또는 [=ordered maps=]의 [=list=]이다.

entry가 [=string=]이면, 이전 애플리케이션의 [=manifest/id=]로 취급된다.

entry가 [=ordered map=]이면, 다음 멤버들을 가질 수 있다:

• id: 이전 애플리케이션의 [=manifest/id=]를 나타내는 [=string=].
• install_url: 이전 애플리케이션의 manifest로 연결되는 페이지의 URL을 나타내는 [=string=]. 사용자 에이전트는 이전 애플리케이션의 일부인 다른 모든 URL이 새 애플리케이션으로 redirect하더라도 업데이트를 적용하기 위해 이 필드를 사용하여 이전 애플리케이션의 manifest를 fetch할 수 있다.
• behavior: `"suggest"` 또는 `"force"` 중 하나일 수 있는 [=string=]. 이는 migration에 대해 사용자에게 알리기 위해 사용자 에이전트가 표시하는 UI가 얼마나 강제적인지에 영향을 줄 수 있는 hint이다.

migrate_to 멤버

[=manifest/migrate_to=] 멤버는 새 애플리케이션으로의 migration을 능동적으로 알리는 선택적 [=ordered map=]이다. 다음 멤버들을 가진다:

• id: 새 애플리케이션의 [=manifest/id=]를 나타내는 [=string=].
• install_url: 새 애플리케이션의 manifest로 연결되는 페이지의 URL을 나타내는 [=string=]. 이 페이지의 manifest는 migration이 처리되기 위해 이 애플리케이션을 다시 가리키는 [=manifest/migrate_from=] 필드를 포함해야 한다.

Origin migration 검증

[=URL=] |old_manifest_id:URL| 및 [=URL=] |new_manifest_id:URL|가 주어졌을 때 validate origin migration하려면:

1. |old_manifest_id|의 [=URL/origin=]과 |new_manifest_id|의 [=URL/origin=]이 [=same site=]가 아니면, error를 반환한다.
2. |old_manifest_id|의 [=URL/origin=]이 |new_manifest_id|의 [=URL/origin=]과 [=same origin=]이면, success를 반환한다.
3. [=URL=] |origin_url:URL|을 |old_manifest_id|의 [=URL/origin=]으로 둔다.
4. [=URL=] |download_url:URL|을 |origin_url|을 base [=URL=]로 사용하여 "/.well-known/web-app-origin-association"을 [=URL Parser|파싱=]한 결과로 둔다.
5. [=ordered map=] |json:ordered map|을 |download_url|가 주어진 [=fetch=]의 결과로 둔다.
6. [=fetch=]가 실패했으면, error를 반환한다.
7. |json|[|new_manifest_id|]가 [=map/exist=]하지 않거나 [=ordered map=]이 아니면, error를 반환한다.
8. |json|[|new_manifest_id|]["allow_migration"]이 `true`가 아니면, error를 반환한다.
9. success를 반환한다.

`migrate_from` 멤버 처리

[=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map| 및 [=URL=] |manifest URL:URL|가 주어졌을 때 process the `migrate_from` member하려면:

1. |json|["id"]가 [=map/exist=]하지 않거나 [=string=]이 아니면, 반환한다.
2. |json|["id"]가 빈 문자열이면, 반환한다.
3. |base_origin:origin|을 |manifest|["start_url"]의 [=URL/origin=]으로 둔다.
4. |id_url:URL|을 |base_origin|을 base URL로 하여 |json|["id"]를 [=URL Parser|파싱=]한 결과로 둔다.
5. |id_url|이 failure이면, 반환한다.
6. |id_url|이 |manifest|["start_url"]와 [=same origin=]이 아니면, 반환한다.
7. |processed_migrate_from:list|를 새 [=list=]로 둔다.
8. |manifest|["migrate_from"]을 |processed_migrate_from|로 설정한다.
9. |json|["migrate_from"]이 [=map/exist=]하지 않거나 [=list=]가 아니면, 반환한다.
10. |json|["migrate_from"]의 각 |entry|에 대해 [=list/For each=]:
    1. |processed_entry:ordered map|을 새 [=ordered map=]으로 둔다.
    2. |entry|가 [=string=]이면:
       1. |id:URL|을 |manifest URL|을 base URL로 하여 |entry|를 [=URL Parser|파싱=]한 결과로 둔다.
       2. |id|가 failure이면, [=iteration/continue=]한다.
       3. |processed_entry|["id"]를 |id|로 설정한다.
    3. 그렇지 않고 |entry|가 [=ordered map=]이면:
       1. |entry|["id"]가 [=map/exist=]하지 않거나 [=string=]이 아니면, [=iteration/continue=]한다.
       2. |id:URL|을 |manifest URL|을 base URL로 하여 |entry|["id"]를 [=URL Parser|파싱=]한 결과로 둔다.
       3. |id|가 failure이면, [=iteration/continue=]한다.
       4. |processed_entry|["id"]를 |id|로 설정한다.
       5. |entry|["install_url"]이 [=map/exists=]하고 [=string=]이면:
          1. |install_url:URL|을 |manifest URL|을 base URL로 하여 |entry|["install_url"]을 [=URL Parser|파싱=]한 결과로 둔다.
          2. |install_url|이 failure가 아니면, |processed_entry|["install_url"]을 |install_url|로 설정한다.
       6. |entry|["behavior"]가 [=map/exists=]하고 [=string=]이면:
          1. |entry|["behavior"]가 "suggest" 또는 "force"이면, |processed_entry|["behavior"]를 |entry|["behavior"]로 설정한다.
    4. 그렇지 않으면, [=iteration/continue=]한다.
    5. [=URL=] |processed_entry|["id"] 및 [=URL=] |id_url|가 주어졌을 때 [=validate origin migration=]의 알고리즘을 사용하여 |processed_entry|["id"]를 검증한다.
    6. 이전 단계가 error를 반환했으면, [=iteration/continue=]한다.
    7. |processed_entry|를 |processed_migrate_from|에 [=list/Append=]한다.

`migrate_to` 멤버 처리

[=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map| 및 [=URL=] |manifest URL:URL|가 주어졌을 때 process the `migrate_to` member하려면:

1. |json|["migrate_to"]가 [=map/exist=]하지 않거나 [=ordered map=]이 아니면, 반환한다.
2. |entry:ordered map|을 |json|["migrate_to"]로 둔다.
3. |entry|["id"]가 [=map/exist=]하지 않거나 [=string=]이 아니면, 반환한다.
4. |id:URL|을 |manifest URL|을 base URL로 하여 |entry|["id"]를 [=URL Parser|파싱=]한 결과로 둔다.
5. |id|가 failure이면, 반환한다.
6. |processed_migrate_to:ordered map|을 새 [=ordered map=]으로 둔다.
7. |processed_migrate_to|["id"]를 |id|로 설정한다.
8. |entry|["install_url"]이 [=map/exists=]하고 [=string=]이면:
   1. |install_url:URL|을 |manifest URL|을 base URL로 하여 |entry|["install_url"]을 [=URL Parser|파싱=]한 결과로 둔다.
   2. |install_url|이 failure가 아니면, |processed_migrate_to|["install_url"]을 |install_url|로 설정한다.
9. |manifest|["migrate_to"]를 |processed_migrate_to|로 설정한다.

개인정보 및 보안 고려 사항

악의적인 행위자가 조용히 애플리케이션을 takeover하는 것(예: 단순한 계산기 앱이 자신을 은행 앱처럼 보이도록 업데이트하는 것)을 방지하기 위해, [=validate origin migration=] 알고리즘은 양방향 handshake를 강제한다. 새 애플리케이션 origin과 이전 애플리케이션 origin 모두 [=web-app-origin-association=] 파일을 통해 migration에 명시적으로 동의해야 한다.

또한 migration은 검증되지 않은 제3자에게 ownership을 이전하는 것이 아니라 조직의 통제 내에서 이루어지는 정당한 rebranding 및 architecture 변경에 사용되도록 보장하기 위해 [=same site=]로 제한된다.

사용자 에이전트는 특히 app name 및 icons와 같은 보안에 민감한 필드의 업데이트가 포함된 경우, migration flow의 일부로 명시적 사용자 확인 dialog를 포함하는 것을 고려해야 한다.

`platform` 멤버

platform 멤버는 이 [=external application resource=]가 연결된 [=platform=]을 나타낸다. platform은 software distribution ecosystem 또는 가능하게는 operating system을 나타낸다. 이 명세는 platform 멤버의 특정 값을 정의하지 않는다.

`url` 멤버

[=external application resource's=] url 멤버는 애플리케이션을 찾을 수 있는 URL이다.

process the `url` member of an application하려면:

1. application URL이 missing이면, null을 반환한다.
2. 그렇지 않으면, application URL을 [=URL Parser|parse=]하고, 결과가 failure가 아니면 결과를 반환한다. 그렇지 않으면 null을 반환한다.

`id` 멤버

[=external application resource's=] id 멤버는 platform에서 애플리케이션을 나타내는 데 사용되는 id를 나타낸다.

`min_version` 멤버

[=external application resource's=] min_version 멤버는 이 웹 앱과 관련 있다고 간주되는 애플리케이션의 minimum version을 나타낸다. 이 version은 platform-specific syntax 및 semantics를 가진 string이다.

`fingerprints` 멤버

[=external application resource's=] fingerprints 멤버는 [=fingerprints=]의 [=list=]를 나타낸다.

fingerprint는 애플리케이션 검증에 사용되는 cryptographic fingerprints의 집합을 나타낸다. fingerprint는 type 및 value라는 두 멤버를 가진다. 이들은 각각 string이지만, 그 syntax 및 semantics는 platform-defined이다.

Installation 과정

steps to install the web application은 다음 알고리즘으로 주어진다:

1. manifest를 installable document의 manifest로 둔다.
2. 사용자의 운영체제에 웹 애플리케이션을 등록하려는 지정되지 않은 일련의 작업을 수행한다(예: 웹 애플리케이션을 실행하는 shortcuts 생성, system uninstall menu에 애플리케이션 등록 등). 설치가 실패하면 (예를 들어 OS가 사용자 에이전트에게 기기의 home screen에 아이콘을 추가할 권한을 거부하는 등 어떤 이유로든 가능하다) 이 단계들을 abort한다.
3. 설치가 발생한 [=top-level browsing context=]의 [=relevant global object=]에 `"appinstalled"`라는 이름의 fire an event를 수행하도록 application life-cycle task source에 Queue a task한다.

BeforeInstallPromptEvent 인터페이스

          [Exposed=Window]
          interface BeforeInstallPromptEvent : Event {
            constructor(DOMString type, optional EventInit eventInitDict = {});
            Promise<PromptResponseObject> prompt();
          };

          dictionary PromptResponseObject {
            AppBannerPromptOutcome userChoice;
          };

          enum AppBannerPromptOutcome {
            "accepted",
            "dismissed"
          };
        

{{BeforeInstallPromptEvent}}는 사이트가 site-triggered install prompt를 표시할 수 있도록 허용될 때, 또는 사용자 에이전트가 automated install prompt를 표시하기 전에 dispatch된다. 이는 사이트가 automated install prompt를 cancel할 수 있게 하고, 또한 site-triggered install prompt를 수동으로 표시할 수 있게 한다.

PromptResponseObject는 {{BeforeInstallPromptEvent/prompt()}}를 호출한 결과를 포함한다. 이는 사용자가 선택한 outcome을 나타내는 하나의 멤버 userChoice를 포함한다.

{{BeforeInstallPromptEvent}}의 인스턴스는 다음 internal slots를 가진다:

[[\didPrompt]]

초기에 `false`인 boolean. 이 이벤트가 최종 사용자에게 present an install prompt하는 데 사용되었는지를 나타낸다.

[[\userResponsePromise]]

presenting an install prompt의 outcome을 나타내는 promise.

              window.addEventListener("beforeinstallprompt", event => {
                // Suppress automatic prompting.
                event.preventDefault();

                // Show the (disabled-by-default) install button. This button
                // resolves the installButtonClicked promise when clicked.
                installButton.disabled = false;

                // Wait for the user to click the button.
                installButton.addEventListener("click", async e => {
                  // The prompt() method can only be used once.
                  installButton.disabled = true;

                  // Show the prompt.
                  const userChoice = await event.prompt();
                  console.info(`user choice was: ${userChoice}`);
                });
              });
            

`Window` object에 대한 확장

          partial interface Window {
            attribute EventHandler onappinstalled;
            attribute EventHandler onbeforeinstallprompt;
          };