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?
- First of all, make sure you’ve created a Netbiscuits account and have logged in.
- If you’re all set there, then you need to contact our team to get your on-premise
- Next, copy your configuration code.
- Once copied, paste that code block into a
javax.servlet.ServletContextListener.contextInitializedimplementation. 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);
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
// 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");
Retrieving the Dynamic Device Data
This will use all the possible dynamic data – see the next example if you would like to exclude some of the sensors.
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
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
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.
// 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. Detection.updateDeviceData();
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. Detection.fetchDeviceData(); ... // 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
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!