이 페이지는 2020년에 지원 중단된 Chrome 앱 플랫폼에 관한 문서의 일부입니다. 적어도 2025년 1월까지는 ChromeOS Enterprise 및 Education 고객에게 계속 지원됩니다. 앱 이전에 관해 자세히 알아보세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

기본 메시지

확장 프로그램과 앱은 다른 메시지 전달 API와 유사한 API를 사용하여 네이티브 애플리케이션과 메시지를 교환할 수 있습니다. 이 기능을 지원하는 네이티브 애플리케이션은 확장 프로그램과 통신하는 방법을 알고 있는 네이티브 메시지 호스트를 등록해야 합니다. Chrome은 별도의 프로세스에서 호스트를 시작하고 표준 입력 및 표준 출력 스트림을 사용하여 호스트와 통신합니다.

기본 메시지 호스트

기본 메시지 호스트를 등록하려면 애플리케이션에서 기본 메시지 호스트 구성을 정의하는 매니페스트 파일을 설치해야 합니다. 다음은 매니페스트 파일의 예입니다.

{
  "name": "com.my_company.my_application",
  "description": "My Application",
  "path": "C:\\Program Files\\My Application\\chrome_native_messaging_host.exe",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
  ]
}

기본 메시지 호스트 매니페스트 파일은 유효한 JSON이어야 하며 다음 필드를 포함합니다.

이름	설명
`name`	기본 메시지 호스트의 이름입니다. 클라이언트는 이 문자열을 runtime.connectNative 또는 runtime.sendNativeMessage에 전달합니다. 이 이름에는 소문자 영숫자 문자, 밑줄, 마침표만 사용할 수 있습니다. 이름은 마침표로 시작하거나 끝날 수 없으며, 마침표 뒤에 다른 점이 올 수 없습니다.
`description`	간단한 애플리케이션 설명입니다.
`path`	기본 메시지 호스트 바이너리의 경로입니다. Linux 및 OSX에서 경로는 절대 경로여야 합니다. Windows에서는 매니페스트 파일이 위치한 디렉터리를 기준으로 할 수 있습니다. 호스트 프로세스는 현재 디렉터리가 호스트 바이너리가 있는 디렉터리로 설정된 상태에서 시작됩니다. 예를 들어 이 매개변수가 `C:\Application\nm_host.exe`로 설정된 경우 현재 디렉터리 `C:\Application\`으로 시작됩니다.
`type`	기본 메시지 호스트와 통신하는 데 사용되는 인터페이스의 유형입니다. 현재 이 매개변수에 가능한 값은 `stdio` 하나뿐입니다. Chrome이 `stdin` 및 `stdout`를 사용하여 호스트와 통신해야 함을 나타냅니다.
`allowed_origins`	기본 메시지 호스트에 대한 액세스 권한이 있어야 하는 확장 프로그램 목록입니다. `chrome-extension:///`와 같은 와일드 카드는 허용되지 않습니다.

기본 메시지 호스트 위치

매니페스트 파일의 위치는 플랫폼에 따라 다릅니다.

Windows에서는 파일 시스템의 어디에나 매니페스트 파일이 있습니다. 애플리케이션 설치 프로그램은 레지스트리 키 HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ 또는 HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_를 만들고 해당 키의 기본값을 매니페스트 파일의 전체 경로로 설정해야 합니다. 예를 들어 다음 명령어를 사용합니다.

REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

또는 다음 .reg 파일을 사용하세요.

Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]
@="C:\\path\\to\\nmh-manifest.json"

Chrome이 기본 메시지 호스트를 찾으면 먼저 32비트 레지스트리를 쿼리한 다음 64비트 레지스트리를 쿼리합니다.

OS X 및 Linux에서는 기본 메시지 호스트의 매니페스트 파일 위치가 브라우저 (Chrome 또는 Chromium)에 따라 다릅니다. 시스템 전체 기본 메시지 호스트는 고정된 위치에서 조회되고, 사용자 수준 기본 메시지 호스트는 사용자 프로필 디렉터리 내 NativeMessagingHosts라는 하위 디렉터리에서 조회됩니다.

OS X (시스템 전체)
- Chrome: /Library/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- Chromium: /Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
OS X (사용자별, 기본 경로)
- Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- Chromium: ~/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
Linux (시스템 전체)
- Chrome: /etc/opt/chrome/native-messaging-hosts/_com.my_company.my_application_.json
- Chromium: /etc/chromium/native-messaging-hosts/_com.my_company.my_application_.json
Linux (사용자별 기본 경로)
- Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- Chromium: ~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

기본 메시지 프로토콜

Chrome은 별도의 프로세스에서 각 기본 메시지 호스트를 시작하고 표준 입력 (stdin)과 표준 출력 (stdout)을 사용하여 통신합니다. 동일한 형식이 두 방향으로 메시지를 보내는 데 사용됩니다. 각 메시지는 JSON 및 UTF-8로 인코딩되어 직렬화되고 기본 바이트 순서의 32비트 메시지 길이가 앞에 옵니다. 기본 메시지 호스트에서 제공하는 단일 메시지의 최대 크기는 1MB이며, 주로 Chrome이 기본 애플리케이션이 오작동하지 않도록 보호하기 위함입니다. 기본 메시지 호스트로 전송되는 메시지의 최대 크기는 4GB입니다.

네이티브 메시지 호스트의 첫 번째 인수는 호출자의 출처로, 보통 chrome-extension://[ID of allowed extension]입니다. 이렇게 하면 기본 메시지 호스트 매니페스트의 allowed_origins 키에 여러 확장 프로그램이 지정된 경우 기본 메시지 호스트가 메시지의 소스를 식별할 수 있습니다. 경고: Windows의 Chrome 54 이하 버전에서는 출처가 첫 번째 매개변수 대신 두 번째 매개변수로 전달되었습니다.

runtime.connectNative를 사용하여 메시지 포트가 생성되면 Chrome은 네이티브 메시지 호스트 프로세스를 시작하고 포트가 삭제될 때까지 실행을 유지합니다. 반면 메시지 포트를 만들지 않고 runtime.sendNativeMessage를 사용하여 메시지를 보내면 Chrome은 각 메시지에 대해 새로운 기본 메시지 호스트 프로세스를 시작합니다. 이 경우 호스트 프로세스에서 생성된 첫 번째 메시지는 원래 요청에 대한 응답으로 처리됩니다. 즉, Chrome은 runtime.sendNativeMessage가 호출될 때 지정된 응답 콜백에 메시지를 전달합니다. 이 경우 기본 메시지 호스트에서 생성된 다른 모든 메시지는 무시됩니다.

Windows에서는 기본 메시지 호스트에도 호출 Chrome 기본 창(--parent-window=<decimal handle value>)의 핸들이 포함된 명령줄 인수가 전달됩니다. 이렇게 하면 네이티브 메시지 호스트에서 상위 요소가 올바르게 지정된 네이티브 UI 창을 만들 수 있습니다. 호출 컨텍스트가 백그라운드 스크립트 페이지인 경우 이 값은 0입니다.

네이티브 애플리케이션에 연결

네이티브 애플리케이션과 주고받는 메시지를 주고받는 것은 확장 프로그램 간 메시징과 매우 유사합니다. 주요 차이점은 runtime.connectNative가 runtime.connect 대신 사용되고 runtime.sendNativeMessage가 runtime.sendMessage 대신 사용된다는 점입니다. 이러한 메서드는 앱의 매니페스트 파일에서 'nativeMessaging' 권한이 선언된 경우에만 사용할 수 있습니다.

다음 예에서는 기본 메시지 호스트 com.my_company.my_application에 연결된 runtime.Port 객체를 만들고 해당 포트의 메시지 리슨을 시작한 다음 하나의 발신 메시지를 보냅니다.

var port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener(function(msg) {
  console.log("Received" + msg);
});
port.onDisconnect.addListener(function() {
  console.log("Disconnected");
});
port.postMessage({ text: "Hello, my_application" });

runtime.sendNativeMessage를 사용하면 포트를 만들지 않고 네이티브 애플리케이션에 메시지를 보낼 수 있습니다.예를 들면 다음과 같습니다.

chrome.runtime.sendNativeMessage('com.my_company.my_application',
  { text: "Hello" },
  function(response) {
    console.log("Received " + response);
  });

네이티브 메시지 디버깅

기본 메시지 호스트가 시작되지 않거나, stderr에 쓰거나, 통신 프로토콜을 위반하는 경우, 출력이 Chrome의 오류 로그에 기록됩니다. Linux 및 OS X의 경우 명령줄에서 Chrome을 시작하고 터미널에서 출력을 확인하면 이 로그에 쉽게 액세스할 수 있습니다. Windows의 경우 로깅 사용 설정 방법에 설명된 대로 --enable-logging를 사용합니다.

다음은 문제를 해결하기 위한 몇 가지 오류 및 도움말입니다.

기본 메시지 호스트를 시작할 수 없습니다.
- 파일을 실행할 수 있는 권한이 있는지 확인하세요.
기본 메시지 호스트 이름이 잘못 지정되었습니다.
- 이름에 잘못된 문자가 포함되어 있는지 확인하세요. 소문자 영숫자 문자, 밑줄, 마침표만 사용할 수 있습니다. 이름은 마침표로 시작하거나 끝날 수 없으며 마침표 다음에 다른 점이 올 수 없습니다.
기본 호스트가 종료되었습니다.
- Chrome에서 메시지를 읽기 전에 기본 메시지 호스트로 연결되는 파이프가 손상되었습니다. 이 작업은 기본 메시지 호스트에서 시작되었을 가능성이 큽니다.
지정된 기본 메시지 호스트를 찾을 수 없습니다.
- 확장 프로그램과 매니페스트 파일에 이름의 철자가 올바르나요?
- 매니페스트가 올바른 디렉터리에 있고 올바른 이름으로 지정되어 있나요? 예상 형식은 네이티브 메시지 호스트 위치를 참고하세요.
- 매니페스트 파일이 올바른 형식인가요? 특히 JSON 구문이 올바르고 값이 기본 메시지 호스트 매니페스트의 정의와 일치하나요?
- path에 지정된 파일이 있나요? Windows에서는 경로가 상대 경로일 수 있지만, OS X 및 Linux에서는 경로가 절대값이어야 합니다.
기본 메시지 호스트 호스트 이름이 등록되지 않았습니다. (Windows만 해당)
- Windows 레지스트리에서 기본 메시지 호스트를 찾을 수 없습니다. regedit를 사용하여 키가 실제로 생성되었고 기본 메시지 호스트 위치에 설명된 필수 형식과 일치하는지 다시 확인합니다.
지정된 기본 메시지 호스트에 대한 액세스가 금지되었습니다.
- 확장 프로그램의 출처가 allowed_origins에 등록되어 있나요?
기본 메시지 호스트와 통신하는 중에 오류가 발생했습니다.
- 이는 매우 흔한 오류이며 기본 메시지 호스트에서 통신 프로토콜이 잘못 구현되었음을 나타냅니다.
- stdout의 모든 출력이 네이티브 메시지 프로토콜을 준수하는지 확인합니다. 디버깅을 위해 일부 데이터를 출력하려면 stderr에 작성하세요.
- 32비트 메시지 길이가 플랫폼의 기본 정수 형식 (little-endian/big-endian)인지 확인합니다.
- 메시지 길이는 1024*1024를 초과할 수 없습니다.
- 메시지 크기는 메시지의 바이트 수와 같아야 합니다. 문자는 여러 바이트로 표현될 수 있으므로 문자열의 '길이'와 다를 수도 있습니다.
- Windows 전용: 프로그램의 I/O 모드가 O_BINARY로 설정되어 있는지 확인합니다. 기본적으로 I/O 모드는 O_TEXT로, 줄바꿈 (\n = 0A)이 Windows 스타일의 줄 끝 (\r\n = 0D 0A)으로 대체되면 메시지 형식을 손상시킵니다. I/O 모드는 __setmode를 사용하여 설정할 수 있습니다.