From b3ece309b650f0d4da8ac7bd69cd757813c8716b Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Tue, 3 Nov 2026 21:05:09 +0000 Subject: [PATCH 01/15] Grab the Go IP Intelligence examples by their names in 51degrees-go (#285) * Grab the Go IP Intelligence examples by their names in the Go repository * Grab the Go IP Intelligence examples by their names in the Go repository * Grab the Go IP Intelligence examples by their names in the Go repository * Grab the Go IP Intelligence examples by their names in the Go repository --- src/ipintelligence/examples/datafileupdates.md | 2 +- src/ipintelligence/examples/gettingstartedconsole/onpremise.md | 2 +- src/ipintelligence/examples/offlineprocessing.md | 2 +- src/ipintelligence/examples/performance.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/ipintelligence/examples/datafileupdates.md b/src/ipintelligence/examples/datafileupdates.md index 52426fd83c..e2d4e41081 100644 --- a/src/ipintelligence/examples/datafileupdates.md +++ b/src/ipintelligence/examples/datafileupdates.md @@ -3,7 +3,7 @@ @startsnippets @grabexample{ip-intelligence-dotnet,_on_premise_2_update_data_file-_console_2_program_8cs,C#} @grabexample{ip-intelligence-java,console_2_update_data_file_8java,Java} -@grabexample{ip-intelligence-go,examples_2onpremise_2update_polling_interval_8go,Go} +@grabexample{ip-intelligence-go,update_polling_interval_2main_8go,Go} @grabexample{rust,ipi-onprem-update-data-file,Rust} @grabbedexample @endsnippets diff --git a/src/ipintelligence/examples/gettingstartedconsole/onpremise.md b/src/ipintelligence/examples/gettingstartedconsole/onpremise.md index b84283d81c..92ae137b0f 100644 --- a/src/ipintelligence/examples/gettingstartedconsole/onpremise.md +++ b/src/ipintelligence/examples/gettingstartedconsole/onpremise.md @@ -18,7 +18,7 @@ You can mix and match elements from different examples in order to match your us @grabexample{ip-intelligence-cxx,_ip_intelligence_2_getting_started_8cpp,C++} @grabexample{ip-intelligence-dotnet,_on_premise_2_getting_started-_console_2_program_8cs,C#} @grabexample{ip-intelligence-java,console_2_getting_started_on_prem_8java,Java} -@grabexample{ip-intelligence-go,examples_2onpremise_2getting_started_8go,Go} +@grabexample{ip-intelligence-go,getting_started_2main_8go,Go} @grabexample{rust,ipi-onprem-getting-started,Rust} @grabbedexample @endsnippets diff --git a/src/ipintelligence/examples/offlineprocessing.md b/src/ipintelligence/examples/offlineprocessing.md index 788b8a5003..d7e05d4f58 100644 --- a/src/ipintelligence/examples/offlineprocessing.md +++ b/src/ipintelligence/examples/offlineprocessing.md @@ -4,7 +4,7 @@ @grabexample{ip-intelligence-cxx,_ip_intelligence_2_offline_processing_8c,C} @grabexample{ip-intelligence-dotnet,_on_premise_2_offline_processing-_console_2_program_8cs,C#} @grabexample{ip-intelligence-java,console_2_offline_processing_8java,Java} -@grabexample{ip-intelligence-go,examples_2onpremise_2offline_processing_8go,Go} +@grabexample{ip-intelligence-go,offline_processing_2main_8go,Go} @grabexample{rust,ipi-onprem-offline-processing,Rust} @grabbedexample @endsnippets diff --git a/src/ipintelligence/examples/performance.md b/src/ipintelligence/examples/performance.md index 80cbf98603..3bca4e5f5d 100644 --- a/src/ipintelligence/examples/performance.md +++ b/src/ipintelligence/examples/performance.md @@ -8,7 +8,7 @@ can make on your hardware. Our own results from five machines are in the @grabexample{ip-intelligence-cxx,_ip_intelligence_2_performance_8c,C} @grabexample{ip-intelligence-dotnet,_performance-_console_2_program_8cs,C#} @grabexample{ip-intelligence-java,_performance_benchmark_8java,Java} -@grabexample{ip-intelligence-go,examples_2onpremise_2performance_8go,Go} +@grabexample{ip-intelligence-go,performance_2main_8go,Go} @grabexample{rust,ipi-onprem-performance,Rust} @grabbedexample @endsnippets From 3214916c94e98b442eb6555dc70585fdafa8a829 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Tue, 3 Nov 2026 23:34:33 +0000 Subject: [PATCH 02/15] Show the Java benchmarks from 51degrees-java and restore the .NET device detection graph (#287) --- src/productsummaries/nightlybenchmarks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/productsummaries/nightlybenchmarks.md b/src/productsummaries/nightlybenchmarks.md index 28b97438c4..ef12d1b1c7 100644 --- a/src/productsummaries/nightlybenchmarks.md +++ b/src/productsummaries/nightlybenchmarks.md @@ -3,8 +3,8 @@ | API / Product |
Device Detection
|
IP Intelligence
| |---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | C/C++ | ![dd-cxx](https://raw.githubusercontent.com/51Degrees/51degrees-cxx/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | ![ip-cxx](https://raw.githubusercontent.com/51Degrees/51degrees-cxx/gh-images/perf-graph-Ubuntu_x64_Release-LookupsPerSecond-latest.png) | -| .NET | ![dd-dotnet](https://raw.githubusercontent.com/51Degrees/51degrees-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | ![ip-dotnet](https://raw.githubusercontent.com/51Degrees/ip-intelligence-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | -| Java | ![dd-java](https://raw.githubusercontent.com/51Degrees/device-detection-java/gh-images/perf-graph-Ubuntu_Java_17-DetectionsPerSecond-latest.png) | ![ip-java](https://raw.githubusercontent.com/51Degrees/ip-intelligence-java/gh-images/perf-graph-Ubuntu_Java_8-DetectionsPerSecond-latest.png) | +| .NET | ![dd-dotnet](https://raw.githubusercontent.com/51Degrees/device-detection-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | ![ip-dotnet](https://raw.githubusercontent.com/51Degrees/ip-intelligence-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | +| Java | ![dd-java](https://raw.githubusercontent.com/51Degrees/51degrees-java/gh-images/perf-graph-Ubuntu_Java_17-DeviceDetection_DetectionsPerSecond-latest.png) | ![ip-java](https://raw.githubusercontent.com/51Degrees/51degrees-java/gh-images/perf-graph-Ubuntu_Java_8-IpIntelligence_DetectionsPerSecond-latest.png) | | Go | ![dd-go](https://raw.githubusercontent.com/51Degrees/51degrees-go/gh-images/perf-graph-Ubuntu_Go_1.24-DetectionsPerSecond-latest.png) | ![ip-go](https://raw.githubusercontent.com/51Degrees/51degrees-go/gh-images/perf-graph-Ubuntu_Go_1.24-LookupsPerSecond-latest.png) | | Node.js | ![dd-node](https://raw.githubusercontent.com/51Degrees/51degrees-node/gh-images/perf-graph-Ubuntu_Node_24-DetectionsPerSecond-latest.png) | | | Python | ![dd-python](https://raw.githubusercontent.com/51Degrees/51degrees-python/gh-images/perf-graph-Ubuntu_Python_3.13-DetectionsPerSecond-latest.png) | | From 6ba06897a7c52ac561b85b2973013f20c3e4d3db Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Wed, 4 Nov 2026 21:46:05 +0000 Subject: [PATCH 03/15] Point the data file steps at the data repository (#288) --- src/devicedetection/cloudtoonpremise.md | 2 +- .../otherintegrations/nginx.md | 6 +- src/devicedetection/quickstart.md | 55 +++++++++---------- src/snippets/example-require-datafile.txt | 12 ++-- 4 files changed, 36 insertions(+), 39 deletions(-) diff --git a/src/devicedetection/cloudtoonpremise.md b/src/devicedetection/cloudtoonpremise.md index 58e0760411..cead48cbef 100644 --- a/src/devicedetection/cloudtoonpremise.md +++ b/src/devicedetection/cloudtoonpremise.md @@ -26,7 +26,7 @@ On-premise deployment works better when you need: ## Step 1: Get License and Data File **For testing:** -- Download the free Lite data file from [GitHub](https://github.com/51degrees/device-detection-data) +- Download the free Lite data file with the scripts in the [data](https://github.com/51Degrees/data) repository on GitHub - No License Key required, but limited device properties **For production:** diff --git a/src/devicedetection/otherintegrations/nginx.md b/src/devicedetection/otherintegrations/nginx.md index 3379407c01..f206be05a5 100644 --- a/src/devicedetection/otherintegrations/nginx.md +++ b/src/devicedetection/otherintegrations/nginx.md @@ -32,7 +32,7 @@ make install STATIC_BUILD=1 ```
-Finally, run the 51Degrees tests with the default 51Degrees Lite data file included in the `device-detection-cxx\device-detection-data` directory. Make sure to build the module with `make install` command as the tests do not work on a static build. +Finally, run the 51Degrees tests with the default 51Degrees Lite data file, which the tests read from the `cxx/data/device-detection` folder. Download it first by running `sh cxx/data/get-data-files.sh 51Degrees-LiteV4.1.hash` from the repository root. The script is part of the [data](https://github.com/51Degrees/data) repository, which the `cxx` submodule includes at `cxx/data`. Make sure to build the module with `make install` command as the tests do not work on a static build. ``` make test ``` @@ -42,9 +42,9 @@ To run the 51Degrees together with the Nginx test suite, run the following comma make test-full ``` -These do not run all the required tests as some tests require properties that are not supported with the Lite version of the data file. To run all tests, obtain a data file that provides properties: JavascriptHardwareProfile, ScreenPixelsWidthJavascript, and ScreenPixelsWidth. Then, use the `FIFTYONEDEGREES_DATAFILE` variable to specify the file name to run the tests with. The new data file should be placed in the `device-detection-cxx\device-detection-data` folder and should have a different name to `51Degrees-LiteV4.1.hash`. If tests still fail, obtain a data file with any other properties used in the tests. Below is an example of running tests with a different data file named `51Degrees-EnterpriseV4.1.hash`: +These do not run all the required tests as some tests require properties that are not supported with the Lite version of the data file. To run all tests, obtain a data file that provides properties: JavascriptHardwareProfile, ScreenPixelsWidthJavascript, and ScreenPixelsWidth. Then, use the `51DEGREES_DD_PATH` variable to give the path of the data file to run the tests with. If tests still fail, obtain a data file with any other properties used in the tests. Below is an example of running tests with a different data file named `51Degrees-EnterpriseV4.1.hash`: ``` -make [test|test-full] FIFTYONEDEGREES_DATAFILE=51Degrees-EnterpriseV4.1.hash +make [test|test-full] 51DEGREES_DD_PATH=/path/to/51Degrees-EnterpriseV4.1.hash ``` # Configuring the Nginx API diff --git a/src/devicedetection/quickstart.md b/src/devicedetection/quickstart.md index b1688d00a0..93cb2abba6 100644 --- a/src/devicedetection/quickstart.md +++ b/src/devicedetection/quickstart.md @@ -84,12 +84,11 @@ C does not have a @Pipeline implementation or the ability to use the cloud-based Device Detection. To get started with C device detection On-premise: -1. Clone the GitHub [repository](https://github.com/51Degrees/51degrees-cxx). -2. Ensure you have [Git LFS](https://git-lfs.github.com/) installed. The device data files are large binary files that can cause problems if stored in a Git repository directly, so Git LFS is used. -3. Ensure all submodules are checked out by running `git submodule update --init --recursive` in the repository. -4. Follow the [installation instructions](https://github.com/51Degrees/51degrees-cxx/blob/main/README%2Emd) to get set up with the project. -5. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). -6. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. +1. Clone the GitHub [repository](https://github.com/51Degrees/51degrees-cxx) with its submodules by running `git clone --recurse-submodules https://github.com/51Degrees/51degrees-cxx.git`. In a clone you already have, run `git submodule update --init --recursive` instead. +2. Download the free Lite data file by running `sh data/get-data-files.sh 51Degrees-LiteV4.1.hash` from the repository root, or `./data/get-data-files.ps1 51Degrees-LiteV4.1.hash` in PowerShell. The scripts are part of the [data](https://github.com/51Degrees/data) repository, which is the `data` submodule. The examples also download the file themselves when it is missing. +3. Follow the [installation instructions](https://github.com/51Degrees/51degrees-cxx/blob/main/README%2Emd) to get set up with the project. +4. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). +5. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. @endsnippet @startsnippet{cxx} @@ -97,12 +96,11 @@ C++ does not have a @Pipeline implementation or the ability to use the cloud-bas Device Detection. To get started with C++ device detection On-premise: -1. Clone the GitHub [repository](https://github.com/51Degrees/51degrees-cxx). -2. Ensure you have [Git LFS](https://git-lfs.github.com/) installed. The device data files are large binary files that can cause problems if stored in a Git repository directly, so Git LFS is used. -3. Ensure all submodules are checked out by running `git submodule update --init --recursive` in the repository. -5. Follow the [installation instructions](https://github.com/51Degrees/51degrees-cxx/blob/main/README%2Emd) to get set up with the project. -6. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). -7. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. +1. Clone the GitHub [repository](https://github.com/51Degrees/51degrees-cxx) with its submodules by running `git clone --recurse-submodules https://github.com/51Degrees/51degrees-cxx.git`. In a clone you already have, run `git submodule update --init --recursive` instead. +2. Download the free Lite data file by running `sh data/get-data-files.sh 51Degrees-LiteV4.1.hash` from the repository root, or `./data/get-data-files.ps1 51Degrees-LiteV4.1.hash` in PowerShell. The scripts are part of the [data](https://github.com/51Degrees/data) repository, which is the `data` submodule. The examples also download the file themselves when it is missing. +3. Follow the [installation instructions](https://github.com/51Degrees/51degrees-cxx/blob/main/README%2Emd) to get set up with the project. +4. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). +5. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. @endsnippet @startsnippet{dotnet} @@ -178,24 +176,22 @@ Due to the restrictions imposed by Composer and Packagist, we cannot supply the Varnish does not have a @Pipeline implementation or the ability to use the cloud-based version of Device Detection. To get started with Varnish device detection On-premise: -1. Clone the GitHub [repository](https://github.com/51degrees/51degrees-varnish). -2. Ensure you have [Git LFS](https://git-lfs.github.com/) installed. The device data files are large binary files that can cause problems if stored in a Git repository directly, so Git LFS is used. -3. Ensure all submodules are checked out by running `git submodule update --init --recursive` in the repository. -4. Follow the [installation instructions](@ref DeviceDetection_OtherIntegrations_Varnish) to get set up with the project. -5. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). -6. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. +1. Clone the GitHub [repository](https://github.com/51degrees/51degrees-varnish) with its submodules by running `git clone --recurse-submodules https://github.com/51Degrees/51degrees-varnish.git`. In a clone you already have, run `git submodule update --init --recursive` instead. +2. Download the free Lite data file, and the free Asn data file that the IP Intelligence tests use, by running `sh cxx/data/get-data-files.sh 51Degrees-LiteV4.1.hash 51Degrees-IPIV4AsnIpiV41.ipi` from the repository root. The script is part of the [data](https://github.com/51Degrees/data) repository, which the `cxx` submodule includes at `cxx/data`. +3. Follow the [installation instructions](@ref DeviceDetection_OtherIntegrations_Varnish) to get set up with the project. +4. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). +5. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. @endsnippet @startsnippet{nginx} Nginx does not have a @Pipeline implementation or the ability to use the cloud-based version of Device Detection. To get started with Nginx device detection On-premise: -1. Clone the GitHub [repository](https://github.com/51degrees/51degrees-nginx). -2. Ensure you have [Git LFS](https://git-lfs.github.com/) installed. The device data files are large binary files that can cause problems if stored in a Git repository directly, so Git LFS is used. -3. Ensure all submodules are checked out by running `git submodule update --init --recursive` in the repository. -4. Follow the [installation instructions](@ref DeviceDetection_OtherIntegrations_Nginx) to get set up with the project. -5. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). -6. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. +1. Clone the GitHub [repository](https://github.com/51degrees/51degrees-nginx) with its submodules by running `git clone --recurse-submodules https://github.com/51Degrees/51degrees-nginx.git`. In a clone you already have, run `git submodule update --init --recursive` instead. +2. Download the free Lite data file by running `sh cxx/data/get-data-files.sh 51Degrees-LiteV4.1.hash` from the repository root. The script is part of the [data](https://github.com/51Degrees/data) repository, which the `cxx` submodule includes at `cxx/data`. +3. Follow the [installation instructions](@ref DeviceDetection_OtherIntegrations_Nginx) to get set up with the project. +4. Follow the linked example here: [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise). +5. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. @endsnippet @startsnippet{go} @@ -203,12 +199,11 @@ Currently, we have a light set of device detection features for Go users to try [device-detection-go](https://github.com/51Degrees/51degrees-go/tree/main/device-detection#readme), [device-detection-examples-go](https://github.com/51Degrees/51degrees-go/tree/main/examples/device-detection#readme). To get started with Go device detection On-premise: -1. Clone the GitHub [repository](https://github.com/51Degrees/51degrees-go). -2. Ensure you have [Git LFS](https://git-lfs.github.com/) installed. The device data files are large binary files that can cause problems if stored in a Git repository directly, so Git LFS is used. -3. Ensure all submodules are checked out by running `git submodule update --init --recursive` in the repository. -4. Follow the [installation instructions](https://github.com/51Degrees/51degrees-go/tree/main/device-detection#build-and-usage) to get set up with the project. -5. Follow the linked example here: [Getting Started](https://github.com/51Degrees/51degrees-go/blob/main/examples/device-detection/dd/getting_started/getting_started.go). -6. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. +1. Clone the GitHub [repository](https://github.com/51Degrees/51degrees-go) with its submodules by running `git clone --recurse-submodules https://github.com/51Degrees/51degrees-go.git`. In a clone you already have, run `git submodule update --init --recursive` instead. +2. Download the free Lite data file by running `sh cxx/data/get-data-files.sh 51Degrees-LiteV4.1.hash` from the repository root, or `./cxx/data/get-data-files.ps1 51Degrees-LiteV4.1.hash` in PowerShell. The scripts are part of the [data](https://github.com/51Degrees/data) repository, which the `cxx` submodule includes at `cxx/data`. +3. Follow the [installation instructions](https://github.com/51Degrees/51degrees-go/tree/main/device-detection#build-and-usage) to get set up with the project. +4. Follow the linked example here: [Getting Started](https://github.com/51Degrees/51degrees-go/blob/main/examples/device-detection/dd/getting_started/getting_started.go). +5. (optional) Obtain a License Key by purchasing a subscription and download a data file with access to more devices and properties, see our [pricing page](https://51degrees.com/pricing) for details. @endsnippet @startsnippet{rust} diff --git a/src/snippets/example-require-datafile.txt b/src/snippets/example-require-datafile.txt index 62bbcf46e7..5461c9b26d 100644 --- a/src/snippets/example-require-datafile.txt +++ b/src/snippets/example-require-datafile.txt @@ -1,13 +1,15 @@ @htmlonly

-This example requires a local data file. The free 'Lite' data file can be acquired by -pulling the git submodules under this repository (run `git submodule update --recursive`) -or from the device-detection-data -GitHub repository. +This example requires a local data file. The free 'Lite' data file can be downloaded with the +scripts in the data GitHub repository, which +this repository includes at cxx/data. Fetch the submodules by running +git submodule update --init --recursive, then run +sh cxx/data/get-data-files.sh 51Degrees-LiteV4.1.hash from the repository root, +which saves the file as cxx/data/device-detection/51Degrees-LiteV4.1.hash.

The Lite data file is only used for illustration, and has limited accuracy and capabilities. Find out about the more capable data files that are available on our -pricing page +pricing page.

@endhtmlonly \ No newline at end of file From b7ab5daba79270e16b1bf500133db41afbe3ba1c Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Wed, 4 Nov 2026 21:46:29 +0000 Subject: [PATCH 04/15] Add PHP to the nightly benchmarks (#291) --- src/productsummaries/nightlybenchmarks.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/productsummaries/nightlybenchmarks.md b/src/productsummaries/nightlybenchmarks.md index ef12d1b1c7..005fa3a208 100644 --- a/src/productsummaries/nightlybenchmarks.md +++ b/src/productsummaries/nightlybenchmarks.md @@ -3,11 +3,12 @@ | API / Product |
Device Detection
|
IP Intelligence
| |---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | C/C++ | ![dd-cxx](https://raw.githubusercontent.com/51Degrees/51degrees-cxx/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | ![ip-cxx](https://raw.githubusercontent.com/51Degrees/51degrees-cxx/gh-images/perf-graph-Ubuntu_x64_Release-LookupsPerSecond-latest.png) | -| .NET | ![dd-dotnet](https://raw.githubusercontent.com/51Degrees/device-detection-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | ![ip-dotnet](https://raw.githubusercontent.com/51Degrees/ip-intelligence-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | +| .NET | ![dd-dotnet](https://raw.githubusercontent.com/51Degrees/51degrees-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | ![ip-dotnet](https://raw.githubusercontent.com/51Degrees/ip-intelligence-dotnet/gh-images/perf-graph-Ubuntu_x64_Release-DetectionsPerSecond-latest.png) | | Java | ![dd-java](https://raw.githubusercontent.com/51Degrees/51degrees-java/gh-images/perf-graph-Ubuntu_Java_17-DeviceDetection_DetectionsPerSecond-latest.png) | ![ip-java](https://raw.githubusercontent.com/51Degrees/51degrees-java/gh-images/perf-graph-Ubuntu_Java_8-IpIntelligence_DetectionsPerSecond-latest.png) | | Go | ![dd-go](https://raw.githubusercontent.com/51Degrees/51degrees-go/gh-images/perf-graph-Ubuntu_Go_1.24-DetectionsPerSecond-latest.png) | ![ip-go](https://raw.githubusercontent.com/51Degrees/51degrees-go/gh-images/perf-graph-Ubuntu_Go_1.24-LookupsPerSecond-latest.png) | | Node.js | ![dd-node](https://raw.githubusercontent.com/51Degrees/51degrees-node/gh-images/perf-graph-Ubuntu_Node_24-DetectionsPerSecond-latest.png) | | | Python | ![dd-python](https://raw.githubusercontent.com/51Degrees/51degrees-python/gh-images/perf-graph-Ubuntu_Python_3.13-DetectionsPerSecond-latest.png) | | +| PHP | ![dd-php](https://raw.githubusercontent.com/51Degrees/51degrees-php/gh-images/perf-graph-Ubuntu_PHP_8.4-DetectionsPerSecond-latest.png) | | | Rust | ![dd-rust](https://raw.githubusercontent.com/51Degrees/51degrees-rust/gh-images/perf-graph-DeviceDetection-OnPremise-DetectionsPerSecond-latest.png) | ![ip-rust](https://raw.githubusercontent.com/51Degrees/51degrees-rust/gh-images/perf-graph-IpIntelligence-OnPremise-LookupsPerSecond-latest.png) | | NGINX | ![dd-nginx](https://raw.githubusercontent.com/51Degrees/51degrees-nginx/gh-images/perf-graph-ubuntu-latest-DetectionsPerSecond-latest.png) | ![ip-nginx](https://raw.githubusercontent.com/51Degrees/51degrees-nginx/gh-images/perf-graph-ubuntu-latest_IPI-DetectionsPerSecond-latest.png) | | Varnish | ![dd-varnish](https://raw.githubusercontent.com/51Degrees/51degrees-varnish/gh-images/perf-graph-ubuntu_DD-DetectionsPerSecond-latest.png) | ![ip-varnish](https://raw.githubusercontent.com/51Degrees/51degrees-varnish/gh-images/perf-graph-ubuntu_IPI-DetectionsPerSecond-latest.png) | From 73b54dba987d05c2e3dd82a2e365957ac5c8bbf9 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Thu, 5 Nov 2026 06:58:24 +0000 Subject: [PATCH 05/15] Say precise, not accurate, where the pages describe how far an IP location can be from the device (#293) Accurate means a location is correct. A location from an IP address can be correct and still only narrow the device down to an area, so the pages say imprecision and precise where they describe that. The property names, such as AccuracyRadiusMin, are unchanged. --- src/ipintelligence/features/confidence.md | 2 +- src/ipintelligence/migration/ipinfo.md | 2 +- src/ipintelligence/overview.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ipintelligence/features/confidence.md b/src/ipintelligence/features/confidence.md index c7f816b7bf..c021a8eff4 100644 --- a/src/ipintelligence/features/confidence.md +++ b/src/ipintelligence/features/confidence.md @@ -14,7 +14,7 @@ Always check the value of `LocationConfidence` when determining how to use IP In - **High** confidence results can be relied upon and considered useful for all practical purposes. -- **Medium** confidence results might be useful where the use case can tolerate a degree of inaccuracy. +- **Medium** confidence results might be useful where the use case can tolerate a degree of imprecision. - **Low** or **Unknown** confidence results should be discarded when the results might be used to make consequential decisions. Instead of using the results consider asking the user to share their location via device APIs such as GPS and then using reverse geocoding, or enter their postal address manually. Subsequent processing may also be similar to handling an exception when obtaining the result. diff --git a/src/ipintelligence/migration/ipinfo.md b/src/ipintelligence/migration/ipinfo.md index 93ba25dd70..09e29f7469 100644 --- a/src/ipintelligence/migration/ipinfo.md +++ b/src/ipintelligence/migration/ipinfo.md @@ -27,7 +27,7 @@ Where a mapping is approximate, the **Notes** column calls it out. Where no equi **Coordinate randomization**: 51Degrees randomizes `Latitude` and `Longitude` within around 1 km of the true average location for the IP range. The randomization is applied during data file generation, so the value returned for a given IP address is stable across all lookups against the same data file and only changes when a new data file is published. This guarantees the coordinates cannot be classified as personal data. No other property is affected. See [Randomization](@ref IpIntelligence_Features_Randomization). -**Location confidence**: 51Degrees rolls up location certainty into a single string-valued `LocationConfidence` property covering the town and country. IPInfo's `radius` field expresses accuracy as a numeric kilometer figure; the closest categorical 51Degrees equivalent is `LocationConfidence`, which complements the numeric `AccuracyRadiusMax` and `AccuracyRadiusMin` properties. See the [property dictionary](https://51degrees.com/developers/property-dictionary) for the set of possible values. +**Location confidence**: 51Degrees rolls up location certainty into a single string-valued `LocationConfidence` property covering the town and country. IPInfo's `radius` field expresses precision as a numeric kilometer figure; the closest categorical 51Degrees equivalent is `LocationConfidence`, which complements the numeric `AccuracyRadiusMax` and `AccuracyRadiusMin` properties. See the [property dictionary](https://51degrees.com/developers/property-dictionary) for the set of possible values. # ASN product diff --git a/src/ipintelligence/overview.md b/src/ipintelligence/overview.md index 216b875fd5..b02cab9698 100644 --- a/src/ipintelligence/overview.md +++ b/src/ipintelligence/overview.md @@ -34,7 +34,7 @@ Data sourced from aggregating real device usage and multiple authoritative datab ### Privacy Protections -Coordinates returned for an IP address are [randomized](@ref IpIntelligence_Features_Randomization) to within 1km of the original point, which keeps them accurate enough for practical applications. +Coordinates returned for an IP address are [randomized](@ref IpIntelligence_Features_Randomization) to within 1km of the original point, which keeps them precise enough for practical applications. ### Accuracy Weighting From 87eab56a45792f940a69c97fc9efecec7ec09f05 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Fri, 6 Nov 2026 13:47:08 +0000 Subject: [PATCH 06/15] Plainer wording, small fixes and sentence case headings (#298) * Plainer wording and small fixes across the documentation 434 changes on 137 pages from a full copy review of the documentation: plain statements in place of marketing phrases, US spelling, consistent names, and small grammar and punctuation fixes. No link target, anchor or code example changes. A few sentences that carried inline code or a link are shortened or removed, for example a note on the false positive control page about a change that is not planned. Accuracy questions and changes that need a decision are not included. * Headings in sentence case 267 headings change to sentence case, as the 51Degrees writing guide asks. Product and feature names keep their capitals, for example Device Detection, IP Intelligence, Reverse Geocoding, Human Confidence and Pipeline API. Documenting.md now asks for sentence case in place of Title Case. Only letter case changes, so anchors and links are unaffected. --- Documenting.md | 2 +- src/devicedetection/cloudtoonpremise.md | 30 ++++----- src/devicedetection/datafileupdates.md | 4 +- .../examples/gettingstartedconsole/cloud.md | 9 +-- .../examples/gettingstartedconsole/index.md | 11 +--- .../gettingstartedconsole/onpremise.md | 13 ++-- .../examples/gettingstartedweb/cloud.md | 6 +- .../examples/gettingstartedweb/index.md | 17 ++--- .../examples/gettingstartedweb/onpremise.md | 6 +- src/devicedetection/examples/index.md | 4 +- .../examples/matchmetrics/index.md | 2 +- .../examples/matchmetrics/onpremisehash.md | 5 +- .../examples/metadata/cloud.md | 4 +- .../examples/metadata/onpremisehash.md | 6 +- .../examples/nativekeylookup/cloud.md | 2 +- .../examples/nativekeylookup/index.md | 2 +- .../examples/offlineprocessing/index.md | 2 +- .../offlineprocessing/onpremisehash.md | 6 +- .../examples/performance/index.md | 3 +- .../examples/performance/onpremisehash.md | 4 +- .../examples/taclookup/cloud.md | 2 +- .../examples/taclookup/index.md | 2 +- .../features/appledetection.md | 21 +++---- .../features/concurrentprocessing.md | 11 ++-- src/devicedetection/features/crawlers.md | 6 +- src/devicedetection/features/csvdatafile.md | 10 +-- .../features/falsepositivecontrol.md | 19 +++--- src/devicedetection/features/index.md | 2 +- .../features/nativekeylookup.md | 6 +- .../features/performanceoptions.md | 19 +++--- src/devicedetection/features/robotstxt.md | 34 +++++----- src/devicedetection/features/taclookup.md | 8 +-- .../features/thirdpartycookies.md | 18 +++--- .../features/useragentclienthints/headers.md | 23 +++---- .../useragentclienthints/javascript.md | 16 ++--- .../features/useragentclienthints/overview.md | 14 ++--- .../requiredUachHeaders.md | 9 ++- .../features/useragentclienthints/sua.md | 12 ++-- src/devicedetection/hash.md | 22 ++++--- .../migrationguides/deviceatlas.md | 26 ++++---- src/devicedetection/migrationguides/index.md | 2 +- src/devicedetection/migrationguides/wurfl.md | 42 ++++++------- .../otherintegrations/index.md | 2 +- .../otherintegrations/nginx.md | 20 +++--- .../otherintegrations/openrtbmappings.md | 8 +-- .../otherintegrations/prebid.md | 6 +- .../otherintegrations/uaparser.md | 15 ++--- .../otherintegrations/varnish.md | 12 ++-- .../otherintegrations/wordpress.md | 12 ++-- src/devicedetection/overview.md | 62 +++++++++--------- src/devicedetection/quickstart.md | 40 ++++++------ src/devicedetection/upgradingtoV4.md | 36 +++++------ src/devicedetection/whatsnewv45.md | 14 ++--- src/humanconfidence/googleanalytics.md | 4 +- src/humanconfidence/overview.md | 2 +- src/humanconfidence/quickstart.md | 8 +-- src/identifiers/fodid.md | 4 +- src/identifiers/overview.md | 2 +- src/identifiers/pmp/cmp-wiring.md | 2 +- src/identifiers/pmp/configuration.md | 8 +-- src/identifiers/pmp/integration.md | 2 +- src/integrations/googleanalytics.md | 2 +- src/integrations/openrtbmappings.md | 14 ++--- src/integrations/prebid.md | 22 +++---- src/ipintelligence/algorithm.md | 18 +++--- src/ipintelligence/combined/console/index.md | 2 +- .../combined/console/onpremise.md | 2 +- src/ipintelligence/combined/index.md | 2 +- src/ipintelligence/combined/web/index.md | 2 +- src/ipintelligence/combined/web/onpremise.md | 2 +- .../examples/datafileupdates.md | 2 +- .../examples/gettingstartedconsole/cloud.md | 2 +- .../examples/gettingstartedconsole/index.md | 12 +--- .../gettingstartedconsole/onpremise.md | 9 +-- .../examples/gettingstartedweb/cloud.md | 2 +- .../examples/gettingstartedweb/index.md | 19 ++---- .../examples/gettingstartedweb/onpremise.md | 6 +- src/ipintelligence/examples/index.md | 2 +- src/ipintelligence/examples/metadata.md | 2 +- .../examples/offlineprocessing.md | 2 +- src/ipintelligence/examples/performance.md | 2 +- src/ipintelligence/features/area.md | 10 +-- src/ipintelligence/features/confidence.md | 4 +- src/ipintelligence/features/diversity.md | 6 +- src/ipintelligence/features/index.md | 2 +- src/ipintelligence/features/randomization.md | 2 +- src/ipintelligence/features/weighting.md | 2 +- src/ipintelligence/migration/index.md | 4 +- src/ipintelligence/migration/ipinfo.md | 4 +- src/ipintelligence/migration/maxmind.md | 2 +- src/ipintelligence/overview.md | 40 ++++++------ src/ipintelligence/quickstart.md | 34 +++++----- src/main.md | 58 ++++++++--------- .../builders/buildingfromconfiguration.md | 22 +++---- .../configuration/builders/elementbuilder.md | 4 +- .../configuration/builders/pipelinebuilder.md | 4 +- src/pipelineapi/concepts/data/aspectdata.md | 5 +- src/pipelineapi/concepts/data/datakey.md | 6 +- src/pipelineapi/concepts/data/elementdata.md | 5 +- .../concepts/data/elementdatakey.md | 5 +- src/pipelineapi/concepts/data/evidence.md | 4 +- .../concepts/data/evidencekeyfilter.md | 7 +-- src/pipelineapi/concepts/data/flowdata.md | 12 ++-- src/pipelineapi/concepts/data/index.md | 2 +- .../concepts/flowelements/aspectengine.md | 8 +-- .../concepts/flowelements/cloudengine.md | 8 +-- .../concepts/flowelements/fiftyoneengine.md | 9 +-- .../concepts/flowelements/flowelement.md | 11 ++-- .../concepts/flowelements/index.md | 2 +- .../concepts/flowelements/onpremiseengine.md | 2 +- .../concepts/metadata/aspectproperties.md | 4 +- .../concepts/metadata/elementproperties.md | 2 +- src/pipelineapi/concepts/metadata/index.md | 2 +- src/pipelineapi/concepts/pipeline.md | 9 +-- src/pipelineapi/concepts/pipeline_basics.md | 9 ++- src/pipelineapi/concepts/terminology.md | 2 +- .../customelement/clientsideevidence.md | 12 ++-- .../examples/customelement/cloud.md | 6 +- .../examples/customelement/flowelement.md | 15 ++--- .../examples/customelement/onpremise.md | 13 ++-- src/pipelineapi/examples/index.md | 2 +- src/pipelineapi/examples/usagesharing.md | 2 +- src/pipelineapi/examples/webintegration.md | 5 +- src/pipelineapi/features/agentsignature.md | 28 ++------- .../features/asynchronousexecution.md | 12 +--- .../features/automaticdatafileupdates.md | 10 ++- .../features/clientsideevidence.md | 63 +++++++++---------- src/pipelineapi/features/customelements.md | 7 +-- src/pipelineapi/features/errorhandling.md | 12 ++-- src/pipelineapi/features/flexibleaccessors.md | 12 ++-- src/pipelineapi/features/index.md | 2 +- src/pipelineapi/features/lazyloading.md | 11 ++-- src/pipelineapi/features/logging.md | 12 ++-- src/pipelineapi/features/parallelexecution.md | 6 +- src/pipelineapi/features/resultcaching.md | 8 +-- src/pipelineapi/features/usagesharing.md | 8 +-- src/pipelineapi/features/webintegration.md | 7 +-- src/productsummaries/benchmarks.md | 3 +- src/productsummaries/featurematrix.md | 6 +- src/productsummaries/hardwarebenchmarks.md | 2 +- src/productsummaries/index.md | 2 +- src/productsummaries/nightlybenchmarks.md | 7 +-- src/productsummaries/openrtbmappings.md | 8 +-- src/productsummaries/testedversions.md | 13 ++-- .../examples/combiningservices.md | 2 +- .../configurefromfile/51degreescloud.md | 4 +- .../examples/gettingstarted/51degreescloud.md | 5 +- src/reversegeocoding/examples/index.md | 2 +- .../examples/webintegration/examples.md | 2 +- src/reversegeocoding/overview.md | 24 +++---- src/reversegeocoding/quickstart.md | 22 +++---- src/services/cloud/errormessages.md | 12 ++-- src/services/cloud/overview.md | 4 +- src/services/cloud/resourcekeys.md | 8 +-- src/services/cloud/selfhosteddocker.md | 8 +-- src/services/configurator.md | 10 +-- src/services/distributor.md | 9 +-- ...mple-automatic-updates-on-startup-hash.txt | 4 +- ...utomatic-updates-polling-interval-hash.txt | 4 +- ...-automatic-updates-system-watcher-hash.txt | 4 +- .../example-failure-to-match-cloud.txt | 6 +- .../example-failure-to-match-hash.txt | 6 +- src/snippets/example-match-metrics-hash.txt | 2 +- src/snippets/example-metadata-cloud.txt | 7 +-- src/snippets/example-metadata-hash.txt | 7 +-- .../example-native-model-lookup-cloud.txt | 5 +- src/snippets/example-performance-hash.txt | 8 +-- src/snippets/example-tac-lookup-cloud.txt | 3 +- src/snippets/example-usage-sharing-intro.txt | 5 +- .../example-user-agent-client-hints.txt | 4 +- .../example-web-integration-client-hints.txt | 6 +- .../example-web-integration-location.txt | 5 +- src/snippets/example-web-integration.txt | 4 +- 173 files changed, 716 insertions(+), 929 deletions(-) diff --git a/Documenting.md b/Documenting.md index b70189b631..a8c06bf3d8 100644 --- a/Documenting.md +++ b/Documenting.md @@ -301,7 +301,7 @@ This contains the structure of the navigation. First there is the main page (def # General Standardization -All headings should be written in Title Case. e.g. 'Last of the Mohican's' +All headings should be written in sentence case, with capitals only for the first word, product names such as Device Detection and IP Intelligence, and other names. e.g. 'How the cloud service works' Use single quotation when enclosing text. diff --git a/src/devicedetection/cloudtoonpremise.md b/src/devicedetection/cloudtoonpremise.md index cead48cbef..5679d52943 100644 --- a/src/devicedetection/cloudtoonpremise.md +++ b/src/devicedetection/cloudtoonpremise.md @@ -1,10 +1,10 @@ -@page DeviceDetection_CloudToOnPremise Migrating from Cloud to On-premise +@page DeviceDetection_CloudToOnPremise Migrating from cloud to on-premise -# Migrating from Cloud to On-premise Device Detection +# Migrating from cloud to on-premise Device Detection This guide walks you through migrating from 51Degrees Cloud Device Detection to On-premise deployment. You'll learn when to migrate, how to update your configuration, and what changes to expect. -## When to Consider On-premise +## When to consider on-premise On-premise deployment works better when you need: @@ -14,7 +14,7 @@ On-premise deployment works better when you need: - **Offline capability** - No internet connection required - **Predictable costs** - Fixed licensing instead of per-request pricing -## Migration Steps Overview +## Migration steps 1. Get an On-premise license and data file 2. Update package dependencies (if needed) @@ -23,7 +23,7 @@ On-premise deployment works better when you need: 5. Set up data file updates 6. Test and optimize performance -## Step 1: Get License and Data File +## Step 1: Get a license and data file **For testing:** - Download the free Lite data file with the scripts in the [data](https://github.com/51Degrees/data) repository on GitHub @@ -34,7 +34,7 @@ On-premise deployment works better when you need: - Includes full data file with all device properties - Automatic data file updates included -## Step 2: Update Dependencies +## Step 2: Update dependencies Most 51Degrees packages already include both Cloud and On-premise capabilities. You typically only need configuration changes. @@ -68,7 +68,7 @@ npm install fiftyone.devicedetection - **PHP**: [device-detection-php-onpremise](https://github.com/51Degrees/51degrees-php/tree/main/device-detection/onpremise) - **Python**: `pip install fiftyone-devicedetection-onpremise` -## Step 3: Update Configuration +## Step 3: Update configuration Replace your Cloud configuration with file-based settings. @@ -106,7 +106,7 @@ Replace your Cloud configuration with file-based settings. } ``` -## Step 4: Update Code +## Step 4: Update code The Pipeline API keeps most code unchanged. Main differences: @@ -142,7 +142,7 @@ For complete examples: - [On-premise Console Examples](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise) - [On-premise Web Examples](@ref DeviceDetection_Examples_GettingStarted_Web_OnPremise) -## Step 5: Set Up Data File Updates +## Step 5: Set up data file updates On-premise deployments need regular data file updates to detect new devices. @@ -157,7 +157,7 @@ Configure the pipeline to handle updates. See the [Data File Updates examples](@ Download new data files from the [51Degrees Distributor](@ref Services_Distributor) using your License Key. -## Step 6: Optimize Performance +## Step 6: Optimize performance **Choose Performance Profile** @@ -174,14 +174,14 @@ Download new data files from the [51Degrees Distributor](@ref Services_Distribut See [Performance Examples](@ref DeviceDetection_Examples_Performance_OnPremiseHash) for benchmarking. -## Testing Your Migration +## Testing your migration 1. **Compare Results** - Verify detection matches Cloud results for test cases 2. **Load Testing** - Confirm performance under expected traffic 3. **Update Testing** - Ensure data file updates work without disruption 4. **Failover Testing** - Test what happens if data file becomes unavailable -## Common Migration Patterns +## Common migration patterns **Web Applications** - Use [web integration examples](@ref DeviceDetection_Examples_GettingStarted_Web_OnPremise) @@ -198,7 +198,7 @@ See [Performance Examples](@ref DeviceDetection_Examples_Performance_OnPremiseHa - Share data file via volume mount - Use environment variables for configuration -## Planning Your Rollback +## Planning your rollback Keep Cloud access during migration: @@ -229,14 +229,14 @@ Keep Cloud access during migration: - Consider out-of-process deployment - Monitor memory usage patterns -## Next Steps +## Next steps 1. Review [On-premise examples](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise) 2. Set up [automatic data file updates](@ref DeviceDetection_DataFileUpdates) 3. Enable [client-side evidence](@ref PipelineApi_Features_ClientSideEvidence) for better accuracy 4. Monitor [match metrics](@ref DeviceDetection_Examples_MatchMetrics_OnPremiseHash) for quality -## 💬 Get Help +## 💬 Get help - Enterprise support: [support@51degrees.com](mailto:support@51degrees.com) - Technical documentation: [On-premise Guide](@ref DeviceDetection_Quickstart) diff --git a/src/devicedetection/datafileupdates.md b/src/devicedetection/datafileupdates.md index 35e1a5cc2f..1070fb5ecb 100644 --- a/src/devicedetection/datafileupdates.md +++ b/src/devicedetection/datafileupdates.md @@ -1,8 +1,8 @@ -@page DeviceDetection_DataFileUpdates Data File Updates +@page DeviceDetection_DataFileUpdates Data file updates # Introduction -New device detection data files are released daily by 51Degrees. This page demonstrates various methods to update device detection data files, including automatic and manual approaches. +We release new device detection data files daily. These examples show how to update data files automatically or manually. For more information on data file updates in general, see the [automatic data file updates](@ref PipelineApi_Features_AutomaticDatafileUpdates) documentation. diff --git a/src/devicedetection/examples/gettingstartedconsole/cloud.md b/src/devicedetection/examples/gettingstartedconsole/cloud.md index 7b5d99e680..70dad9534c 100644 --- a/src/devicedetection/examples/gettingstartedconsole/cloud.md +++ b/src/devicedetection/examples/gettingstartedconsole/cloud.md @@ -1,13 +1,10 @@ -@page DeviceDetection_Examples_GettingStarted_Console_Cloud Getting Started Console Cloud +@page DeviceDetection_Examples_GettingStarted_Console_Cloud Getting started with cloud detection in a console application # Introduction -This example shows how to get set up an cloud based Device Detection @aspectengine and use it -to process User-Agents and/or User-Agent Client Hints. +This example shows how to set up a cloud Device Detection @aspectengine to process User-Agents, User-Agent Client Hints, or both. -There are many different ways to use the pipeline. Rather that creating examples for every scenario, -we have used the following table where possible when creating the 'getting started' examples. -You can mix and match elements from different examples in order to match your use case. +The table shows how each example configures the pipeline. You can combine elements from different examples to suit your application. | | Console | Web | |------------|---------------------|---------------------| diff --git a/src/devicedetection/examples/gettingstartedconsole/index.md b/src/devicedetection/examples/gettingstartedconsole/index.md index c7f9b6d187..a44bd8b26e 100644 --- a/src/devicedetection/examples/gettingstartedconsole/index.md +++ b/src/devicedetection/examples/gettingstartedconsole/index.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Examples_GettingStarted_Console_Index Getting Started - Console +@page DeviceDetection_Examples_GettingStarted_Console_Index Getting started with console applications # Introduction @@ -12,14 +12,9 @@ pipeline into a larger application. Two deployment models are covered: -- **Cloud** — calls 51Degrees' hosted Cloud service over HTTPS. The simplest - path to a working detection: a Resource Key configures the pipeline, no data - file is needed locally. See @ref DeviceDetection_Examples_GettingStarted_Console_Cloud. +- **Cloud** calls our hosted service over HTTPS. Configure the pipeline with a Resource Key. You do not need a local data file. See @ref DeviceDetection_Examples_GettingStarted_Console_Cloud. -- **On-premise** — runs the Hash engine inside your own process against a - locally distributed data file. Suitable when network access is restricted or - when you need the lowest per-call latency. See - @ref DeviceDetection_Examples_GettingStarted_Console_OnPremise. +- **On-premise** runs the Hash engine in your process with a local data file. Use it when network access is restricted or per-call latency is a priority. See @ref DeviceDetection_Examples_GettingStarted_Console_OnPremise. Both examples are available across every supported language with a matching pattern, so the same logic can be compared side by side. If you intend to diff --git a/src/devicedetection/examples/gettingstartedconsole/onpremise.md b/src/devicedetection/examples/gettingstartedconsole/onpremise.md index 5bdfe32636..57532798de 100644 --- a/src/devicedetection/examples/gettingstartedconsole/onpremise.md +++ b/src/devicedetection/examples/gettingstartedconsole/onpremise.md @@ -1,13 +1,10 @@ -@page DeviceDetection_Examples_GettingStarted_Console_OnPremise Getting Started Console On-premise +@page DeviceDetection_Examples_GettingStarted_Console_OnPremise Getting started with on-premise detection in a console application # Introduction -This example shows how to get set up an On-premise Device Detection @aspectengine and use it -to process User-Agents and/or User-Agent Client Hints. +This example shows how to set up an on-premise Device Detection @aspectengine to process User-Agents, User-Agent Client Hints, or both. -There are many different ways to use the pipeline. Rather that creating examples for every scenario, -we have used the following table where possible when creating the 'getting started' examples. -You can mix and match elements from different examples in order to match your use case. +The table shows how each example configures the pipeline. You can combine elements from different examples to suit your application. | | Console | Web | |------------|---------------------|---------------------| @@ -33,9 +30,9 @@ This example is available in full on [GitHub](https://github.com/51Degrees/51deg @include{doc} example-require-datafile.txt -The path to the data needs to be updated before running the example. +Update the data file path before running the example. -In a Linux environment, the following commands: +In a Linux environment, run the following commands: ```bash $ curl localhost:8080 -I -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36" diff --git a/src/devicedetection/examples/gettingstartedweb/cloud.md b/src/devicedetection/examples/gettingstartedweb/cloud.md index 470a619668..ce885f9f5b 100644 --- a/src/devicedetection/examples/gettingstartedweb/cloud.md +++ b/src/devicedetection/examples/gettingstartedweb/cloud.md @@ -1,13 +1,11 @@ -@page DeviceDetection_Examples_GettingStarted_Web_Cloud Getting Started Web Cloud +@page DeviceDetection_Examples_GettingStarted_Web_Cloud Getting started with cloud detection in a web application # Introduction This example shows how to integrate a Pipeline running a cloud based @devicedetection engine into a simple web page. -There are many different ways to use the pipeline. Rather than creating examples for every scenario, -we have used the following table where possible when creating the 'getting started' examples. -You can mix and match elements from different examples in order to match your use case. +The table shows how each example configures the pipeline. You can combine elements from different examples to suit your application. | | Console | Web | |------------|---------------------|---------------------| diff --git a/src/devicedetection/examples/gettingstartedweb/index.md b/src/devicedetection/examples/gettingstartedweb/index.md index 9691b550e6..f30d02001a 100644 --- a/src/devicedetection/examples/gettingstartedweb/index.md +++ b/src/devicedetection/examples/gettingstartedweb/index.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Examples_GettingStarted_Web_Index Getting Started - Web +@page DeviceDetection_Examples_GettingStarted_Web_Index Getting started with web applications # Introduction @@ -10,20 +10,11 @@ properties to your handler so you can adapt the response. Two deployment models are covered: -- **Cloud** — calls 51Degrees' hosted Cloud service over HTTPS. No data file - to manage, no on-premise binary to update; suitable for traffic that already - reaches a public endpoint and for teams who want the fastest path to a - working integration. See @ref DeviceDetection_Examples_GettingStarted_Web_Cloud. +- **Cloud** calls our hosted service over HTTPS. You do not need to manage a local data file or detection binary. See @ref DeviceDetection_Examples_GettingStarted_Web_Cloud. -- **On-premise** — runs the Hash engine inside your own process against a - locally distributed data file. Suitable for workloads that need offline - operation, predictable latency, or the highest request throughput. See - @ref DeviceDetection_Examples_GettingStarted_Web_OnPremise. +- **On-premise** runs the Hash engine in your process with a local data file. Use it for offline operation or when latency and throughput are priorities. See @ref DeviceDetection_Examples_GettingStarted_Web_OnPremise. -Both examples follow the same pattern: configure a pipeline, register it with -the framework, and read the detected properties off the request. Each ships -side-by-side snippets across every supported language and web framework, so -you can pick the one that matches your stack and skip the rest. If you are +For both examples, configure a pipeline, register it with your web framework, and read the detected properties from each request. Select a tab for your language and framework. If you are evaluating which deployment model fits your use case first, see @ref DeviceDetection_CloudToOnPremise for a comparison. diff --git a/src/devicedetection/examples/gettingstartedweb/onpremise.md b/src/devicedetection/examples/gettingstartedweb/onpremise.md index a45522decc..a511f24ca0 100644 --- a/src/devicedetection/examples/gettingstartedweb/onpremise.md +++ b/src/devicedetection/examples/gettingstartedweb/onpremise.md @@ -1,13 +1,11 @@ -@page DeviceDetection_Examples_GettingStarted_Web_OnPremise Getting Started Web On-premise +@page DeviceDetection_Examples_GettingStarted_Web_OnPremise Getting started with on-premise detection in a web application # Introduction This example shows how to integrate a Pipeline running an On-premise @devicedetection engine into a simple web page. -There are many different ways to use the pipeline. Rather that creating examples for every scenario, -we have used the following table where possible when creating the 'getting started' examples. -You can mix and match elements from different examples in order to match your use case. +The table shows how each example configures the pipeline. You can combine elements from different examples to suit your application. | | Console | Web | |------------|---------------------|---------------------| diff --git a/src/devicedetection/examples/index.md b/src/devicedetection/examples/index.md index 05cfe2477e..b0d3593478 100644 --- a/src/devicedetection/examples/index.md +++ b/src/devicedetection/examples/index.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Examples_Index Device Detection Examples +@page DeviceDetection_Examples_Index Device Detection examples @subpage DeviceDetection_Examples_GettingStarted_Console_Index @@ -18,6 +18,6 @@ @subpage DeviceDetection_Examples_TacLookup_Index -## Combined Services +## Combined services For examples that combine Device Detection with IP Intelligence, see @ref IpIntelligence_Combined_Index diff --git a/src/devicedetection/examples/matchmetrics/index.md b/src/devicedetection/examples/matchmetrics/index.md index 438ab12f58..2327f9a78e 100644 --- a/src/devicedetection/examples/matchmetrics/index.md +++ b/src/devicedetection/examples/matchmetrics/index.md @@ -1,3 +1,3 @@ -@page DeviceDetection_Examples_MatchMetrics_Index Match Metrics +@page DeviceDetection_Examples_MatchMetrics_Index Match metrics @subpage DeviceDetection_Examples_MatchMetrics_OnPremiseHash diff --git a/src/devicedetection/examples/matchmetrics/onpremisehash.md b/src/devicedetection/examples/matchmetrics/onpremisehash.md index cab8ff6b83..d5573c74a3 100644 --- a/src/devicedetection/examples/matchmetrics/onpremisehash.md +++ b/src/devicedetection/examples/matchmetrics/onpremisehash.md @@ -1,9 +1,8 @@ -@page DeviceDetection_Examples_MatchMetrics_OnPremiseHash Match Metrics On-premise Hash +@page DeviceDetection_Examples_MatchMetrics_OnPremiseHash On-premise Hash match metrics # Introduction -This example shows how to view metrics associated with the results of processing with a Device Detection -@aspectengine using the Hash algorithm. +This example shows how to read match metrics from a Device Detection @aspectengine that uses the Hash algorithm. @startsnippets @grabexample{device-detection-cxx,_hash_2_match_metrics_8c,C} diff --git a/src/devicedetection/examples/metadata/cloud.md b/src/devicedetection/examples/metadata/cloud.md index c518ee3320..fc12689b75 100644 --- a/src/devicedetection/examples/metadata/cloud.md +++ b/src/devicedetection/examples/metadata/cloud.md @@ -1,8 +1,8 @@ -@page DeviceDetection_Examples_Metadata_Cloud Metadata Cloud +@page DeviceDetection_Examples_Metadata_Cloud Cloud metadata # Introduction -This example shows how to interrogate the metadata returned by the 51Degrees Cloud service. +This example shows how to read metadata returned by the 51Degrees Cloud service. @startsnippets @grabexample{device-detection-dotnet,_cloud_2_metadata-_console_2_program_8cs,C#} diff --git a/src/devicedetection/examples/metadata/onpremisehash.md b/src/devicedetection/examples/metadata/onpremisehash.md index b56d27955b..335c3628ab 100644 --- a/src/devicedetection/examples/metadata/onpremisehash.md +++ b/src/devicedetection/examples/metadata/onpremisehash.md @@ -1,8 +1,8 @@ -@page DeviceDetection_Examples_Metadata_OnPremiseHash Metadata On-premise Hash +@page DeviceDetection_Examples_Metadata_OnPremiseHash On-premise Hash metadata # Introduction -This example shows how to interrogate the metadata associated with the contents of a Device Detection @datafile. +This example shows how to read metadata about a Device Detection @datafile. @startsnippets @showsnippet{c,C} @@ -14,7 +14,7 @@ This example shows how to interrogate the metadata associated with the contents @grabexample{device-detection-python,onpremise_2metadata_console_8py,Python} @grabexample{rust,dd-onprem-metadata,Rust} @startsnippet{c} -Metadata is only available in C++ wrapper layer to provide a convenient way for higher level languages to access additional data to internal components of the Device Detection engine. C developer can access these information directly without a need for additional MetaData entities. +The C++ wrapper exposes metadata so that higher-level languages can access internal Device Detection data. In C, you can access this information directly without additional metadata objects. @endsnippet @grabbedexample @endsnippets diff --git a/src/devicedetection/examples/nativekeylookup/cloud.md b/src/devicedetection/examples/nativekeylookup/cloud.md index 63f044e65a..7b4a1b6d85 100644 --- a/src/devicedetection/examples/nativekeylookup/cloud.md +++ b/src/devicedetection/examples/nativekeylookup/cloud.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Examples_NativeKeyLookup_Cloud Cloud Native Key Lookup +@page DeviceDetection_Examples_NativeKeyLookup_Cloud Cloud native key lookup # Introduction diff --git a/src/devicedetection/examples/nativekeylookup/index.md b/src/devicedetection/examples/nativekeylookup/index.md index a6c39cb754..a1447e59b4 100644 --- a/src/devicedetection/examples/nativekeylookup/index.md +++ b/src/devicedetection/examples/nativekeylookup/index.md @@ -1,3 +1,3 @@ -@page DeviceDetection_Examples_NativeKeyLookup_Index Native Key Lookup +@page DeviceDetection_Examples_NativeKeyLookup_Index Native key lookup @subpage DeviceDetection_Examples_NativeKeyLookup_Cloud diff --git a/src/devicedetection/examples/offlineprocessing/index.md b/src/devicedetection/examples/offlineprocessing/index.md index dce175fc12..7fdbcd6b00 100644 --- a/src/devicedetection/examples/offlineprocessing/index.md +++ b/src/devicedetection/examples/offlineprocessing/index.md @@ -1,3 +1,3 @@ -@page DeviceDetection_Examples_OfflineProcessing_Index Offline Processing +@page DeviceDetection_Examples_OfflineProcessing_Index Offline processing @subpage DeviceDetection_Examples_OfflineProcessing_OnPremiseHash diff --git a/src/devicedetection/examples/offlineprocessing/onpremisehash.md b/src/devicedetection/examples/offlineprocessing/onpremisehash.md index ddcf972d63..a22547706a 100644 --- a/src/devicedetection/examples/offlineprocessing/onpremisehash.md +++ b/src/devicedetection/examples/offlineprocessing/onpremisehash.md @@ -1,8 +1,8 @@ -@page DeviceDetection_Examples_OfflineProcessing_OnPremiseHash Offline Processing On-premise Hash +@page DeviceDetection_Examples_OfflineProcessing_OnPremiseHash On-premise Hash offline processing # Introduction -This example shows how process data for later viewing using a Device Detection Hash @datafile. +This example shows how to process data for later viewing using a Device Detection Hash @datafile. @startsnippets @grabexample{device-detection-cxx,_hash_2_offline_processing_8c,C} @@ -17,7 +17,7 @@ This example shows how process data for later viewing using a Device Detection H There is no offline (or batch) processing example for C++, see the C tab instead. @endsnippet @startsnippet{php} -PHP designed specifically to service web requests. So, for this reason, an offline (or batch) processing example has been omitted. Processing data from a file is possible using the PHP API. However, the use of another language is advised. +The PHP API can process data from a file, but we recommend another language for offline or batch processing. No PHP example is provided here. @endsnippet @grabbedexample @endsnippets diff --git a/src/devicedetection/examples/performance/index.md b/src/devicedetection/examples/performance/index.md index 9636c2f7c9..e49f31c967 100644 --- a/src/devicedetection/examples/performance/index.md +++ b/src/devicedetection/examples/performance/index.md @@ -15,8 +15,7 @@ the configuration knobs that drive throughput and memory: the how the data file is loaded, and the size of the property and value caches. Pick a profile, run the example, and use the numbers to decide whether to trade memory for throughput on your target hosts. The example covers the -On-premise Hash engine — Cloud performance is dominated by network round-trip -and is not benchmarked here. +on-premise Hash engine. Cloud performance depends on network round-trip time and is not benchmarked here. The example ships across every supported language with a matching pattern, so the same workload can be measured across runtimes. diff --git a/src/devicedetection/examples/performance/onpremisehash.md b/src/devicedetection/examples/performance/onpremisehash.md index c206ebbcda..84334cd731 100644 --- a/src/devicedetection/examples/performance/onpremisehash.md +++ b/src/devicedetection/examples/performance/onpremisehash.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Examples_Performance_OnPremiseHash Performance Test On-premise Hash +@page DeviceDetection_Examples_Performance_OnPremiseHash On-premise Hash performance test # Introduction @@ -20,6 +20,6 @@ A [feature page](@ref DeviceDetection_Features_PerformanceOptions) is also avail There is no performance example for C++, see the C tab instead. @endsnippet @startsnippet{php} -The PHP device-detection On-premise repository includes a modified version of ApacheBench along with benchmarking script tool. Details of how to run this can be found in the [GitHub Readme](https://github.com/51Degrees/51degrees-php/tree/main/device-detection/onpremise#performance) +The PHP on-premise device detection repository includes a modified ApacheBench and a benchmarking script. See the [GitHub Readme](https://github.com/51Degrees/51degrees-php/tree/main/device-detection/onpremise#performance) for instructions. @endsnippet @endsnippets diff --git a/src/devicedetection/examples/taclookup/cloud.md b/src/devicedetection/examples/taclookup/cloud.md index 8c1e196f57..641ad2ac8e 100644 --- a/src/devicedetection/examples/taclookup/cloud.md +++ b/src/devicedetection/examples/taclookup/cloud.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Examples_TacLookup_Cloud TAC Cloud Lookup +@page DeviceDetection_Examples_TacLookup_Cloud Cloud TAC lookup # Introduction diff --git a/src/devicedetection/examples/taclookup/index.md b/src/devicedetection/examples/taclookup/index.md index 97e4e3d311..1a8fb83ab2 100644 --- a/src/devicedetection/examples/taclookup/index.md +++ b/src/devicedetection/examples/taclookup/index.md @@ -1,3 +1,3 @@ -@page DeviceDetection_Examples_TacLookup_Index TAC Lookup +@page DeviceDetection_Examples_TacLookup_Index TAC lookup @subpage DeviceDetection_Examples_TacLookup_Cloud diff --git a/src/devicedetection/features/appledetection.md b/src/devicedetection/features/appledetection.md index e6bd563418..95d0cd3056 100644 --- a/src/devicedetection/features/appledetection.md +++ b/src/devicedetection/features/appledetection.md @@ -1,6 +1,6 @@ -@page DeviceDetection_Features_AppleDetection Apple Model Detection +@page DeviceDetection_Features_AppleDetection Apple model detection -# Apple Model Detection +# Apple model detection Apple devices are unique in that their User-Agent strings do not include hardware model identifiers - unlike most Android devices. @@ -8,8 +8,7 @@ This means it's not possible to identify the exact iPhone/iPad model using only To solve this, 51Degrees uses **client-side JavaScript** to gather additional evidence from the device, such as screen resolution and GPU model. -This allows us to identify the precise Apple hardware model - including the specific iPhone/iPad generation. -Even when the User-Agent string is generic. +This evidence can identify a model or narrow the result to a group of models, even when the User-Agent string is generic. This feature is built into the [client-side evidence](@ref PipelineApi_Features_ClientSideEvidence) functionality, and is automatically enabled when the relevant property is included in your Resource Key. @@ -25,7 +24,7 @@ When a request from an Apple device is received: 2. Based on this, the server sends JavaScript to the client that gathers device-specific information. 3. The JavaScript runs on the client and returns a **hardware profile ID**. 4. This ID is sent back to the server. -5. The server updates the detection result with the exact Apple model. +5. The server updates the detection result with the detected Apple model or group of models. This works even in edge cases such as: @@ -60,18 +59,18 @@ the generic Apple group profile with a more accurate one. - [Web Integration Example](@ref DeviceDetection_Examples_GettingStarted_Web_Index): See how to implement it with code samples - [51Degrees Blog - Apple](https://51degrees.com/resources/blogs/tag/Apple): Technical deep dives, case studies, and news we've produced relating to Apple -## Detection Results for Apple Devices {#detection-results} +## Detection results for Apple devices {#detection-results} Apple has continually worked to homogenize any information that a website can get about a device, through JavaScript or any other means. For more information, take a look at our [Upgrade Apple Device](https://51degrees.com/blog/upgrade-apple-device-detection) blog. Below we cover the detection results that are experienced for each iPhone, starting from the iPhone 3GS, when using Safari. -The 'percentage' column refers to the percentage of the data submissions we have received that would return that detection result for that particular display mode. For example, '100.00%' in Standard mode indicates that 100% of our submissions for that device would receive that result if the data from the submission were passed to our detection script. '1.50%' in indicates that 1.5% of our submissions would receive that detection result. +The 'percentage' column shows the share of data submissions that would return each detection result for the given display mode. For example, '100.00%' in Standard mode means all submissions for that device would return that result when passed to our detection script. '1.50%' means 1.5% of submissions would return that result. As we receive more data on Apple devices, this table will change. We will update this table following each update to the JavaScript. The tables currently match the released JavaScript created on 22 September 2026. -For optimized viewing of the table, it is recommended you zoom out within your browser. +Zoom out in your browser to see more of the table. -### iPhones using browser in Mobile mode and in standard display mode {#iphones_mobile_standard_mode} +### iPhones in mobile browser mode and standard display mode {#iphones_mobile_standard_mode} |Device|Results|Percentage| |---|---|---| |iPhone 18 Pro Max|iPhone 16 Pro Max, iPhone 17 Pro Max, iPhone 18 Pro Max|100.00%| @@ -127,7 +126,7 @@ For optimized viewing of the table, it is recommended you zoom out within your b |iPhone 4|iPhone 4|100.00%| |iPhone 3GS|iPhone 3GS|100.00%| -### iPhones using browser in Mobile mode and in zoomed display mode {#iphones_mobile_zoom_mode} +### iPhones in mobile browser mode and zoomed display mode {#iphones_mobile_zoom_mode} This table is for display zoom, an iPhone accessibility feature. It is not the normal zoom operation in browsers. It is enabled in Settings > Display & Brightness > Display Zoom > Zoomed. |Device|Results|Percentage| @@ -178,7 +177,7 @@ This table is for display zoom, an iPhone accessibility feature. It is not the n |iPhone 6 Plus|iPhone 6 Plus|100.00%| |iPhone 6|iPhone 6|100.00%| -### iPhones using browser in Desktop mode {#iphones_desktop_mode} +### iPhones in desktop browser mode {#iphones_desktop_mode} |Device|Display Mode|Results|Percentage| |---|---|---|---| |iPhone 18 Pro Max|Standard|iPhone 16 Pro Max, iPhone 17 Pro Max, iPhone 18 Pro Max|100.00%| diff --git a/src/devicedetection/features/concurrentprocessing.md b/src/devicedetection/features/concurrentprocessing.md index 868ed6cd12..a6ee2f066a 100644 --- a/src/devicedetection/features/concurrentprocessing.md +++ b/src/devicedetection/features/concurrentprocessing.md @@ -1,17 +1,14 @@ -@page DeviceDetection_Features_ConcurrentProcessing Concurrent Processing +@page DeviceDetection_Features_ConcurrentProcessing Concurrent processing # Introduction -When using a @PerformanceProfile that loads collections completely into memory, the API's ability -to handle concurrent requests is only limited by the available hardware resources. However, when -using a lower memory @PerformanceProfile where collections are partially or fully read from file, -consideration needs to be given to how many parallel threads will be accessing the @Pipeline. +With a @PerformanceProfile that loads collections completely into memory, available hardware limits concurrent requests. When collections are read partly or entirely from a file, configure concurrency for the number of threads that will access the @Pipeline. See the [Specification](https://github.com/51Degrees/specifications/blob/main/pipeline-specification/advanced-features/parallel-processing.md#) for more technical details. -# Detail +# Configure concurrency For @PerformanceProfiles such as `LowMemory` and `Balanced`, the concurrency is limited by the number of file handles available in the file pool. In most implementations, the default value for this is @@ -113,7 +110,7 @@ Or in config file: ``` @endsnippet @startsnippet{php} -For PHP, the concurrency options is set in the php.ini file. +For PHP, set the concurrency option in the php.ini file. ``` extension=/usr/lib/php/20170718/FiftyOneDegreesHashEngine.so FiftyOneDegreesHashEngine.data_file=/path to your file/51Degrees-LiteV4.1.hash diff --git a/src/devicedetection/features/crawlers.md b/src/devicedetection/features/crawlers.md index 075c983fa7..e834f6652a 100644 --- a/src/devicedetection/features/crawlers.md +++ b/src/devicedetection/features/crawlers.md @@ -2,7 +2,7 @@ # Overview -Key crawler properties include `CrawlerUsage` and `CrawlerProductTokens`. `CrawlerUsage` contains a list of the uses of the crawler data. Crawlers are categorised into one or more of the below crawler usage values based on our judgement of publicly available information from the crawler controller and any research. +Key crawler properties include `CrawlerUsage` and `CrawlerProductTokens`. `CrawlerUsage` lists how the crawler uses collected data. We assign one or more usage values based on information published by the crawler operator and our research. # Values @@ -29,7 +29,7 @@ Control what your content can be used for by checking the `CrawlerUsage` propert - **Feed** Indicates that the crawler is used for aggregating news, information, or data. -- **Discovery** Indicates that the crawler is used to gain an understanding of the discoverability or search ranking of the crawled website or web page. Primarily relating to Search Engine Optimisation (SEO). +- **Discovery** Indicates that the crawler gathers information about a website's discoverability or search ranking, primarily for search engine optimization (SEO). # IsArtificialIntelligence @@ -45,7 +45,7 @@ Control what your content can be used for by checking the `CrawlerUsage` propert - **N/A** Not a crawler. -# Signed Agents +# Signed agents `IsCrawler` and the other crawler properties tell you what an agent declares about itself. An @agentsignature tells you what an agent has proved. The two are used together. diff --git a/src/devicedetection/features/csvdatafile.md b/src/devicedetection/features/csvdatafile.md index 1bda5f8713..041949dc26 100644 --- a/src/devicedetection/features/csvdatafile.md +++ b/src/devicedetection/features/csvdatafile.md @@ -1,17 +1,17 @@ -@page DeviceDetection_Features_CsvDataFile CSV Data File +@page DeviceDetection_Features_CsvDataFile CSV data file # Overview As well as providing device detection, we also offer access to a CSV version of our data. This includes all property values for all profiles (hardware, platform, browser, and crawler). It does not include any information to help determine device details from User-Agent or UA-CH values. -# Use Cases +# Use cases -This data may be used to lookup details using some other key such as TAC or the model name returned by native apps running on the device. +Use this data to look up device details by a key such as a TAC or a model name returned by a native app. -It can also be used to obtain sets of possible values for each value (this can also be accessed using the API with the standard data file – see the [metadata examples](@ref DeviceDetection_Examples_Metadata_Index)) +Use it to obtain the possible values for each property. You can also access these values through the API with the standard data file, as shown in the [metadata examples](@ref DeviceDetection_Examples_Metadata_Index). -You may load the data into a database or similar indexing system if you wish. The unique keys (profile id) for each profile are included in the CSV. These values are also returned by the device detection API. One use for this would be to store the profile ids along with other details related to the request. Later, some offline process could then use the profile ids to lookup the corresponding device values in the database, rather than needing to do device detection on the original evidence again. +You can load the CSV into a database or another indexing system. The CSV includes unique profile IDs, which the device detection API also returns. Store these IDs with request details so that an offline process can look up device values later without repeating detection on the original evidence. # How do I get it? diff --git a/src/devicedetection/features/falsepositivecontrol.md b/src/devicedetection/features/falsepositivecontrol.md index 841860cd8b..339befe873 100644 --- a/src/devicedetection/features/falsepositivecontrol.md +++ b/src/devicedetection/features/falsepositivecontrol.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Features_FalsePositiveControl False Positives +@page DeviceDetection_Features_FalsePositiveControl False positives # Introduction @@ -6,17 +6,17 @@ Most device detection solutions rely primarily on the User-Agent HTTP header. Ho A false positive occurs when the service tells you it has found a match but in reality the details provided are incorrect. -In these scenarios, different use cases often demand different responses. 51Degrees Device Detection allows the developer to determine exactly what happens. +You can configure how 51Degrees Device Detection handles unmatched evidence and limits differences between the evidence and a match. # HasValue -The Device Detection API returns many different properties. Every single one of these can either have a specified value or not. +Each property returned by the Device Detection API may have a value or no value. Each language implements this differently but in all cases, there will be some form of `HasValue` method or property associated with each result property. Where `HasValue` is false, accessing the property value will cause an exception to be returned or thrown (depending on the language). The detail associated with this exception will explain why the property does not have a specified value. -# No Match Found +# No match found In some cases, the device detection algorithm can fail to find any match at all for the supplied evidence. @@ -26,10 +26,10 @@ If `AllowUnmatched` is true then the default @profile will be returned. The default @profile has specific values for properties but they may be incorrect. For example, the default hardware profile has `IsMobile = false`. In reality, if no match was found then we have no idea if the device is a mobile device or not. -# Bad Match +# Bad match The `Difference` value is used to measure how different a potential match is from the supplied evidence. -The `Drift` value is used to measure how far a matching substring is from it's expected position. +The `Drift` value measures how far a matching substring is from its expected position. The maximum allowable `Difference` and `Drift` values can be set when the engine is created. This is used to control how far the supplied evidence is allowed to differ from the real-world training data that was used to create the data file. For example, if the maximum `Difference` value is set to 0 (default) then a match will only be returned if the difference value is 0. @@ -50,11 +50,10 @@ Regardless of the settings used, the result will return additional metadata that # The 'Unknown' value -Previous versions of the Device Detection API were unable to indicate that a property did not have a value. -Therefore, in the past, the string values `Unknown` or `N/A` were used to indicate that the API did not have a value for a particular property. +Some properties use the string values `Unknown` or `N/A` to indicate that a value is not known or is not applicable. These values are treated as distinct from `HasValue`, i.e., it is possible for `HasValue` to return `true` and `Value` to return `Unknown`. -In the future, this may be changed so that `HasValue` will return false if `Value` is `Unknown`, `N/A`, or similar, but this is not currently planned. + # Use cases @@ -74,7 +73,7 @@ In the future, this may be changed so that `HasValue` will return false if `Valu - **I'm migrating from 51Degrees V3 Device Detection and want to retain the previous functionality.** OR - **I want to keep my code simple as possible. I'm not worried about some false positives.** + **I want to keep my code as simple as possible. I'm not worried about some false positives.** Set `AllowUnmatched` to true. Set `Difference` (and `Drift` if using @Hash) to -1. These settings will mean that `HasValue` is never false. Each property will always have a value so you don't need to worry about dealing with a situation where they do not. diff --git a/src/devicedetection/features/index.md b/src/devicedetection/features/index.md index 8ab0310454..fcdbb02592 100644 --- a/src/devicedetection/features/index.md +++ b/src/devicedetection/features/index.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Features_Index Device Detection Features +@page DeviceDetection_Features_Index Device Detection features @subpage DeviceDetection_Features_AppleDetection diff --git a/src/devicedetection/features/nativekeylookup.md b/src/devicedetection/features/nativekeylookup.md index 8db2b2142b..e5b81fe29c 100644 --- a/src/devicedetection/features/nativekeylookup.md +++ b/src/devicedetection/features/nativekeylookup.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Features_NativeKeyLookup Native Key Lookup Feature +@page DeviceDetection_Features_NativeKeyLookup Native key lookup # Introduction @@ -23,9 +23,9 @@ Requests to the Cloud Service can include a 'NativeModel' query parameter. As lo includes one or more 'hardware device' properties and the 'profiles' property, the Cloud Service will return a result set with the details of any devices that match the supplied native model key. -NOTE: The 'profiles' and property **MUST** be selected for native lookup to function. +NOTE: You **MUST** select the 'profiles' property for native lookup to work. -For language specific details, see these [examples](@ref DeviceDetection_Examples_NativeKeyLookup_Cloud). +For setup in your programming language, see these [examples](@ref DeviceDetection_Examples_NativeKeyLookup_Cloud). # Local lookup diff --git a/src/devicedetection/features/performanceoptions.md b/src/devicedetection/features/performanceoptions.md index aea4e3b699..d463213245 100644 --- a/src/devicedetection/features/performanceoptions.md +++ b/src/devicedetection/features/performanceoptions.md @@ -1,13 +1,12 @@ -@page DeviceDetection_Features_PerformanceOptions Performance Options +@page DeviceDetection_Features_PerformanceOptions Performance options # Introduction -For device detection, as with many computing tasks, there are trade-offs to be made between the performance of the algorithm and memory usage, as well as performance vs adaptability. +Device detection has tradeoffs between speed, memory use, and tolerance for unfamiliar evidence. -Rather than trying to solve this with a one-size-fits-all approach, our Device Detection API allows you to easily configure the solution to suit your requirements. +Use the options below to configure Device Detection for your workload. -Be aware that all these options only apply to the On-premise implementation. The cloud solution is -inherently far more limited in the range of options you have to adjust performance. +These options apply to on-premise detection. The cloud service offers fewer performance controls. # Performance profile templates @@ -16,15 +15,15 @@ These collections may either be fully mapped into memory or accessed via highly The mechanism used to access the data, as well as the size of these caches, can be configured specifically. However, we have defined templates which we believe will cover the majority of scenarios. -The exact method for specifying the template will vary by programing language. See the [performance examples](@ref DeviceDetection_Examples_Performance_OnPremiseHash) for a demonstration. +How you select a template depends on your programming language. See the [performance examples](@ref DeviceDetection_Examples_Performance_OnPremiseHash). The table below explains the options, from fastest performance and highest memory usage to slowest performance and lowest memory usage. | Template Name | Behavior | Recommendations | |---|---|---| |MaxPerformance|All data from the data file is mapped into main memory at startup. As caches are not needed, data access is lock-free. | Use when memory usage is not a problem and performance is critical. This configuration is also strongly recommended when the API is running in a highly concurrent environment. | -|HighPerformance|Data accessed via caches; caches are large enough that all data from the data file can be accommodated as it is requested over time. |Generally not recommended. It offers slightly worse performance than MaxPerformance but will grow to the same memory usage over time. Can be useful as a starting point when creating a custom configuration. | -|Balanced (Default)|Data accessed via caches; some caches are smaller than the high performance template. However, there is enough space that the most commonly accessed items are retained in memory. As such, loading from the disk is still relatively uncommon (assuming a typical web server workload). |Fine for generic workloads where there is no extreme memory or performance requirement. | +|HighPerformance|Data is accessed through caches large enough to hold the entire data file as it is requested over time.|Generally not recommended. It is slightly slower than MaxPerformance and grows to the same memory use over time. It can be a starting point for a custom configuration.| +|Balanced (Default)|Data is accessed through caches, some smaller than those in HighPerformance. Frequently used items stay in memory, so disk reads are relatively uncommon for a typical web server workload.|Use for general workloads without extreme memory or performance requirements.| |LowMemory|Data always streamed from disk on-demand. | Recommended when the lowest possible memory usage is more important than performance. | The precise values associated with each template can be seen in the source code on [GitHub](https://github.com/51Degrees/51degrees-cxx/blob/67503df045efb32e84eb59fe7e320772dd6475db/src/hash/hash.c#L177). @@ -33,9 +32,9 @@ We measured throughput, startup time, and memory for Device Detection on seven m # Evaluation graphs -In version 4.5 and later, the device detection algorithm uses a single, unified predictive graph. Previously, it was possible to select between performance and predictive graphs, but these have been consolidated to provide the best balance of speed and accuracy. +In version 4.5 and later, device detection uses a single predictive graph. -# Property Indexing +# Property indexing A configuration option `propertyValueIndex` is available (introduced in version 4.5). When enabled (set to `true`), the engine indexes property values at startup. diff --git a/src/devicedetection/features/robotstxt.md b/src/devicedetection/features/robotstxt.md index 49998b75fc..66776f1b27 100644 --- a/src/devicedetection/features/robotstxt.md +++ b/src/devicedetection/features/robotstxt.md @@ -1,10 +1,10 @@ -@page DeviceDetection_Features_RobotsTxt Robots.txt Generator +@page DeviceDetection_Features_RobotsTxt Robots.txt generator # Introduction A `robots.txt` file is a plain text file hosted at the root of a website (for example `https://example.com/robots.txt`) that tells web crawlers which parts of the site they are or are not allowed to access. It follows the [Robots Exclusion Protocol](https://www.rfc-editor.org/rfc/rfc9309.html), where each block declares one or more `User-Agent` lines followed by `Allow:` and/or `Disallow:` directives that the named crawlers should respect. -With the explosion of AI training crawlers, search bots, analytics agents, archival workers and security scanners, manually maintaining a `robots.txt` that correctly distinguishes between these uses is impractical. The crawler list changes constantly, individual operators ship multiple product tokens, and a single bot can serve more than one purpose. +Maintaining a `robots.txt` file by crawler usage can be difficult. The crawler list changes, operators use multiple product tokens, and one crawler can serve more than one purpose. The `RobotsTxtEngine` shipped in the [device-detection-dotnet](https://github.com/51Degrees/51degrees-dotnet/tree/main/device-detection/RobotsTxt) package solves this problem by generating a `robots.txt` document on demand from the up-to-date 51Degrees crawler dataset, driven by a small set of allow/disallow choices expressed in terms of [crawler usages](@ref DeviceDetection_Features_Crawlers) rather than individual user-agents. @@ -27,9 +27,9 @@ produces a file to host, with no code involved. | 51Degrees Cloud | Any language, over HTTP | | Hosted generator | No code required | -# Output Properties +# Output properties -The engine produces two synthetic properties — they are not stored in any data file, they are computed at request time from the crawler dataset and the evidence supplied to the engine. +The engine computes two output properties at request time from the crawler data set and supplied evidence. These properties are not stored in a data file. ## robotstxt.plaintext @@ -39,9 +39,9 @@ Hosting this string as the body of `https://yoursite.com/robots.txt` is a valid ## robotstxt.annotatedtext -The same document as `robotstxt.plaintext`, but with comments added before each crawler block describing the crawler name, its declared usages and a reference URL where available. Useful for human review and documentation; not intended to be served verbatim, although it remains a valid `robots.txt` (lines starting with `#` are comments). +The same document as `robotstxt.plaintext`, with comments before each crawler block that name the crawler, its declared usages, and a reference URL where available. Use it for review and documentation. It is valid `robots.txt` because lines starting with `#` are comments, but it is not intended to be served verbatim. -# Input — Crawler Usages +# Input crawler usages The engine consumes evidence keyed by [crawler usage](@ref DeviceDetection_Features_Crawlers) values. For every `CrawlerUsage` value present in the loaded dataset, the engine accepts an evidence key of the form: @@ -51,13 +51,13 @@ query.robotstxt. with a value of either `allow` or `disallow` (case-insensitive; `true`/`false`, `yes`/`no`, `enabled`/`disabled`, and `on`/`off` are also accepted as synonyms). -For each crawler in the dataset, the engine checks whether **any** of that crawler's usages appears in the allow set. If so, the crawler is allowed by falling through to the wildcard catch-all block; otherwise the engine emits a dedicated `Disallow: /` block for every product token the crawler advertises. +For each crawler in the data set, the engine checks whether **any** of its usages is allowed. If so, the crawler falls through to the wildcard block. Otherwise, the engine emits a dedicated `Disallow: /` block for each product token the crawler advertises. If the same usage is supplied as both `allow` and `disallow`, `disallow` wins. -The full list of `CrawlerUsage` values — `Index`, `Train`, `Input`, `Search`, `Monitor`, `Archiving`, `Preview`, `Security`, `Analytics`, `Feed`, `Discovery` — is documented under [Crawlers](@ref DeviceDetection_Features_Crawlers). Because the set is data-driven, querying the dataset directly is the way to discover the values currently supported. See [Cloud Usage](#cloud-usage) below for the metadata endpoint. +The [Crawlers](@ref DeviceDetection_Features_Crawlers) page describes `Index`, `Train`, `Input`, `Search`, `Monitor`, `Archiving`, `Preview`, `Security`, `Analytics`, `Feed`, and `Discovery`. Query the data set for the currently supported `CrawlerUsage` values, as shown under [Cloud Usage](#cloud-usage). -# Terms Document Locator (TDL) +# Terms document locator (TDL) A Terms Document Locator (TDL) is a stable URL that points at the human-readable terms of use that crawlers in the wildcard `Allow:` block must comply with. When the engine receives the additional evidence key: @@ -75,11 +75,11 @@ The `tdl` value can be: Entries that are neither absolute URIs nor known macro ids are silently dropped, per the IETF-Robots TDL specification. If everything supplied is dropped, the engine falls back to the standard `Allow: /` wildcard block. -# Cloud Usage +# Cloud usage Robots.txt is available from 51Degrees Cloud on the free plan. For a step by step guide to fetching the file and keeping it fresh, see @ref Services_Cloud_RobotsTxt. When the properties are enabled on a Resource Key, two additional steps make integration straightforward. -## Discovering the available CrawlerUsage values +## Discover available CrawlerUsage values Before deciding which `query.robotstxt.` parameters to send, fetch the full list of allowed `CrawlerUsage` values from the cloud metadata API: @@ -87,7 +87,7 @@ Before deciding which `query.robotstxt.` parameters to send, fetch the fu https://cloud.51degrees.com/api/metadata/values?propertyName=CrawlerUsage ``` -This returns the canonical list of usages available on your Resource Key tier — use the value names verbatim (lower-cased) as the suffix of the evidence parameter. +This returns the usage values available on your Resource Key tier. Use the value names in lowercase as the suffix of each evidence parameter. ## Calling the JSON endpoint @@ -115,11 +115,11 @@ The response is a standard 51Degrees Cloud JSON document, with the generated tex } ``` -The Resource Key must include the `robotstxt.plaintext` and/or `robotstxt.annotatedtext` properties. A License-key-only caller names them in the `values` parameter instead. The `plaintext` value is intended for production use. The `annotatedtext` value is intended for internal use to understand why certain choices were made and provide context. +The Resource Key must include `robotstxt.plaintext`, `robotstxt.annotatedtext`, or both. If you use only a License Key, request the properties in the `values` parameter instead. Use `plaintext` in production and `annotatedtext` for internal review of the generated rules. Create a Resource Key that includes `robotstxt.plaintext` and `robotstxt.annotatedtext` at [configure.51degrees.com](https://configure.51degrees.com). Leave its domain list empty when your server makes the request, because a key limited to domains refuses requests that come from anywhere else. -# On Premise Engine Configuration +# On-premise engine configuration The engine is built via `RobotsTxtEngineBuilder` and added to a Pipeline that also contains a `DeviceDetectionHashEngine` (the engine reads the crawler list out of the loaded device-detection data file at `AddPipeline` time). @@ -133,8 +133,8 @@ Builder parameters: Properties advertised by the engine carry the data tier of the underlying device-detection data file, so `robotstxt.plaintext` and `robotstxt.annotatedtext` are only available when running against an Enterprise tier file (or higher) that contains the crawler properties. -# See Also +# See also -- @ref DeviceDetection_Features_Crawlers — `CrawlerUsage` value definitions. -- [51Degrees Robots.txt generator](https://51degrees.com/robots-txt) — hosted UI built on top of the same engine. +- @ref DeviceDetection_Features_Crawlers for `CrawlerUsage` value definitions. +- [51Degrees Robots.txt generator](https://51degrees.com/robots-txt), a hosted interface for the same engine. - @ref Services_Cloud_RobotsTxt, a step by step guide to getting a fresh robots.txt from the cloud on a schedule. diff --git a/src/devicedetection/features/taclookup.md b/src/devicedetection/features/taclookup.md index 8bb5602145..33737be1bf 100644 --- a/src/devicedetection/features/taclookup.md +++ b/src/devicedetection/features/taclookup.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Features_TacLookup TAC Lookup Feature +@page DeviceDetection_Features_TacLookup TAC lookup # Introduction @@ -18,11 +18,9 @@ other data query mechanism. # Cloud Service -Requests to the Cloud Service can include a 'TAC' query parameter. As long as the [Resource Key](@term{ResourceKey}) -includes one or more 'hardware device' properties and the 'profiles', and 'TAC' property, the Cloud Service will -return a result set with the details of any devices that match the supplied TAC. +Include a 'TAC' query parameter in your Cloud Service request. Your [Resource Key](@term{ResourceKey}) must include one or more hardware device properties, plus 'profiles' and 'TAC'. The service returns details of devices that match the supplied TAC. -NOTE: The 'profiles' and 'TAC' properties ***MUST** be selected for TAC lookup to function. +NOTE: You **MUST** select the 'profiles' and 'TAC' properties for TAC lookup to work. For language specific details, see these [examples](@ref DeviceDetection_Examples_TacLookup_Cloud). diff --git a/src/devicedetection/features/thirdpartycookies.md b/src/devicedetection/features/thirdpartycookies.md index 48f442736e..7d509eac1b 100644 --- a/src/devicedetection/features/thirdpartycookies.md +++ b/src/devicedetection/features/thirdpartycookies.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Features_ThirdPartyCookies Third-Party Cookies Detection +@page DeviceDetection_Features_ThirdPartyCookies Third-party cookie detection # Introduction @@ -8,18 +8,18 @@ For businesses that rely on third-party cookies for functionality such as cross- 51Degrees provides a lightweight, stateless mechanism to detect third-party cookie support as part of the cloud service. -# How It Works +# How it works -The detection mechanism relies on verifying whether the browser can send cookies to a third-party domain. This is achieved through generated @ref PipelineApi_Features_ClientSideEvidence "client-side evidence" JavaScript that contains special detection snippets. +The generated @ref PipelineApi_Features_ClientSideEvidence "client-side evidence" JavaScript checks whether the browser can send a cookie to a third-party domain. -## Two-Origin Architecture +## Two-origin architecture The detection requires two distinct origins: 1. **Origin A** - The customer's website (e.g., `example.com`) 2. **Origin B** - The third-party detection endpoint (e.g., `cloud.51degrees.com`) -## Detection Flow +## Detection flow 1. The user's page on Origin A includes the 51Degrees @ref PipelineApi_Features_ClientSideEvidence "client-side evidence" JavaScript. This JavaScript can be served from either Origin A (first-party) or Origin B (third-party) - the serving location does not affect the detection. 2. The JavaScript contains a detection snippet that always makes a request to the third-party endpoint (Origin B) to check cookie support. @@ -31,7 +31,7 @@ The detection requires two distinct origins: The key point is that regardless of where the JavaScript is served from, the detection snippet inside always communicates with a third-party domain to test cross-origin cookie behavior. -## Cookie Attributes +## Cookie attributes The detection cookie uses specific attributes required for cross-site delivery in modern browsers: @@ -74,9 +74,9 @@ Third-party cookies detection is automatically performed when using the 51Degree **Note:** If you are using the 51Degrees Cloud service, you need a Resource Key that includes the `ThirdPartyCookiesEnabled` and `ThirdPartyCookiesEnabledJavascript` properties. The @ref Services_Configurator "Resource Key guide" shows how to create one. -When the JavaScript is loaded and makes its callback to the cloud service, the detection happens transparently. The results are available in the response data alongside other device detection properties. +After the JavaScript callback to the cloud service, the response includes the cookie detection result alongside the other device detection properties. -## Custom Endpoint Configuration +## Custom endpoint configuration By default, the detection snippet communicates with `cloud.51degrees.com`. If you are hosting your own 51Degrees cloud service or need to use a different endpoint, you can customize the third-party cookie detection endpoint by setting the `window.fodTpcEndpoint` global variable before loading the JavaScript: @@ -89,7 +89,7 @@ By default, the detection snippet communicates with `cloud.51degrees.com`. If yo This allows you to point the detection to your own hosted instance while maintaining the third-party cookie detection functionality. -# Browser Support Considerations +# Browser support considerations Modern browsers have varying levels of third-party cookie support: diff --git a/src/devicedetection/features/useragentclienthints/headers.md b/src/devicedetection/features/useragentclienthints/headers.md index b70d855b39..dc9239a50f 100644 --- a/src/devicedetection/features/useragentclienthints/headers.md +++ b/src/devicedetection/features/useragentclienthints/headers.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Features_UACH_Headers HTTP Headers +@page DeviceDetection_Features_UACH_Headers HTTP headers # Introduction @@ -10,15 +10,11 @@ The [Overview page](@ref DeviceDetection_Features_UACH_Overview) includes advice # Background -In the past, device detection worked primarily by examining the -value of the User-Agent HTTP header. This header is always sent as part -of the first request to a web server, meaning device information was -available immediately on the server-side. +Device detection can use the User-Agent HTTP header when it is present in the first request. With UA-CH, only a limited subset of information is sent as part of the first request. -If the server wishes to know more, then it needs to set a HTTP header in -the response to request the additional detail. +To request more detail, set an HTTP response header. The 51Degrees API will automatically determine the names and values of any response headers that need to be set based on the initial information. @@ -70,9 +66,7 @@ Permissions-Policy: ch-ua-full-version-list=(self "https://cloud.51degrees.com") If you are using our Pipeline API on your server (either cloud or On-premise) then you'll need a way to set the `Accept-CH` header in the response to the client. -In either case, you need to ensure the relevant `SetHeaderBrowserAccept-CH`, `SetHeaderHardwareAccept-CH` and -`SetHeaderPlatformAccept-CH` properties are included in the results (all properties are included -by default for On-premise). +Include the relevant `SetHeaderBrowserAccept-CH`, `SetHeaderHardwareAccept-CH`, and `SetHeaderPlatformAccept-CH` properties in the results. On-premise detection includes all properties by default. If you're unsure which ones are relevant for you, see the [required values](@ref DeviceDetection_Features_UACH_RequiredUachHeaders) page. @@ -111,8 +105,7 @@ such that the web application may not function without them. When the browser su it checks if the indicated Client Hints were sent in the original request, and if not, immediately makes another request supplying the missing Client Hints. -This has to be used with caution for it may often cause another round trip for the client. We recommend only using `Critical-CH` if you need to do the -device detection immediately on the very first request from the user. +Use `Critical-CH` only when you need device detection on the first request, because it can cause an additional browser round trip. In that case, the application or middleware logic must consider if the Client Hints necessary for the device detection were missing. If the Client Hints were missing, the application or @@ -125,10 +118,8 @@ Critical-CH: sec-ch-ua-arch, sec-ch-ua-full-version, sec-ch-ua-full-version-list Accept-CH: sec-ch-ua-arch, sec-ch-ua-full-version, sec-ch-ua-full-version-list, sec-ch-ua-model, sec-ch-ua-platform, sec-ch-ua-platform-version ``` -## B2B Service Supplier {#UACH_Http_Headers_BtoB} -If your service would be classed as a third-party in the 'browser to web server' communication, -then you'll also need to arrange for your clients to let their users know that it's okay to -send your server UA-CH values. +## B2B service supplier {#UACH_Http_Headers_BtoB} +If your service receives requests as a third party, ask your customers to configure their websites so that browsers can send UA-CH values to your service. This is because the 'high-entropy' UA-CH values are not sent to third-parties by default. In order to do this, you'll need to ask your customers to use the `Delegate-CH` HTML directive or diff --git a/src/devicedetection/features/useragentclienthints/javascript.md b/src/devicedetection/features/useragentclienthints/javascript.md index d9d9ded219..4fd20ce284 100644 --- a/src/devicedetection/features/useragentclienthints/javascript.md +++ b/src/devicedetection/features/useragentclienthints/javascript.md @@ -9,8 +9,7 @@ This page explains how to use the JavaScript approach with our API. The [UA-CH headers page](@ref DeviceDetection_Features_UACH_Headers) explains the alternative. The [Overview page](@ref DeviceDetection_Features_UACH_Overview) includes advice if you're unsure which approach to take. -Using the UA-CH JavaScript API is very simple if you are calling our Cloud Service directly. -See details below. +For calls directly to our Cloud Service, follow the Cloud instructions below. Otherwise, if you are using one of our web integrations, you can use the 'Integrated' approach described below. If not, you'll need to use the 'non-integrated' approach instead. @@ -36,10 +35,7 @@ In either case, you need to ensure the `JavascriptGetHighEntropyValues` property in the results (all properties are included by default for On-premise). ## Integrated {#UACH_Javascript_Integrated} -If you are using our [web integration](@ref PipelineApi_Features_WebIntegration) with -[client-side evidence](@ref PipelineApi_Features_ClientSideEvidence) enabled, then this will take -care of sending the snippet to the client device, getting the values back to the server and -passing them into our API. +With [client-side evidence](@ref PipelineApi_Features_ClientSideEvidence) enabled, our [web integration](@ref PipelineApi_Features_WebIntegration) sends the snippet to the browser, returns the values to your server, and passes them to our API. No additional configuration is required for either Cloud or On-premise solutions. The device detection engine natively processes the `getHighEntropyValues()` result when passed as evidence. @@ -90,12 +86,12 @@ detection engine natively processes this evidence format, converting it to the e See the [Getting Started Console On-premise](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise) example for a complete demonstration of this approach. -# Alternative Evidence Formats {#UACH_Javascript_Alternatives} +# Alternative evidence formats {#UACH_Javascript_Alternatives} In addition to the `getHighEntropyValues()` JavaScript API result, the device detection engine supports the [Structured User Agent (SUA)](@ref DeviceDetection_Features_UACH_SUA) format from the OpenRTB 2.6 specification, commonly used in programmatic advertising scenarios. -## Technical Details {#UACH_Javascript_Technical} +## Technical details {#UACH_Javascript_Technical} The `getHighEntropyValues()` evidence is converted internally to the equivalent `Sec-CH-UA-*` HTTP headers before processing: @@ -108,6 +104,4 @@ headers before processing: - `Sec-CH-UA-Arch` - `Sec-CH-UA-Bitness` -The conversion happens natively in the device detection engine (in the C layer), making it -efficient and seamless. This eliminates the need for any additional pipeline elements or -pre-processing steps that were required in earlier versions. +The device detection engine converts the evidence in its C layer. You do not need additional pipeline elements or preprocessing steps. diff --git a/src/devicedetection/features/useragentclienthints/overview.md b/src/devicedetection/features/useragentclienthints/overview.md index 037a06e43e..2bb87f2e3f 100644 --- a/src/devicedetection/features/useragentclienthints/overview.md +++ b/src/devicedetection/features/useragentclienthints/overview.md @@ -1,8 +1,8 @@ -@page DeviceDetection_Features_UACH_Overview UA-CH Overview +@page DeviceDetection_Features_UACH_Overview UA-CH overview # Introduction -User-Agent Client Hints (UA-CH) are part of a Google proposal to replace the existing User-Agent HTTP header. +User-Agent Client Hints (UA-CH) provide device and browser information through HTTP headers or a JavaScript API. This page gives an overview of UA-CH detection in our API. It also provides guidance on which mechanism to use based on your use-case. @@ -41,16 +41,16 @@ We have examples that demonstrate UA-CH detection in various scenarios: ## Current support -The 51Degrees Device Detection API provides comprehensive UA-CH support: +51Degrees Device Detection supports the following UA-CH capabilities: -- **Basic support** - We detect devices using the Sec-CH-UA header (since December 7, 2020) -- **Full support** - We detect devices, operating systems, and browsers from UA-CH headers (Version 4.4 and data files from [June 2022 onwards](https://51degrees.com/blog/updates-to-user-agent-client-hints-version-4-4)) +- **Basic support** - Detect devices using the Sec-CH-UA header +- **Full support** - Detect devices, operating systems, and browsers from UA-CH headers with Version 4.4 and data files from [June 2022 onwards](https://51degrees.com/blog/updates-to-user-agent-client-hints-version-4-4) - **Windows 11 detection** - We [identify Windows 11 using User-Agent Client Hints](https://51degrees.com/blog/windows-11-detectable-with-uach) (the [only reliable method](https://docs.microsoft.com/en-us/microsoft-edge/web-platform/how-to-detect-win11)) ## JavaScript API support -We added support for the UA-CH [JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/User-Agent_Client_Hints_API) in: +The UA-CH [JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/User-Agent_Client_Hints_API) requires: - .NET API version 4.4.19 - Data files from March 6, 2023 @@ -120,7 +120,7 @@ The authors of the proposal have written [a web.dev guide to how UA-CH works](ht ## Technical context -User-Agent Client Hints extends the previously existing Client Hints content negotiation feature. +User-Agent Client Hints extend the Client Hints content negotiation feature. **General documentation:** - [MDN Client Hints documentation](https://developer.mozilla.org/en-US/docs/Glossary/Client_hints) diff --git a/src/devicedetection/features/useragentclienthints/requiredUachHeaders.md b/src/devicedetection/features/useragentclienthints/requiredUachHeaders.md index 4d4338e3da..61864e3f25 100644 --- a/src/devicedetection/features/useragentclienthints/requiredUachHeaders.md +++ b/src/devicedetection/features/useragentclienthints/requiredUachHeaders.md @@ -1,4 +1,4 @@ -@page DeviceDetection_Features_UACH_RequiredUachHeaders Required UA-CH Headers +@page DeviceDetection_Features_UACH_RequiredUachHeaders Required UA-CH headers # Overview @@ -15,8 +15,7 @@ recommend supplying all of these for the best detection results: - Sec-CH-UA-Platform - Sec-CH-UA-Platform-Version -If you want to be more selective for some reason, the rest of the page describes how the data is -used. The table at the end shows which UA-CH values are needed for each 'component'. +To request only the values needed for specific properties, use the component table below. # Background @@ -37,7 +36,7 @@ We concatenate the various UA-CH headers that are needed to identify a component # Pseudo-headers {#UACH_Http_Headers_Pseudoheaders} -The table below shows which pseudo-headers are required in order to detect each component. These are the minimum pseudo-headers we use to detect the component; however, we recommend providing all UA-CH values for the best detection. Additionally, this table is only applicable for Chromium-based browsers; to detect non-Chromium browsers, you will need to continue supplying User-Agent information. +The table shows the UA-CH values used to build pseudo-headers for each component. We recommend providing all UA-CH values for the best detection results. This applies to Chromium-based browsers. Continue supplying User-Agent information for other browsers. Some pseudo-headers are not required to detect the component but can provide more detailed detection results. For example, Sec-CH-UA-Platform-Version is not required to determine the Platform component, but provides additional version information when supplied. @@ -50,7 +49,7 @@ To raise the limit, set a larger value before creating the engine, which uses mo ## Key - x = This value is required in order to determine the component. - x* = This value is not required, but if provided may return more detailed results. -- y and z = One of these values are required. Supplying y may return a more accurate result and removes the need to supply z. +- y and z = One of these values is required. Supplying y may return a more accurate result and removes the need to supply z. |UA-CH header|Hardware|Platform|Browser/App| |---|---|---|---| diff --git a/src/devicedetection/features/useragentclienthints/sua.md b/src/devicedetection/features/useragentclienthints/sua.md index 5f448cd549..a51a1dcc1c 100644 --- a/src/devicedetection/features/useragentclienthints/sua.md +++ b/src/devicedetection/features/useragentclienthints/sua.md @@ -6,7 +6,7 @@ The [OpenRTB 2.6 specification](https://github.com/InteractiveAdvertisingBureau/ User Agent (`device.sua`) format for representing User-Agent Client Hints. This is commonly used in programmatic advertising and real-time bidding scenarios. -# Passing SUA to Device Detection +# Pass SUA to Device Detection If you receive UA-CH data in the SUA format, you can pass it directly to the device detection engine with the `query.` or `cookie.` prefix: @@ -15,7 +15,7 @@ engine with the `query.` or `cookie.` prefix: flowData.AddEvidence("query.51D_StructuredUserAgent", suaJsonString); ``` -# SUA Format +# SUA format The SUA format looks like this: @@ -32,7 +32,7 @@ The SUA format looks like this: } ``` -# Technical Details +# Technical details The SUA format is converted internally to the equivalent `Sec-CH-UA-*` HTTP headers before processing: @@ -46,11 +46,9 @@ headers before processing: - `Sec-CH-UA-Arch` - `Sec-CH-UA-Bitness` -The conversion happens natively in the device detection engine (in the C layer), making it -efficient and seamless. This eliminates the need for any additional pipeline elements or -pre-processing steps that were required in earlier versions. +The device detection engine converts SUA evidence in its C layer. You do not need additional pipeline elements or preprocessing steps. -# Related Pages +# Related pages For more details on OpenRTB integration, see the [OpenRTB Mappings](@ref DeviceDetection_OtherIntegrations_OpenRTBMappings) page. diff --git a/src/devicedetection/hash.md b/src/devicedetection/hash.md index 2164c62ef5..42ecbb4af6 100644 --- a/src/devicedetection/hash.md +++ b/src/devicedetection/hash.md @@ -1,7 +1,7 @@ -@page DeviceDetection_Hash Hash Algorithm +@page DeviceDetection_Hash Hash algorithm # Introduction -During extensive analysis of web interactions over several years, we discovered that a smart method of identifying and hashing substrings within User-Agents could be used to produce an optimum data set that displays the following characteristics: +The Hash algorithm identifies and hashes substrings in User-Agents to produce a data set with the following characteristics: - Speed: over 1 million detections per second on an eight-core AWS Graviton3 instance with the whole data file in memory, as measured in the [hardware benchmarks](@ref ProductSummaries_Benchmarks_Hardware). - Fast startup: the whole data file loads into memory, ready to detect, in under 150 milliseconds on the same Graviton3 instance, which matters most where servers start and stop as demand changes. @@ -40,7 +40,9 @@ A separate graph is used to detect the hardware device. After matching a few nod Many Android User-Agents will consistently place the substrings associated with the device at this position. A long list of hash values, perhaps tens of thousands, could then be evaluated to either identify the device or narrow down the options. Perhaps just the first 5 characters `SPH-D` will be used to reduce the possible devices. This is very efficient as it considerably narrows the possible devices with a single hash value calculation and lookup. This process of hashing the most relevant substrings will continue until a complete device including hardware, operating system, and browser has been identified using the graphs for each. -# Data set production {#DeviceDetection_Hash_DataSetProduction}The production of the optimized data set is computationally intensive as training data is evaluated. However the resulting data set is small and fast for 51Degrees users. As only the relevant characters are evaluated and some tolerance for substrings drifting within the User-Agent can be allowed for, the predictive features of **Hash** are better than character based trie solutions. +# Data set production {#DeviceDetection_Hash_DataSetProduction} + +Producing the optimized data set is computationally intensive because it requires evaluating training data. However the resulting data set is small and fast for 51Degrees users. As only the relevant characters are evaluated and some tolerance for substrings drifting within the User-Agent can be allowed for, the predictive features of **Hash** are better than character based trie solutions. With the help of optional @usagesharing, real world data is fed back into the data set production. This is constant learning cycle where new data, unknown to the system, is processed using the knowledge the system already has to enhance the graphs it produces. Not just for the data it has already seen, but for data it expects to be seen. @@ -52,11 +54,15 @@ Graphs are constructed using a series of decision trees to determine the best st Performance optimized graphs are constructed using decision trees which result in the fastest detection for a given evidence string. Generally, this results in nodes where a long hash is looked for in a narrow range. For example, if the substring `Android 4.0.4` is known to exist at character positions 18-25 within the training data, why look for it in a larger range which would be slower? Using the exact position `Android 4.0.4` at character 20 reduces the possible devices very quickly, and evaluation of the exact position is quicker than evaluation of a range. This approach works very well with the training data, but how does it work on evidence which has not been seen before? Consider a User-Agent containing the substring `iPhone 8` which is in the training data, then along comes one containing the substring `iPhone 8s`. All substrings to the right of this will be shifted by one character. If the next node is looking for `Version` starting at character 120, it now needs to be found at character 121. Because of the very narrow range used in a performance graph, the string would not be matched. Predictive graphs help to solve this problem, so it's unusual to use performance graphs in isolation. -## Predictive graphs {#DeviceDetection_Hash_DataSetProduction_Predictive}Predictive optimized graphs are constructed using decision trees which result in the most accurate result for evidence not in the training data. Generally, this results in nodes where a short hash is looked for in a large range. For example, the substring `Android` is usually found around the same area of the User-Agent. So, when constructing a graph for the OS @component, instead of looking for an exact position, why not look for it in the general area it is expected to be? This narrows down the result to Android, then it can be narrowed down further. In contrast to the performance graphs, the above example will probably not be found by matching `4.0.4` next. It's more likely that it will be narrowed down in stages. For example, `4.0.` then `4 `. Constructing a graph in this way ensures that things which do not have an exact match in the training data are still matched to a sufficient degree of accuracy in practice. Consider a new Android version 4.0.5 which is not yet in the training data. Using the predictive graph, `4.0.` would be matched, and the best known match would be correct. If we had looked for `4.0.4`, nothing would have been found after `Android` and the result would have been an unknown Android version. +## Predictive graphs {#DeviceDetection_Hash_DataSetProduction_Predictive} + +We use decision trees to construct predictive graphs that match evidence not in the training data. Generally, this results in nodes where a short hash is looked for in a large range. For example, the substring `Android` is usually found around the same area of the User-Agent. So, when constructing a graph for the OS @component, instead of looking for an exact position, why not look for it in the general area it is expected to be? This narrows down the result to Android, then it can be narrowed down further. In contrast to the performance graphs, the above example will probably not be found by matching `4.0.4` next. It's more likely that it will be narrowed down in stages. For example, `4.0.` then `4 `. Constructing a graph in this way ensures that things which do not have an exact match in the training data are still matched to a sufficient degree of accuracy in practice. Consider a new Android version 4.0.5 which is not yet in the training data. Using the predictive graph, `4.0.` would be matched, and the best known match would be correct. If we had looked for `4.0.4`, nothing would have been found after `Android` and the result would have been an unknown Android version. -# Predictive power {#DeviceDetection_Hash_PredictivePower}When constructing graphs, there is always the risk of over (or under) fitting the data to the training data. The graphs contained in the **Hash** data set are produced to fit "just right" to the training data seen from optional @usagesharing, and data which has not yet been seen. This is a delicate balance, which we have perfected for most use cases. For cases where some tweaking is required, the algorithm can be configured to be more accommodating (or less) to unknown data. +# Predictive power {#DeviceDetection_Hash_PredictivePower} -The **Hash** algorithm has two tolerances which can be enabled through the API to enhance the predictive power of the algorithm. Predictive power of a matching algorithm can be measured by how accurately it can match things it has not yet encountered based solely on the information it already has. By ignoring irrelevant substrings, the **Hash** algorithm already fairs well when matching unknown User-Agents. But by configuring drift and difference, the predictive power can be fine tuned by the user. +When constructing graphs, we risk fitting them too closely or too loosely to the training data. The graphs contained in the **Hash** data set are produced to fit "just right" to the training data seen from optional @usagesharing, and data which has not yet been seen. This is a delicate balance, which we have perfected for most use cases. For cases where some tweaking is required, the algorithm can be configured to be more accommodating (or less) to unknown data. + +The **Hash** algorithm has two configurable tolerances, drift and difference, that control how it matches evidence not seen in training. Ignoring irrelevant substrings already helps the algorithm match unknown User-Agents. You can adjust the tolerances to make matching more or less permissive. ## Drift The drift tolerance allows for a substring to be matched in a wider range of character positions. As an example, the User-Agent may be altered by inserting a space near the start of the string. If we require the characters to be in the exact expected positions then this could match as something other than we might expect. @@ -70,4 +76,6 @@ The difference tolerance allows for User-Agents where some characters differ sli Take the example User-Agent (assuming we are using a performance graph) for a known browser version which contains the substring `Android 4.0.4`, and an unknown version containing the substring `Android 4.0.5`. Due to the nature of the chosen **hash** algorithm, the hashes of the two substrings vary proportionally to the difference in ASCII value of the last character. This means that if the difference is set to one, the unknown substring will be allowed as a match for the known Android version. -# The algorithm in action {#Device_Detection_Hash_InAction}Now that you've got an idea of how the algorithm and data structure work, why not try our [User-Agent Tester](https://51degrees.com/developers/user-agent-tester) to see the algorithm in action. Or try it for yourself with our [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise) examples. +# The algorithm in action {#Device_Detection_Hash_InAction} + +Try our [User-Agent Tester](https://51degrees.com/developers/user-agent-tester) to see detection results, or run the [Getting Started](@ref DeviceDetection_Examples_GettingStarted_Console_OnPremise) examples. diff --git a/src/devicedetection/migrationguides/deviceatlas.md b/src/devicedetection/migrationguides/deviceatlas.md index 91bb5464c2..84522b58f5 100644 --- a/src/devicedetection/migrationguides/deviceatlas.md +++ b/src/devicedetection/migrationguides/deviceatlas.md @@ -1,8 +1,8 @@ -@page DeviceDetection_MigrationGuides_DeviceAtlas Device Atlas +@page DeviceDetection_MigrationGuides_DeviceAtlas DeviceAtlas # Introduction -Here you'll find a list of DeviceAtlas properties and their 51Degrees equivalent. +Use the table below to find 51Degrees properties that correspond to DeviceAtlas properties. Details of all available DeviceAtlas properties can be found on their website, whilst the [51Degrees property dictionary](https://51degrees.com/developers/property-dictionary) contains details of all our properties and their possible values. To see how these equivalencies look in code, take a look at the [DeviceAtlas comparison implementation](https://github.com/51Degrees/51degrees-java/blob/main/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/comparison/DetectionImplDeviceAtlas.java) in our Java examples repository, which maps DeviceAtlas properties onto their 51Degrees counterparts. It is a skeleton: the DeviceAtlas calls are commented out and untested, so you will need to uncomment them and add the DeviceAtlas dependencies to run it. Once working, register it in [`Comparer`](https://github.com/51Degrees/51degrees-java/blob/main/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/comparison/Comparer.java) to benchmark both providers side by side. Note that the comparison measures detection time rather than displaying property values. @@ -11,13 +11,13 @@ To see how these equivalencies look in code, take a look at the [DeviceAtlas com # Obsolete DeviceAtlas capabilities DeviceAtlas was launched in 2008 when the web and mobile was very different to now. As such, many of the properties DeviceAtlas list have not proven relevant to businesses who've migrated to 51Degrees. -Examples of these include properties related to J2ME which has been surpassed by platforms like Android, iOS, and Windows Phone, legacy data delivery mechanisms that are no longer in use, or markup specifications that are no longer popular. + Such capabilities are considered obsolete and for reference are listed at the bottom of this page. Skip to the list of [obsolete capabilities](@ref DeviceDetection_MigrationGuides_DeviceAtlas_Obsolete). -# Mapped DeviceAtlas API Names +# Mapped DeviceAtlas API names The following table lists the DeviceAtlas API Name and 51Degrees properties and values that contain the equivalent data. @@ -46,8 +46,8 @@ The following table lists the DeviceAtlas API Name and 51Degrees properties and | css.transforms | [CssTransforms](https://51degrees.com/developers/property-dictionary?item=Web%20Browser%20and%20Apps%7CCss) | | Indicates if the browser supports 2D transformations in CSS3 including rotating, scaling, etc. This property includes support for both transform and transform-origin properties. | | css.transitions | [CssTransitions](https://51degrees.com/developers/property-dictionary?item=Web%20Browser%20and%20Apps%7CCss) | | Indicates if the browser supports CSS3 transitions elements, used for animating changes to properties. | | diagonalScreenSize | [ScreenInchesDiagonal](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) | | Indicates the diagonal size of the device's screen in inches. This property is not applicable for a device that does not have a screen. | -| displayColorDepth | [BitsPerPixel](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) | | Indicates the number of bits used to describe the colour of each individual pixel, also known as bit depth or colour depth. | -| displayHeight | [ScreenPixelsHeight](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) | | Indicates the height of the device's screen in pixels.This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel height will be the smaller value compared to the pixel width. | +| displayColorDepth | [BitsPerPixel](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) | | Indicates the number of bits used to describe the color of each individual pixel, also known as bit depth or color depth. | +| displayHeight | [ScreenPixelsHeight](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) | | Indicates the height of the device's screen in pixels. This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel height will be the smaller value compared to the pixel width. | | displayPpi | [ScreenInchesWidth](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) [ScreenPixelsWidth](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) | | Refers to the width of the device's screen in inches. This property will return the value 'Unknown' for desktop or for devices which do not have an integrated screen. Indicates the width of the device's screen in pixels. This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel width will be the larger value compared to the pixel height. | | displayWidth | [ScreenPixelsWidth](https://51degrees.com/developers/property-dictionary?item=Device%7CScreen) | | Indicates the width of the device's screen in pixels. This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel width will be the larger value compared to the pixel height. | | edge | [SupportedBearers](https://51degrees.com/developers/property-dictionary?item=Device%7CConnectivity) | EDGE | Indicates the list of wireless data technologies supported by the device, including Bluetooth. If the device supports phone calls, the SMS value is also returned. | @@ -58,7 +58,7 @@ The following table lists the DeviceAtlas API Name and 51Degrees properties and | html.audio | [Html5Audio](https://51degrees.com/developers/property-dictionary?item=Web%20Browser%20and%20Apps%7CHtml) | | Lists what audio formats, if any, the browser supports using the HTML5 `