이 페이지는 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 및 macOS에서는 경로가 절대값이어야 합니다. Windows에서는 매니페스트 파일이 포함된 디렉터리를 기준으로 할 수 있습니다. 호스트 프로세스는 현재 디렉터리가 호스트 바이너리가 있는 디렉터리로 설정된 상태에서 시작됩니다. 예를 들어 이 매개변수가 C:\Application\nm_host.exe로 설정된 경우 현재 디렉터리 `C:\Application`으로 시작됩니다.
type: 기본 메시지 호스트와 통신하는 데 사용되는 인터페이스의 유형입니다. 이 매개변수에는 가능한 값 stdio가 하나 있습니다. Chrome이 stdin 및 stdout를 사용하여 호스트와 통신해야 함을 나타냅니다.
allowed_origins: 기본 메시지 호스트에 액세스할 수 있어야 하는 확장 프로그램 목록입니다. allowed-origins 값에는 와일드 카드를 포함할 수 없습니다.

기본 메시지 호스트 위치

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

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비트 레지스트리를 쿼리합니다.

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

macOS (시스템 전체): Chrome: /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Chromium: /Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
macOS (사용자별, 기본 경로): 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 기본 창(--parent-window=<decimal handle value>)의 핸들이 포함된 명령줄 인수가 전달됩니다. 이렇게 하면 네이티브 메시지 호스트에서 상위 요소가 올바르게 지정된 네이티브 UI 창을 만들 수 있습니다. 호출 컨텍스트가 서비스 워커인 경우 이 값은 0입니다.

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

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

네이티브 애플리케이션과 주고받는 메시지를 주고받는 것은 확장 프로그램 간 메시징과 매우 유사합니다. 주요 차이점은 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);
  }
);

네이티브 메시지 디버그

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

다음은 몇 가지 일반적인 오류와 이를 해결하기 위한 도움말입니다.

기본 메시지 호스트를 시작할 수 없습니다.

기본 메시지 호스트 파일을 실행할 수 있는 권한이 있는지 확인합니다.

잘못된 기본 메시지 호스트 이름이 지정되었습니다.

이름에 잘못된 문자가 포함되어 있는지 확인하세요. 소문자 영숫자 문자, 밑줄, 마침표만 사용할 수 있습니다. 이름은 마침표로 시작하거나 끝날 수 없으며 마침표 다음에 다른 점이 올 수 없습니다.

네이티브 호스트가 종료되었습니다.

Chrome에서 메시지를 읽기 전에 기본 메시지 호스트로 연결되는 파이프가 손상되었습니다. 이 작업은 기본 메시지 호스트에서 시작되었을 가능성이 큽니다.

지정된 기본 메시지 호스트를 찾을 수 없습니다.

다음을 확인하세요.

확장 프로그램과 매니페스트 파일에 이름의 철자가 올바르나요?
매니페스트가 올바른 디렉터리에 있고 이름이 정확한가요? 예상 형식은 네이티브 메시지 호스트 위치를 참고하세요.
매니페스트 파일이 올바른 형식인가요? 특히 JSON이 유효하고 형식이 올바르며 값이 기본 메시지 호스트 매니페스트의 정의와 일치하나요?
path에 지정된 파일이 있나요? Windows에서는 경로가 상대 경로일 수 있지만, macOS 및 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를 사용하여 설정할 수 있습니다.