확장 프로그램은 다른 메시지 전달 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
를 사용하여 설정할 수 있습니다.