Node Device Detection
This project contains 51Degrees Device Detection engines that can be used with the Pipeline API.
The Pipeline is a generic web request intelligence and data processing solution with the ability to add a range of 51Degrees and/or custom plug ins (Engines)
Device detection can be performed 'on-premise' using a local data file or via the 51Degrees cloud service. On-premise provides better performance, while cloud is easier to deploy.
Both options use the same evidence values and expose (almost all) the same properties, so can be swapped out if needed at a later date.
For runtime dependencies, see our dependencies page. The tested versions page shows the Node versions that we currently test against. The software may run fine against other versions, but additional caution should be applied.
The API can either use our cloud service to get its data or it can use a local (on-premise) copy of the data.
You will require a resource key to use the Cloud API. You can create resource keys using our configurator, see our documentation on how to use this.
In order to perform device detection on-premise, you will need to use a 51Degrees data file. This repository includes a free, 'lite' file in the 'device-detection-data' sub-module that has a significantly reduced set of properties. To obtain a file with a more complete set of device properties see the 51Degrees website. If you want to use the lite file, you will need to install GitLFS:
sudo apt-get install git-lfs
git lfs install
Then, navigate to 'fiftyone.devicedetection.onpremise/device-detection-cxx/device-detection-data' and execute:
git lfs pull
Using NPM call:
npm install fiftyone.devicedetection
npm install fiftyone.devicedetection.cloud
npm install fiftyone.devicedetection.onpremise
Device detection on-premise uses a native binary. (i.e. compiled from C code to target a specific platform/architecture) The NPM package contains several binaries for common platforms. However, in some cases, you'll need to build the native binaries yourself for your target platform. This section explains how to do this.
npm install node-gyp --global
v142
10.0.18362.0
sudo apt-get install g++ make libatomic1
git submodule update --init --recursive
binding.51d
to binding.gyp
npm install
build
.node-gyp configure
node-gyp build
10.0.18362.0
.--msvs_version=[VS version]
and --msvs_target_platform_version=[Windows SDK Version]
as part of the npm install
command.FiftyOneDeviceDetectionHashV4.node
under build/Release
folder.FiftyOneDeviceDetectionHashV4.node
to build
directory (which is one level up) and rename it using the following convention.
WARNING
: npm install
removes this copied file, so you will need to do the above steps again after running npm install
For details of how to run the examples, please refer to run examples. The tables below describe the examples that are available.
Example | Description |
---|---|
configurator-console | Shows how to call the cloud with the created key and how to access the values of the selected properties. |
gettingstarted-console | How to use the 51Degrees Cloud service to determine details about a device based on its User-Agent and User-Agent Client Hints HTTP header values. |
gettingstarted-web | How to use the 51Degrees Cloud service to determine details about a device as part of a simple web server. |
metadata-console | How to access the meta-data that relates to the device detection algorithm. |
nativemodellookup-console | How to get device details based on a given 'native model name' using the 51Degrees cloud service. |
taclookup-console | How to get device details based on a given TAC (Type Allocation Code) using the 51Degrees cloud service. |
useragentclienthints-web | This is now deprecated. Kept for testing purposes. Please see gettingstarted-web instead. |
Example | Description |
---|---|
automaticupdates/dataFileSystemWatcher.js | How to configure automatic updates using the file system watcher to monitor for changes to the data file. |
automaticupdates/updateOnStartUp.js | How to configure the Pipeline to automatically update the device detection data file on startup. |
automaticupdates/updatePollingInterval.js | Ho to configure and verify the various automatic data file update settings. |
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 | How to use the 51Degrees Cloud service to determine details about a device as part of a simple web server. |
matchmetrics-console | How to view metrics associated with the results of processing with a Device Detection engine. |
metadata-console | How to access the meta-data that relates to the device detection algorithm. |
offlineprocessing-console | How to process data for later viewing using a Device Detection Hash data file. |
performance-console | How to configure the various performance options and run a simple performance test. |
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 | This is now deprecated. Kept for testing purposes. Please see gettingstarted-web instead. |
Example | Description |
---|---|
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. |
In this repository, there are tests for the examples. You will need to install jest to run them:
npm install jest --global
You will also need to install any required packages for the examples in the Examples section.
Add a 51Degrees cloud resource key in the fiftyone.devicedetection/package.json file for cloud tests. You can obtain a resource key from the 51Degrees Cloud Configurator and assign it to the environment variable RESOURCE_KEY
in your test environment.
There are other environment variables that you will also need to set in your test environment before running all tests:
TEST_SUPER_RESOURCE_KEY
: This key contains all SetHeader*
properties.TEST_PLATFORM_RESOURCE_KEY
: This key contains only the SetHeaderPlatform*
property but no other SetHeader
properties.TEST_HARDWARE_RESOURCE_KEY
: This key contains only the SetHeaderHardware*
property but no other SetHeader
properties.TEST_BROWSER_RESOURCE_KEY
: This key contains only the SetHeaderBrowser*
property but no other SetHeader
properties.TEST_NO_SETHEADER_RESOURCE_KEY
: This key contains no SetHeader
properties.To run the tests, execute the following command in the root directory or a sub-module directory:
npm test
Process for rebuilding SWIG interfaces following an update to the device detection cxx code (This is only intended to be run by 51Degrees developers internally):
Types are generated and exported automatically from JSDoc comments using this script. Upon generation types are committed into the repository into the package's types
directory. Calling the generation step is manual for now, but later will be added as part of CI/CD pipeline.
The TypeScript example with typechecking enabled is available under onpremise/gettingstarted-console/gettingStarted.ts
.
The example can be run as:
npx ts-node gettingStarted.ts