Java packages for the Pipeline API, Device Detection, IP Intelligence and Location
Our User-Agent parser for Java supports Device Detection, browser detection, mobile detection, and crawler detection on-premise or in the cloud. IP Intelligence adds IP geolocation, including IP to country data.
It reads User-Agent and User-Agent Client Hints, HTTP request headers that carry browser and device information. For cloud bot detection, Human Confidence reports confidence that a person is viewing the page.
Each product is a separate Maven Central package. For Device Detection, cloud or on-premise:
<!-- Make sure to select the latest version from https://mvnrepository.com/artifact/com.51degrees/pipeline.device-detection -->
<dependency>
<groupId>com.51degrees</groupId>
<artifactId>device-detection</artifactId>
<version>4.5.x</version>
</dependency>The product guides below list the other packages. To build from source, see Getting the code.
Try the User-Agent tester and IP tester. For cloud use, create a Resource Key.
Created from pipeline-java, device-detection-java, ip-intelligence-java, location-java, device-detection-java-examples, and ip-intelligence-java-examples, this repository continues their work.
| Product | Read first | Documentation |
|---|---|---|
| Pipeline API | pipeline/README.md | Java |
| Device Detection | device-detection/README.md | Java |
| IP Intelligence | ip-intelligence/README.md | Java |
| Location | location/README.md | Java |
| Path | Contents |
|---|---|
pipeline |
The Pipeline API packages, com.51degrees:pipeline.* |
device-detection |
The Device Detection packages, com.51degrees:device-detection* |
ip-intelligence |
The IP Intelligence packages, com.51degrees:ip-intelligence* |
location |
The Location packages, com.51degrees:geo-location* |
examples/device-detection |
Console and web examples for Device Detection |
examples/ip-intelligence |
Console and web examples for IP Intelligence, including the mixed examples that run both products |
cxx |
Submodule of 51degrees-cxx, with the C and C++ code the on-premise engines are built from and the data submodule in cxx/data |
pom.xml |
The reactor that builds everything here. It is never published |
ci |
The scripts the shared 51Degrees CI workflows call |
git clone --recurse-submodules https://github.com/51Degrees/51degrees-java.git
cd 51degrees-java
The free data files come from the data
repository, which is the cxx/data submodule. Each one is listed there as a
.link file, and a script downloads them all into place:
cxx/data/get-data-files.sh
On Windows, run cxx\data\get-data-files.ps1 in PowerShell instead. The
examples run the script themselves for a free file they need that is missing.
In a clone made before the data repository was added, delete the
cxx/device-detection-data and cxx/ip-intelligence-data folders once cxx no
longer includes them, because Git leaves a removed submodule's folder on disk.
You need a JDK (8 or later) and either Maven 3.8 or later or the mvnw
wrapper in this folder. The two on-premise engines compile their native
library during the build, which needs CMake 3.10 or later and a C++ toolchain:
Visual Studio with the C++ workload on Windows, GCC or Clang elsewhere.
From this folder:
mvn install -DskipTests
That builds every package in dependency order, so a change to pipeline is
seen by device-detection in the same build. To skip the native libraries,
for example on a machine without a C++ toolchain, add -DskipNativeBuild=true.
To build one product and what it depends on, name its folder:
mvn install -DskipTests -pl device-detection -am
mvn surefire:test
The cloud tests need a Resource Key, passed as -DTestResourceKey=<key>. The
on-premise tests need the free data files, which the script in
Getting the code downloads. For the Enterprise IP
Intelligence data file, see ip-intelligence/README.md.
Tests find data files by searching from the root of this repository, so run
Maven from here rather than from inside a package folder.
The examples reference the packages published to Maven Central, which is how
a project of your own uses them. To build and run them against the libraries
in this repository instead, activate the dev profile:
mvn install -DskipTests -Pdev
The C++ wrappers Java_Hash_Engine.cpp and Java_Ipi_Engine.cpp are
generated and must not be edited by hand. They include the C++ headers through
cxx/, so SWIG needs the root of this repository on its include path. With
SWIG 4.0 or later, from this folder:
cd device-detection/device-detection.hash.engine.on-premise/src/main/cxx
swig -c++ -java -I../../../../.. -package fiftyone.devicedetection.hash.engine.onpremise.interop.swig -outdir ../java/fiftyone/devicedetection/hash/engine/onpremise/interop/swig -o Java_Hash_Engine.cpp hash_java.i
The IP Intelligence engine has RegenSwig.ps1 beside its interface file that
does the same.
The repository has one version, and every package is released with it. CI
sets the version on each package tree before a release and tags the commit
with the plain version, such as 4.5.127.
| Earlier repository | What it held |
|---|---|
| pipeline-java | The Pipeline API |
| device-detection-java | Device Detection |
| ip-intelligence-java | IP Intelligence |
| location-java | Location |
| device-detection-java-examples | Device Detection examples |
| ip-intelligence-java-examples | IP Intelligence examples |
The folders pipeline, device-detection, ip-intelligence, location and
the two example folders were brought in from the separate repositories
pipeline-java,
device-detection-java,
ip-intelligence-java,
location-java,
device-detection-java-examples
and
ip-intelligence-java-examples
with git subtree add, without --squash, so every commit keeps its original
SHA. The history of a file before the import is under its old path, so read it
from the imported commit, for example git log aff7c544 -- pom.xml for what is
now pipeline/pom.xml.