이 페이지는 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)인지 확인합니다.
메시지 길이는 1,024*1,024를 초과할 수 없습니다.
메시지 크기는 메시지의 바이트 수와 같아야 합니다. 문자가 여러 바이트로 표현될 수 있으므로 문자열의 '길이'와 다를 수 있습니다.
Windows만 해당: 프로그램의 I/O 모드가 O_BINARY로 설정되어 있는지 확인합니다. 기본적으로 I/O 모드는 O_TEXT이며 줄바꿈 (\n = 0A)이 Windows 스타일의 줄 끝 (\r\n = 0D 0A)으로 대체되므로 메시지 형식이 손상됩니다. I/O 모드는 __setmode를 사용하여 설정할 수 있습니다.