1 |
|
2 |
|
3 | # egjs-agent
|
4 | [![npm version](https://img.shields.io/npm/v/@egjs/agent.svg?style=flat-square&color=007acc&label=version)](https://www.npmjs.com/package/@egjs/agent) [![Build Status](https://img.shields.io/travis/naver/egjs-agent.svg?style=flat-square&label=build)](https://travis-ci.org/naver/egjs-agent) [![Coverage Status](https://img.shields.io/coveralls/github/naver/egjs-agent.svg?style=flat-square&label=coverage)](https://coveralls.io/github/naver/egjs-agent?branch=master)
|
5 | ![Support TypeScript](https://img.shields.io/static/v1.svg?label=&message=TypeScript&color=294E80&style=flat-square&logo=typescript)
|
6 |
|
7 | Extracts browser and operating system information from the user agent string or user agent object(userAgentData).
|
8 |
|
9 | ## Documents
|
10 | - [Get Started and Demos](https://naver.github.io/egjs-agent/)
|
11 | - [API documentation](https://naver.github.io/egjs-agent/release/latest/doc/)
|
12 | - [Prepare for Client Hints, freezing User Agent](https://medium.com/naver-fe-platform/prepare-for-client-hints-freezing-user-agent-9c0ea1ddd02c)
|
13 |
|
14 | ## Download and Installation
|
15 |
|
16 | Download dist files from repo directly or install it via npm.
|
17 |
|
18 | ### Installation with npm
|
19 |
|
20 | The following command shows how to install egjs-agent using npm.
|
21 |
|
22 | ```bash
|
23 | $ npm install @egjs/agent
|
24 | ```
|
25 |
|
26 | ### For development
|
27 |
|
28 | You can download the files for development
|
29 |
|
30 | * Latest : https://naver.github.io/egjs-agent/release/latest/dist/agent.js
|
31 | * Latest(min): https://naver.github.io/egjs-agent/release/latest/dist/agent.min.js
|
32 | * Specific version : https://naver.github.io/egjs-agent/release/[VERSION]/dist/agent.js
|
33 | * Specific version(min): https://naver.github.io/egjs-agent/release/[VERSION]/dist/agent.min.js
|
34 |
|
35 |
|
36 | ## Prepare for Client Hints and User-Agent Reduction!
|
37 |
|
38 | Chrome was planned to freeze userAgent to improve user privacy, and it is being applied as an experimental feature in 84+.
|
39 |
|
40 | Not only Chrome, but other browsers will come someday.
|
41 |
|
42 | > It is still an experimental feature until Chrome(Chromium) 86.
|
43 | >
|
44 | > If you want to test, enable the flag below.
|
45 | >
|
46 | > **chrome://flags/#enable-experimental-web-platform-features**
|
47 | > **chrome://flags/#freeze-user-agent**
|
48 | >
|
49 | > This reduced format will be available for testing via chrome://flags/#reduce-user-agent in Chrome 93.
|
50 | > **chrome://flags/#reduce-user-agent**
|
51 |
|
52 |
|
53 | ### User-Agent Reduction Proposed Rollout Plan
|
54 | ```
|
55 | Phase 4: Chrome 101 Ship reduced Chrome MINOR.BUILD.PATCH version numbers (“0.0.0”). Once rolled-out, the reduced UA string would apply to all page loads on desktop and mobile OSes that do not opt into the reverse Origin Trial.
|
56 |
|
57 | Phase 5: Chrome 107 Begin roll-out of reduced Desktop UA string and related JS APIs (navigator.userAgent, navigator.appVersion, navigator.platform). Once rolled-out, the reduced UA string would apply to all page loads on desktop OSes that do not opt into the reverse Origin Trial.
|
58 |
|
59 | Phase 6: Chrome 110 Begin roll-out of reduced Android Mobile (and Tablet) UA string and related JS APIs. Once rolled-out, the reduced UA string would apply to all page loads on Android that do not opt into the reverse Origin Trial.
|
60 |
|
61 | Reduction Completion Phase 7: Chrome 113 reverse Origin Trial ends and all page loads receive the reduced UA string and related JS APIs.
|
62 | ```
|
63 |
|
64 | ### In the future
|
65 | 1. the following attribute values will not appear correctly.
|
66 | * navigator.userAgent
|
67 | * navigator.appVersion
|
68 | * navigator.platform
|
69 | * navigator.productSub
|
70 | * navigator.vendor
|
71 | 2. You should use `navigator.userAgentData` instead of `navigator.userAgent`.
|
72 | * Browser version only shows major.
|
73 | * OS name, OS version, Browser full version should be fetched asynchronously.
|
74 | * The only OS name that you can check synchronously are iOS and Android.
|
75 |
|
76 | ### Possible (You can know exactly)
|
77 | * Check browser name, major version
|
78 | * Check the full version under Chrome 101
|
79 | * Check mobile
|
80 | * Check OS name
|
81 | * Check Webkit, Chromium
|
82 | * Check old OS, OS Version (Chrome 84 support range or less)
|
83 | * **< Android 5.0**
|
84 | * **< Mac OS X 10.10**
|
85 | * **< Windows 7**
|
86 | * **< iOS Unknown**
|
87 |
|
88 |
|
89 | ```js
|
90 | import getAgent from "@egjs/agent";
|
91 |
|
92 | const agent = getAgent();
|
93 |
|
94 | // Check iOS
|
95 | agent.os.name === "ios"
|
96 | agent.os.majorVersion === 9
|
97 | // Check Android
|
98 | agent.os.name === "android"
|
99 | agent.os.majorVersion === 4
|
100 | parseFloat(agent.os.version) <= 4.4
|
101 | // Check browser name
|
102 | agent.browser.name === "safari"
|
103 | // Check webkit
|
104 | agent.browser.webkit
|
105 | // Check chromium
|
106 | agent.browser.chromium
|
107 | ```
|
108 |
|
109 | ### If you want to use only the method using navigator.userAgent
|
110 | ```js
|
111 | import { getLegacyAgent } from "@egjs/agent";
|
112 |
|
113 | const agent = getLegacyAgent();
|
114 | // Check iOS
|
115 | agent.os.name === "ios"
|
116 | agent.os.majorVersion === 9
|
117 | // Check Android
|
118 | agent.os.name === "android"
|
119 | agent.os.majorVersion === 4
|
120 | parseFloat(agent.os.version) <= 4.4
|
121 | // Check browser name
|
122 | agent.browser.name === "safari"
|
123 | // Check webkit
|
124 | agent.browser.webkit
|
125 | // Check chromium
|
126 | agent.browser.chromium
|
127 | ```
|
128 | ### Not Possible (If synchronous)
|
129 | * Check OS version.
|
130 | * Check Browser full version.
|
131 |
|
132 | ```js
|
133 | import getAgent from "@egjs/agent";
|
134 | const agent = getAgent();
|
135 |
|
136 | // If the full version is 10.5, it is displayed as 10.
|
137 | agent.browser.version
|
138 | // "unknown"
|
139 | agent.os.name
|
140 | // -1
|
141 | agent.os.majorVersion
|
142 | ```
|
143 |
|
144 | ### Possible (If asynchronous)
|
145 | * You can get accurate agent information.
|
146 | * Check OS version.
|
147 | * Check Browser full version.
|
148 | ```js
|
149 | import { getAccurateAgent } from "@egjs/agent";
|
150 |
|
151 | // Use Promise
|
152 | getAccurateAgent().then(agent => {
|
153 | // Check OS version
|
154 | agent.os.version
|
155 |
|
156 | // Check Browser full verion
|
157 | agent.browser.version
|
158 | });
|
159 |
|
160 | // Use Callback
|
161 | getAccurateAgent(agent => {});
|
162 | ```
|
163 |
|
164 | ### If you dare to use synchrous, you have to choose.
|
165 | * If you're checking a version (ex. 93.0.1234.56) lower than Chrome 101 to fix the bug, there shouldn't be a problem.
|
166 | * However, if you need to check the minor or patch version of version 101 or higher, you have to check it asynchronously.
|
167 | * You can check the OS name, but if you want to check the OS version, consider switching to asynchronous before reduction is applied.
|
168 |
|
169 |
|
170 | ## Supported Browsers
|
171 | The following are the supported browsers.
|
172 |
|
173 | |Internet Explorer|Chrome|Firefox|Safari|iOS|Android|
|
174 | |---|---|---|---|---|---|
|
175 | |7+|latest|latest|latest|3+|2.1+|
|
176 |
|
177 | ### Client Hints Support
|
178 |
|
179 | Chromium (Chrome, Edge, Whale)|Gecko (Firefox)|Webkit (Safari)|
|
180 | |---|---|---|
|
181 | |84+ (Experimental)|Unknown|Unknown|
|
182 |
|
183 |
|
184 |
|
185 |
|
186 | ## How to start developing egjs-agent?
|
187 |
|
188 | For anyone interested to develop egjs-agent, follow the instructions below.
|
189 |
|
190 | ### Development Environment
|
191 |
|
192 | #### 1. Clone the repository
|
193 |
|
194 | Clone the egjs-agent repository and install the dependency modules.
|
195 |
|
196 | ```bash
|
197 | # Clone the repository.
|
198 | $ git clone https://github.com/naver/egjs-agent.git
|
199 | ```
|
200 |
|
201 | #### 2. Install dependencies
|
202 | `npm` is supported.
|
203 |
|
204 | ```
|
205 | # Install the dependency modules.
|
206 | $ npm install
|
207 | ```
|
208 |
|
209 | #### 3. Build
|
210 |
|
211 | Use npm script to build eg.agent
|
212 |
|
213 | ```bash
|
214 | # Run rollup
|
215 | $ npm start
|
216 |
|
217 | # Build
|
218 | $ npm run build
|
219 |
|
220 | # Generate jsdoc
|
221 | $ npm run jsdoc
|
222 | ```
|
223 |
|
224 | Two folders will be created after complete build is completed.
|
225 |
|
226 | - **dist** folder: Includes the **agent.js** and **agent.min.js** files.
|
227 | - **doc** folder: Includes API documentation. The home page for the documentation is **doc/index.html**.
|
228 |
|
229 | ### Linting
|
230 |
|
231 | To keep the same code style, we adopted [ESLint](http://eslint.org/) to maintain our code quality.
|
232 | Setup your editor for check or run below command for linting.
|
233 |
|
234 | ```bash
|
235 | $ npm run lint
|
236 | ```
|
237 |
|
238 | ### Test
|
239 |
|
240 | Once you created a branch and done with development, you must perform a test running `npm run test` command before you push code to a remote repository.
|
241 |
|
242 | ```bash
|
243 | $ npm run test
|
244 | ```
|
245 | Running a `npm run test` command will start [Jest](https://jestjs.io/).
|
246 |
|
247 |
|
248 | ## Bug Report
|
249 |
|
250 | If you find a bug, please report it to us using the [Issues](https://github.com/naver/egjs-agent/issues) page on GitHub.
|
251 |
|
252 |
|
253 | ## License
|
254 | egjs-agent is released under the [MIT license](http://naver.github.io/egjs/license.txt).
|
255 |
|
256 |
|
257 | ```
|
258 | Copyright (c) 2015 NAVER Corp.
|
259 |
|
260 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
261 | of this software and associated documentation files (the "Software"), to deal
|
262 | in the Software without restriction, including without limitation the rights
|
263 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
264 | copies of the Software, and to permit persons to whom the Software is
|
265 | furnished to do so, subject to the following conditions:
|
266 |
|
267 | The above copyright notice and this permission notice shall be included in
|
268 | all copies or substantial portions of the Software.
|
269 |
|
270 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
271 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
272 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
273 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
274 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
275 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
276 | THE SOFTWARE.
|
277 | ```
|