fiftyone.devicedetection.onpremise 4.4.132 → 4.4.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiftyone.devicedetection.onpremise",
-  "version": "4.4.132",
+  "version": "4.4.133",
   "description": "Device detection on-premise services for the 51Degrees Pipeline API",
   "keywords": [
     "51degrees",

package/readme.md

@@ -13,13 +13,15 @@ This package provides a On-Premise implementation of Device Detection engine whi
 
 This package requires the following additional packages:
 
-- **fiftyone.devicedetection.shared** - A Node.js module which contains shared functionality to build cloud and on-premise engines.
+- [**fiftyone.devicedetection.shared**](/fiftyone.devicedetection.shared#readme) - A Node.js module which contains shared functionality to build cloud and on-premise engines.
 
 ### Installation
 
 Using NPM call:
 
-`npm install fiftyone.devicedetection.onpremise`
+```
+npm install fiftyone.devicedetection.onpremise
+```
 
 ### On-Premise
 When running on-premise, a local Hash V4.1 data file is required.
@@ -29,65 +31,87 @@ When running on-premise, a local Hash V4.1 data file is required.
 51Degrees provides [multiple options](https://51degrees.com/Licencing-Pricing/On-Premise), some of which support automatic updates through the Pipeline API.
 
 If the module is installed directly from Git then the binaries are also required. These binaries are native module which contains the core engine of device detection. Below are the steps to build these binaries:
-- Pre-requisites
-  - Install Node.js.
-  - Install node-gyp by running.
-    - `npm install node-gyp --global`  
-  - Install C build tools:
-    - Windows:
-      - You will need either Visual Studio 2019 or the [C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) installed.
-If you have Visual Studio Code, you'll still need to install the build tools from the link above.
-    - Linux/MacOS:
-      - You will need a C++ compiler which supports C++11. The compiler will and other build tools will be selected by CMake automatically based on your environment.
-- Build steps:
-  - Navigate to fiftyone.devicedetection.onpremise.
-  - Create a folder named `build`.
-  - Rename the `binding.51d` to `binding.gyp`
-  - Run `node-gyp configure`
-  - Run `node-gyp build`
-    - This will build the `FiftyOneDeviceDetectionHashV4.node` under `build/Release` folder.
-  - Copy the `FiftyOneDeviceDetectionHashV4.node` to `build` directory (which is one level up) and rename it using the following convention.
-    - Windows:
-      - FiftyOneDeviceDetectionHashV4-win32-[ Node version ].node
-        - e.g. FiftyOneDeviceDetectionHashV4-win32-10.node for Node 10.
-    - Linux:
-      - FiftyOneDeviceDetectionHashV4-linux-[ Node version ].node
-        - e.g. FiftyOneDeviceDetectionHashV4-linux-10.node for Node 10.
-    - MacOS:
-      - FiftyOneDeviceDetectionHashV4-darwin-[ Node version ].node
-        - e.g. FiftyOneDeviceDetectionHashV4-darwin-10.node for Node 10.
-    - Please see [Support Version](https://51degrees.com/documentation/_info__version_support.html) for Node versions that we support.
-    - At this point, other build files and folders can be removed apart from the binaries file *.node.
+#### Pre-requisites
+
+- Install Node.js.
+- Install node-gyp by running.
+  - `npm install node-gyp --global`  
+- Install C build tools:
+  - Windows:
+    - You will need either Visual Studio 2019 or the [C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) installed.
+      - Minimum platform toolset version is `v142`
+      - Minimum Windows SDK version is `10.0.18362.0`
+  - Linux/MacOS:
+    - `sudo apt-get install g++ make libatomic1`
+- Pull git submodules:
+  - `git submodule update --init --recursive`
+
+#### Build Steps 
+
+- Navigate to fiftyone.devicedetection.onpremise
+- Rename the `binding.51d` to `binding.gyp`
+- Run `npm install`
+  - Alternatively this step can be replaced by the followings:
+    - Create a folder named `build`.
+    - Run `node-gyp configure`
+    - Run `node-gyp build`
+  - Platform specific:
+    - Windows
+      - By default this will look for Visual Studio 2019 and a minimum Windows SDK version `10.0.18362.0`.
+      - This can be overwritten by include `--msvs_version=[VS version]` and `--msvs_target_platform_version=[Windows SDK Version]` as part of the `npm install` command.
+        - **NOTE**: This is not recommended. Also, some time the latest SDK version is selected instead, as observed in environment with multiple SDK versions installed. Thus, only install the correct Visual Studio version and the minimum required Windows SDK version as recommended.
+- This will build the `FiftyOneDeviceDetectionHashV4.node` under `build/Release` folder.
+- Copy the `FiftyOneDeviceDetectionHashV4.node` to `build` directory (which is one level up) and rename it using the following convention.
+  - Windows:
+    - FiftyOneDeviceDetectionHashV4-win32-[ Node version ].node
+      - e.g. FiftyOneDeviceDetectionHashV4-win32-10.node for Node 10.
+  - Linux:
+    - FiftyOneDeviceDetectionHashV4-linux-[ Node version ].node
+      - e.g. FiftyOneDeviceDetectionHashV4-linux-10.node for Node 10.
+  - MacOS:
+    - FiftyOneDeviceDetectionHashV4-darwin-[ Node version ].node
+      - e.g. FiftyOneDeviceDetectionHashV4-darwin-10.node for Node 10.
+  - Please see the [tested versions page](https://51degrees.com/documentation/_info__tested_versions.html) for Node versions that we currently test against. The software may run fine against other versions, but extra caution should be applied.
+  - You can optionally clear up by removing all the build files and folders except for the *.node file that's been created.
+  - `WARNING`: `npm install` removes this copied file, so you will need to do the above steps again after running `npm install`
 
-### Examples
 
-Some examples require 'n-readlines' to run, so you will need to install it:
+### Examples
 
-`npm install n-readlines`
+For details of how to run the examples, please refer to [run examples](/run_examples.md).
+The tables below describe the examples that are available.
 
-List of examples:
+| Example                                | Description |
+|----------------------------------------|-------------|
+| [automaticupdates/dataFileSystemWatcher.js](/fiftyone.devicedetection.onpremise/examples/onpremise/automaticupdates/dataFileSystemWatcher.js) | How to configure automatic updates using the file system watcher to monitor for changes to the data file. |
+| [automaticupdates/updateOnStartUp.js](/fiftyone.devicedetection.onpremise/examples/onpremise/automaticupdates/updateOnStartUp.js)    | How to configure the Pipeline to automatically update the device detection data file on startup. |
+| [automaticupdates/updatePollingInterval.js](/fiftyone.devicedetection.onpremise/examples/onpremise/automaticupdates/updatePollingInterval.js) | Ho to configure and verify the various automatic data file update settings. |
+| [gettingstarted-console](/fiftyone.devicedetection.onpremise/examples/onpremise/gettingstarted-console)                | How to use the 51Degrees on-premise device detection API to determine details about a device based on its User-Agent and User-Agent Client Hints HTTP header values. |
+| [gettingstarted-web](/fiftyone.devicedetection.onpremise/examples/onpremise/gettingstarted-web)                     | How to use the 51Degrees Cloud service to determine details about a device as part of a simple web server. |
+| [matchmetrics-console](/fiftyone.devicedetection.onpremise/examples/onpremise/matchmetrics-console)                   | How to view metrics associated with the results of processing with a Device Detection engine. |
+| [metadata-console](/fiftyone.devicedetection.onpremise/examples/onpremise/metadata-console)                       | How to access the meta-data that relates to the device detection algorithm. |
+| [offlineprocessing-console](/fiftyone.devicedetection.onpremise/examples/onpremise/offlineprocessing-console)              | How to process data for later viewing using a Device Detection Hash data file. |
+| [performance-console](/fiftyone.devicedetection.onpremise/examples/onpremise/performance-console)                    | How to configure the various performance options and run a simple performance test. |
+| [updatedatafile-console](/fiftyone.devicedetection.onpremise/examples/onpremise/updatedatafile-console)                 | This example illustrates various parameters that can be adjusted when using the on-premise device detection engine, and controls when a new data file is sought and when it is loaded by the device detection software. |
+| [useragentclienthints-web](/fiftyone.devicedetection.onpremise/examples/onpremise/useragentclienthints-web)               | This is now deprecated. Kept for testing purposes. Please see **gettingstarted-web** instead. |
 
-- **configureFromFile.js** - This example shows how to configure a pipeline from a configuration file using the pipelinebuilder's buildFromConfigurationFile method.
-- **failureToMatch.js** - This example shows how the hasValue function can help make sure that meaningful values are returned when checking properties returned from the device detection engine. It also illustrates how the "allowUnmatched" parameters can be used to alter these results.
-- **gettingStarted.js** - Getting started example of using the 51Degrees device detection 'Hash' algorithm to determine whether a given User-Agent corresponds to a mobile device or not.
-- **metaData.js** - This example shows how to get properties from a pipeline's processed flowData based on their metadata, the getProperties() method and also additional meta data properties on device detection data.
-- **webIntegration.js** - This example demonstrates the evidence.addFromRequest() method and client side JavaScript overrides by creating a web server, serving JavaScript created by the device detection engine and bundled together by a special JavaScript bundler engine. This JavaScript is then used on the client side to save a cookie so that when the device detection engine next processes the request (using the addFromRequest() method) it has a more accurate reading for properties set on the client side.
-- **matchMetrics.js** - This example shows how to get information about the detection result such as the algorithm that was used to perform the detection.
-- **offlineProcessing.js** - This example shows how to process a CSV file containing User-Agent strings and produce an output csv containing the source User-Agent strings with IsMobile, PlatformName and PlatformVersion properties appended.
-- **performance.js** - The examples demonstrates the performance of the HighPerformance device detection configuration.
 
 ## Tests
 
 In this repository, there are tests for the examples. 
 You will need to install jest to run them:
 
-`npm install jest --global`
+```
+npm install jest --global
+```
 
 You will also need to install any required packages for the examples in the **Examples** section.
 
 To run the tests, navigate to the module directory and execute:
 
-`npm test`
+```
+npm test
+```
 
 ## Native code updates
 
@@ -106,3 +130,4 @@ Process for rebuilding SWIG interfaces following an update to the device detecti
 5. Run the 'Build Device Detection Binaries for Node.js' Azure CI Pipeline.
 6. Copy the produced artifacts into the fiftyone.pipeline.devicedetection/build directory.
 7. Commit changes to repository.
+