이 문서는 UA Pro 1.5.0에 적용되며 설정을 백업, 이전, 직접 작성하고 원격 주소에서 불러오는 방법을 설명합니다. 새 버전은 전체 스냅샷 형식을 사용하며 설정 파일의 version은 2입니다.
가져오기 전에 대상 브라우저에서 백업을 내보내세요. 가져올 때마다 파일의 전체 스냅샷으로 전역 규칙, 도메인 규칙 전체, 두 UA 라이브러리와 리소스 도메인 대체 규칙 스위치를 교체하며 항목별로 병합하지 않습니다. "globalRule": null은 대상 브라우저의 전역 규칙을 지운다는 뜻입니다.
01설정 내보내기
- 브라우저 도구 모음에서 UA Pro 아이콘을 클릭합니다.
- “더보기” → “설정 가져오기/내보내기”를 엽니다.
- “설정 내보내기”를 클릭하고 다운로드한
.json파일을 저장합니다. - 파일 이름은
ua-switcher-config-2026-11-16.json과 비슷합니다. 파일 이름의 날짜는 UTC 기준으로 생성되므로 현지 날짜와 하루 차이가 날 수 있습니다.
파일에는 다음과 같이 지속적으로 저장되는 설정이 포함됩니다.
- 전역 규칙과 활성화 또는 일시 중지 상태.
- 도메인 규칙 전체와 각 규칙의 활성화 또는 일시 중지 상태.
- 사용자 지정 UA 분류와 항목.
- 추가 텍스트 분류와 항목.
- “리소스 도메인 대체 규칙” 스위치.
파일에는 탭 규칙, 이미 추출된 무작위 UA 바인딩, 현재 열린 탭, 인터페이스 언어, 테마 및 플로팅 오버레이 설정이 포함되지 않습니다. 가져온 후 이 항목들은 백업에서 복원되지 않습니다. 대상 브라우저에 이미 있는 탭 규칙도 가져오기 작업으로 지워지지 않으므로 도메인 또는 전역 규칙보다 계속 우선할 수 있습니다.
내보낸 파일은 읽을 수 있는 일반 텍스트 JSON입니다. 사용자 지정 UA 또는 분류에 공개하고 싶지 않은 정보가 있으면 백업을 안전하게 보관하세요.
02로컬 파일에서 가져오기
- 대상 브라우저에서 UA Pro → “더보기” → “설정 가져오기/내보내기”를 엽니다.
- 먼저 “설정 내보내기”를 클릭하여 필요할 때 복원할 수 있도록 대상 브라우저의 기존 설정을 보관합니다.
- “설정 가져오기”를 클릭하고
.json파일을 선택합니다. - 덮어쓰기 안내와 규칙 및 목록의 개수를 확인합니다. “구성 내용 보기”를 클릭하면 확인 전에 전체 JSON을 살펴볼 수 있습니다. “취소”를 선택하면 쓰기 작업이 수행되지 않습니다. 확인 후 “설정을 가져왔습니다!” 안내가 나타날 때까지 기다립니다. 확인하는 동안 설정이 변경되면 확장 프로그램에서 다시 진행하도록 요청합니다.
- 전역 및 도메인 규칙, 사용자 지정 목록, 리소스 도메인 대체 규칙 스위치를 확인하고 기존 탭 규칙이 이들보다 우선하는지도 확인합니다. 테스트할 웹페이지를 새로고침한 다음 UA를 확인합니다.
확장 프로그램은 먼저 파일을 검사하고 규칙 설치를 시도한 뒤 지속 설정을 기록합니다. 설치 또는 쓰기에 실패하면 현재 브라우저에 저장된 규칙으로 복원을 시도합니다. 복원할 수 없다는 안내가 표시되면 실제 설정을 확인하세요. 브라우저 동기화나 다른 창에서 동시에 설정을 변경할 경우 이 과정을 기기 간 트랜잭션으로 이해해서는 안 됩니다.
03원격 주소에서 불러오기
원격 설정은 로컬 백업과 동일한 JSON 내용을 사용합니다. 이는 수동으로 한 번 불러와 가져오는 작업이며 자동으로 업데이트되는 구독이 아닙니다.
- 먼저 설정 백업을 내보내거나 아래 설명에 따라 JSON 파일을 준비합니다.
- 대상 브라우저에서 접근할 수 있는 HTTPS 서비스에 파일을 올리고 JSON 내용을 직접 반환하는 전체 주소를 확보합니다. 예:
https://example.com/ua-pro/config.json. 이 주소는 예시이므로 실제 사용하는 주소로 바꾸세요. - UA Pro에서 “더보기” → “설정 가져오기/내보내기”로 이동해 “원격 설정”을 펼치고 주소를 붙여 넣은 후 “불러오기”를 클릭합니다.
- 불러오기와 형식 검사를 통과하면 확장 프로그램에 확인 창과 원격 호스트 이름이 표시됩니다. “구성 내용 보기”를 클릭하면 실제 다운로드한 전체 JSON을 확인할 수 있습니다. 확인하면 로컬 가져오기와 동일한 규칙으로 설정이 업데이트되며 취소하면 가져오지 않습니다.
- 서버의 파일이 변경된 후 새 내용을 사용하려면 주소를 다시 입력하고 불러온 다음 확인해야 합니다. 패널을 다시 열 때 주소는 자동으로 유지되지 않습니다.
HTTPS 직접 링크만 허용하며 HTTP, 주소의 사용자 이름이나 비밀번호, URL 프래그먼트는 허용하지 않고 리디렉션도 따르지 않습니다. 요청에는 브라우저 Cookie나 로그인 자격 증명이 포함되지 않고 Referer를 전송하지 않으며 캐시를 우회합니다. 따라서 로그인 Cookie가 필요한 서비스는 사용할 수 없습니다. UA Pro는 이 확장 프로그램에 설정된 UA 규칙을 해당 요청에 적용하지 않지만 다른 확장 프로그램이나 네트워크 장치가 요청을 변경할 수 있습니다. 주소에 쿼리 매개변수를 넣을 수 있으며 액세스 토큰이 포함된 주소는 비밀번호처럼 보관해야 합니다. 신뢰할 수 있는 주소를 사용하고 응답이 로그인 페이지나 코드를 표시하는 HTML 페이지가 아닌 JSON 파일 자체인지 확인하세요.
로컬 파일과 원격 응답의 크기는 각각 128 KiB로 제한됩니다. 원격 읽기는 10초로 제한되며 실제 읽은 내용의 크기를 계산합니다. 브라우저 동기화 저장소에는 더 작은 단일 항목 할당량이 있으므로 파일이 128 KiB 이하여도 규칙이나 단일 라이브러리가 너무 크면 저장하지 못할 수 있습니다. 오류가 발생하면 서버가 상태 200과 유효한 JSON을 반환하는지, 인증서가 유효한지, 주소가 리디렉션되는지, 네트워크에 연결할 수 있는지 확인하세요.
04전체 JSON 예제
다음 예제는 UTF-8로 인코딩된 config.json 파일로 저장할 수 있습니다. 예제 도메인과 UA 값은 설명용입니다. 교체하기 전에 기존 설정을 백업하세요. JSON은 대소문자를 구분하며 문자열에 영문 큰따옴표를 사용합니다. 마지막 요소 뒤에는 쉼표를 붙이지 말고 JSON 안에 주석을 작성하지 마세요.
{
"version": 2,
"type": "ua-switcher-config",
"timestamp": "2026-11-16T06:00:00.000Z",
"data": {
"globalRule": {
"enabled": true,
"mode": "builtin",
"params": {
"os": "Windows",
"uaKey": "Edge 125 (Latest)"
}
},
"domainRules": {
"example.com": {
"enabled": true,
"mode": "custom",
"params": {
"category": "手机示例",
"value": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
}
},
"app.example.com": {
"enabled": true,
"mode": "append",
"params": {
"category": "测试标记",
"value": "MyApp/1.0"
}
},
"random.example.com": {
"enabled": true,
"mode": "random",
"params": {
"pool": "custom:随机示例",
"strategy": "page"
}
},
"paused.example.com": {
"enabled": false,
"mode": "custom",
"params": {
"category": "测试",
"value": "ExampleAgent/1.0"
}
}
},
"userCustomData": {
"手机示例": [
"Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
],
"随机示例": [
"ExampleAgent/1.0",
"ExampleAgent/2.0"
],
"测试": [
"ExampleAgent/1.0"
]
},
"userAppendData": {
"测试标记": [
"MyApp/1.0"
]
},
"resourceDomainFallback": false
}
}
이 예제는 내장 전역 UA 하나와 도메인 규칙 네 개를 설정합니다. app.example.com처럼 더 구체적인 하위 도메인 규칙은 example.com보다 우선합니다. 일시 중지된 규칙은 활성 일치에 참여하지 않으며 상위 도메인이나 전역 규칙이 대신 적용될 수 있습니다. 실제 사이트가 예제 UA를 인식할 수 있는지는 해당 사이트에 달려 있습니다.
05최상위 필드와 덮어쓰기 동작
| 필드 | 예제 | 용도 |
|---|---|---|
version |
2 |
필수. 새 버전은 숫자 2만 허용합니다. |
type |
"ua-switcher-config" |
필수. 설정 유형 식별자로, 이 문자열과 정확히 일치해야 합니다. |
timestamp |
"2026-11-16T06:00:00.000Z" |
필수. 밀리초와 Z가 포함된 UTC 시간을 사용합니다. 기록용이며 규칙의 적용 시각을 결정하지 않습니다. |
data |
{ ... } |
필수. 전체 설정을 담는 객체로 아래 표의 모든 필드를 포함합니다. |
data의 필드 |
올바른 형식 | 이 버전에서 가져올 때의 동작 |
|---|---|---|
globalRule |
규칙 객체 하나 또는 null |
규칙 객체는 기존 전역 규칙을 교체하고 null은 기존 전역 규칙을 지웁니다. |
domainRules |
{ "域名": 规则对象 } |
객체 전체가 기존 도메인 규칙을 교체하며 {}은 모든 규칙을 비웁니다. |
userCustomData |
{ "分类": ["UA", ...] } |
객체 전체가 기존 사용자 지정 UA 라이브러리를 교체하며 {}은 그 내용을 비웁니다. |
userAppendData |
{ "分类": ["追加文本", ...] } |
객체 전체가 기존 추가 텍스트 라이브러리를 교체하며 {}은 그 내용을 비웁니다. |
resourceDomainFallback |
true 또는 false |
JSON 불리언 값: 리소스 도메인 대체 규칙을 켜거나 끕니다. |
다섯 필드는 모두 필수이며 globalRule 이외에는 null을 사용할 수 없습니다. 누락되거나 알 수 없는 필드와 중복 JSON 키는 거부됩니다. 이전 버전이나 일부만 포함된 설정도 가져올 수 없습니다. 도메인 규칙과 두 라이브러리는 각각 전체가 교체됩니다. 예를 들어 도메인 하나만 포함한 domainRules를 제공하면 대상 브라우저에 있던 다른 도메인 규칙도 교체됩니다. 새 버전에서 실제로 내보낸 파일을 바탕으로 편집하고 필요한 항목을 모두 보존하는 것이 좋습니다.
리소스 도메인 대체 규칙은 기본 페이지에 유효한 탭, 도메인 또는 전역 UA가 없을 때에만 리소스 요청의 대상 도메인에 따라 규칙을 적용할 수 있습니다. 모든 교차 도메인 리소스가 기본 페이지의 규칙을 덮어쓴다는 뜻은 아닙니다.
06규칙 객체 작성 방법
전역 규칙과 각 도메인 규칙은 같은 구조를 사용합니다.
{
"enabled": true,
"mode": "custom",
"params": {
"category": "常用",
"value": "ExampleAgent/1.0"
}
}
enabled: true은 활성화, false은 일시 중지를 뜻합니다. mode에 따라 params의 필드가 결정됩니다.
6.1 내장 UA: builtin
{
"enabled": true,
"mode": "builtin",
"params": { "os": "Windows", "uaKey": "Edge 125 (Latest)" }
}
os과 uaKey은 해당 확장 프로그램 버전에 내부적으로 사전 설정된 키와 정확히 일치해야 하며 인터페이스에 번역되어 표시되는 문구와 반드시 같지는 않습니다. 가장 확실한 방법은 화면에서 사전 설정을 선택하고 설정을 내보낸 뒤 해당 params를 복사하는 것입니다. 버전에 따라 사전 설정 목록이 바뀌면 다시 확인하세요.
6.2 사용자 지정 UA: custom
{
"enabled": true,
"mode": "custom",
"params": { "category": "常用", "value": "ExampleAgent/1.0" }
}
value은 전체 UA 문자열입니다. category은 분류와 화면 편집에 사용되며 userCustomData의 같은 이름의 분류에도 이 값을 포함하는 것이 좋습니다. 규칙이 적용될 때 읽는 값은 규칙 자체의 value입니다. 규칙을 직접 가져와도 이 값이 사용자 지정 라이브러리에 자동으로 추가되지는 않습니다.
6.3 텍스트 추가: append
{
"enabled": true,
"mode": "append",
"params": { "category": "应用标记", "value": "MyApp/1.0" }
}
확장 프로그램은 현재 브라우저의 원래 UA 뒤에 공백 하나를 넣고 value을 추가합니다. userAppendData의 같은 이름의 분류에도 이 텍스트를 보관하는 것이 좋습니다. 규칙을 가져와도 목록이 자동으로 채워지지는 않습니다.
6.4 무작위 UA: random
{
"enabled": true,
"mode": "random",
"params": { "pool": "custom:随机示例", "strategy": "page" }
}
strategy은 "page"(전체 페이지를 불러올 때마다 추출) 또는 "tab"(규칙과 탭별로 유지)여야 합니다. 무작위 추출은 중복을 허용하므로 두 번 연속 같더라도 다시 추출하지 않았다는 뜻은 아닙니다.
자주 사용하는 pool 값:
| 값 | 무작위 출처 |
|---|---|
all |
모든 내장 UA, 사용자 지정 UA 및 추가 텍스트로 생성한 UA |
builtin |
모든 내장 UA |
builtin_desktop, builtin_mobile, builtin_legacy |
내장 데스크톱, 모바일 또는 레거시 기기 분류 |
builtin_gaming, builtin_smarttv, builtin_communication, builtin_social |
해당 내장 분류 |
custom |
모든 사용자 지정 분류의 UA |
custom:分类名 |
userCustomData에서 지정한 분류의 UA |
append_all |
모든 추가 텍스트에 해당하는 UA |
append:分类名 |
userAppendData에서 지정한 분류의 추가 텍스트에 해당하는 UA |
콜론 뒤의 분류 이름은 라이브러리의 키와 일치해야 합니다. 활성화된 무작위 규칙에 사용 가능한 후보가 없으면 파일이 거부됩니다.
07직접 편집할 때 확인 사항
domainRules의 키에는example.com,shop.example.com처럼 도메인을 적고https://, 경로, 포트 또는 공백은 적지 마세요. 도메인 규칙은 하위 도메인에도 일치합니다. 현재 버전에서*.example.com는example.com자체도 포함하며 “하위 도메인만”을 뜻하지 않습니다.- 분류 이름에는 중국어를 사용할 수 있으며 비어 있지 않은 문자열이어야 합니다. 제어 문자나 위험한 양방향 텍스트 제어 문자는 포함할 수 없으며
__proto__,prototype,constructor는 분류 이름으로 사용할 수 없습니다. UA와 추가 텍스트에는 인쇄 가능한 ASCII 문자를 사용하는 것이 좋습니다. 줄 바꿈, 탭 또는 기타 제어 문자는 포함하지 마세요. UA 하나는 최대 4096자입니다. 텍스트의 영문 큰따옴표와 역슬래시는 JSON 규칙에 따라 이스케이프해야 합니다. - 각 분류는 문자열 배열에 대응합니다(예:
"常用": ["Agent/1.0", "Agent/2.0"]). 항목이 하나뿐이어도 대괄호를 유지하세요. 빈 분류는[]로 쓸 수 있습니다. true,false,null는 큰따옴표로 감싸면 안 됩니다."false"은 불리언이 아닌 문자열입니다.- 파일은 유효한 UTF-8 및 JSON이어야 하며 중복 키는 허용되지 않습니다. 확장 프로그램은 구조, 필드 유형, 규칙, 사전 설정 이름과 무작위 풀도 검사합니다. 구문이 올바르더라도 규칙을 반드시 사용할 수 있는 것은 아닙니다.
설정 파일은 브라우저가 웹사이트에 보내는 UA를 변경할 수 있습니다. HTTPS는 전송을 보호하지만 서버가 제공하는 설정이 의도에 맞는다는 보장은 하지 않습니다. 신뢰할 수 있는 출처의 파일만 가져오고 확인 전에 내용을 살펴본 뒤 대상 페이지를 새로고침하여 실제 결과를 확인하세요.
08자주 묻는 질문
| 증상 | 확인 방법 |
|---|---|
| 파일 형식이 올바르지 않다는 메시지가 표시됨 | UTF-8, JSON 구문, 중복 키, 버전, 필수 필드와 규칙 유형을 확인하고 새 버전의 내보내기 파일을 템플릿으로 사용하세요. |
| 원격 불러오기 실패 | HTTPS 인증서, 직접 링크, 네트워크와 반환된 내용을 확인하세요. 리디렉션, Cookie 로그인 및 HTTP는 허용되지 않습니다. |
| 가져온 후 규칙이 줄어듦 | 도메인 규칙과 두 라이브러리는 각각 전체가 교체됩니다. 가져오기 전 백업에서 복원하거나 새 파일에 유지할 항목을 추가하세요. |
| 빈 전역 규칙을 가져왔는데 웹페이지에서 여전히 다른 UA를 사용함 | 기존 탭 규칙 또는 일치하는 도메인 규칙을 확인하세요. 이 규칙들은 전역 규칙보다 우선할 수 있습니다. |
| 성공으로 표시되지만 UA가 올바르지 않음 | 규칙이 활성화되어 있는지, 내용이 유효한지, 무작위 풀에 사용 가능한 항목이 있는지, 더 우선순위가 높은 탭 또는 도메인 규칙이 있는지 확인한 다음 페이지를 새로고침하세요. |
| 데이터가 많을 때 가져오기 중 저장소 오류가 발생함 | 파일과 브라우저 동기화 저장소에는 모두 크기 제한이 있습니다. 규칙이나 목록을 줄여 다시 시도하고 기존 설정을 확인하세요. |
| 원격 파일을 수정해도 확장 프로그램에 변화가 없음 | 원격 불러오기는 수동으로 한 번 가져오는 작업입니다. 주소를 다시 입력하고 불러온 후 확인하세요. |