Knowledge base


How does it work?

Installing the on-premise option is slightly more involved than simply using the Netbiscuits Device Detection server, but for large traffic sites, it can be the most efficient setup. We provide technical support for your installation (contact us). However, this guide describes the steps, so you have some idea what is involved. Setup requires the download of the Netbiscuits Device Database onto your own servers, but this is all dealt with in a few lines of code. Below are instructions and code examples for getting an on-premise solution set up.

A typical Java On-Premise Device Detection configuration code block will look something like this:

int cacheSize = 0;
String exportPath = "/tmp/onpremise.db";
String shortCode = "[account_name]";
String detectionToken = "[token]";
String staticProfile = "[profile]";
Detection.initialize(cacheSize, exportPath, shortCode, detectionToken, staticProfile);

With the Java on-premise client configured, the following events happen when a user’s browser requests a page from your website:

  • Your server requests the Device Detection profile from the Netbiscuits Device Detection server installed on your server
  • The Device Detection server runs a series of tests to identify the user’s device
  • A collection of parameters and values is created and returned to your server in JSON format
  • Device Detection can also (optionally) gather dynamic data within the user’s browser, like current Bandwidth and Geolocation – Learn more about using using Dynamic Parameters
  • Once complete, the Device Detection object can be used to customize the user’s experience for the exact device they are using

How can I use Java Device Detection?

  1. First of all, make sure you’ve created a Netbiscuits account and have logged in.
  2. If you’re all set there, then you need to contact our team to get your on-premise .jar file.
  3. Next, copy your configuration code.
  4. Once copied, paste that code block into a javax.servlet.ServletContextListener.contextInitialized implementation. The exact configuration code you copied will be broken down and explained in detail below.


This section of the code initializes the library, sets a 0 size cache and adds your tokens and shortcode (which will have been automatically added from your my.netbiscuits details). This section of the code should go into a javax.servlet.ServletContextListener.contextInitialized implementation. This will ensure the initialization step is only performed once.

// Device Information can be cached, specify the maximum number of cache
// entries (by User-Agent), use '0' to disable the cache
int cacheSize = 0;
// file system location where to which the device data export and the geolocation database will be downloaded
String exportPath = "/tmp/onpremise.db";
// the account shortcode will have been added automatically.
String shortCode = "[account_name]";
// the detection token will have been added automatically.
String detectionToken = "[token]";
// in order to use a different static profile, create one via my.netbiscuits
String staticProfile = "[profile]";
Detection.initialize(cacheSize, exportPath, shortCode, detectionToken, staticProfile);

Default Setup

Get Device Data

Once the initialization is complete, you can set up an instance of the detection method. After you’ve done this, you need to take the user agent from the request and pass it to your DeviceInformation object.

// get a new Detection instance
Detection detection = Detection.createInstance();
// methods for UserAgent and HeaderMap are available
DeviceInformation deviceInfo = detection.detect(HttpServletRequest);
// e.g. check device model name via Parameter List
String modelname = deviceInfo.getString("devicemodelname");

Get JavaScript for using Device Data Client Side

If you require static parameters on the client-side, you will also need to add the JavaScript into your website using the same method.

// convenience methods for HttpServletRequest and HeaderMap are available
DeviceInformation deviceInfo = detection.detect("user agent");
// inject JavaScript into your website, retrieve device data via 'dcs.get(parametername)'
String javaScript = deviceInfo.getJavaScript();

Retrieving the Dynamic Device Data

If you would like to retrieve dynamic parameters, you will also need to set up your JavaScript token. This can be done with code similar to that used in the Detection Code. The JavaScript token is included in the code you copied above.

This will use all the possible dynamic data – see the next example if you would like to exclude some of the sensors.

// get JavaScript token from
String javaScriptToken = "[token]";
// inject JavaScript into your website, use similar to the
// DetectionCode (required part:'dcs.dynamic.init(configurationobject)')
String dynamicDetectionScript = detection.getDynamicDetectionScript (javaScriptToken);
String javaScript = deviceInfo.getJavaScript();

Restricting sensors for Dynamic Device Data and using Personas

If you would like to exclude some of the sensors (for latency reasons, for example, or they are simply not required), then you can do so by retrieving all the available sensors into a set, removing those you do not need, and passing the set into the DeviceInformation method.

If you would like to use Custom Clusters, either your own or those supplied by Netbiscuits (for instance, Personas), then these must also be added here and passed to the DeviceInformation method.

String javaScriptToken = "[token]";
Set<String> sensors = Detection.getAvailableSensors();
// exclude bandwidth information
// exclude geolocation
Set<String> clusterNames = new HashSet<String>();
// choose names from Custom Cluster Builder
DeviceInformation deviceInfo = detection.getDynamicDetectionScript(javaScriptToken, sensors, clusterNames);
String javaScript = deviceInfo.getJavaScript();

Updating Device Data

It is important to make sure that the device data is kept updated, and this can be done in two ways: 1) either you do a one time ‘Hot Swap’ or 2) you download the new device data in the background and update it at a later time. The two implementations are essentially the same, with the difference that the Hot Swap method will immediately restart your application, so the new device database will be used immediately.

When fetching the device data and updating later, the implementation is not updated until your application is restarted.

If your application will be restarted regularly, the second option is recommended.

Hot swap

// A backup of the current device data is created and the
// new device data is fetched from Netbiscuits and stored on disk.
// Afterwards, the outdated in-memory data is replaced by the updated data.

Fetch Device Data and Update Later

// a backup of the current device data is created and the new device
// data is fetched from Netbiscuits and stored on disk.
// re-initialize the on-premise client with the new device data
Detection.initialize(cacheSize, exportPath, shortCode, detectionToken, staticProfile);

Shutting down the detection instance

The Device Detection instance must be shut down after usage.


This section of the code should be added to a javax.servlet.ServletContextListener.contextDestroyed implementation.

We hope this has helped you understand Netbiscuits On-Premise Java Device Detection. To get help with installation or to ask any questions, please contact us.

Or if you’re ready for the next step, find out about all the Device Detection Parameters you can build into your website!

Learn more about Device Detection Parameters

YouTube aktivieren?

Auf dieser Seite gibt es mind. ein YouTube Video. Cookies für diese Website wurden abgelehnt. Dadurch können keine YouTube Videos mehr angezeigt werden, weil YouTube ohne Cookies und Tracking Mechanismen nicht funktioniert. Willst du YouTube dennoch freischalten?