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 setup.
A typical .Net On-Premise Device Detection configuration code block will look something like this:
var cacheSize = 0; var generateClientSideScripts = true; var databaseFile = "C:\tmp\onpremise.db"; var shortCode = "[account_name]"; var detectionToken = "[token]"; var geolocationFile = "C:\tmp\geolocation.mmdb"; var geolocationService = new IpGeoLocationService(geolocationFile); var detection = Detection.Initialize( cacheSize: cacheSize, databaseFile: databaseFile, // Alternatively provide a System.IO.Stream here databasePassword: detectionToken, generateClientSideScripts: generateClientSideScripts, accountCode: shortCode, geolocationService: geolocationService);
With the .Net 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 the .Net Device Detection?
- First of all, you will need to be working with .Net Framework 4.5 or higher.
- 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 file.
- Next, copy your configuration code.
- 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). Initialize the detection as shown below before first use, and re-use the returned detection object.
// Device Information can be cached, specify the maximum number of cache // entries (by User-Agent), use '0' to disable the cache var cacheSize = 0; // Generating the client side scripts can be optionally disabled if not required, which may improve detection speed. var generateClientSideScripts = true; // file system location where the OnPremise DeviceDB is located var databaseFile = "C:\tmp\onpremise.db"; // the account shortcode will have been added automatically. var shortCode = "[account_name]"; // the detection token will have been added automatically. var detectionToken = "[token]"; // Optional Geolocation module // File system location where the Geolocation database is located var geolocationFile = "C:\tmp\geolocation.mmdb"; var geolocationService = new IpGeoLocationService(geolocationFile); // Initialize a new Detection instance and reuse it until no longer required var detection = Detection.Initialize( cacheSize: cacheSize, databaseFile: databaseFile, // Alternatively provide a System.IO.Stream here databasePassword: detectionToken, generateClientSideScripts: generateClientSideScripts, accountCode: shortCode, geolocationService: geolocationService);
Get Device Data
After the code is implemented, you need to take the user agent from the request and pass it to a
// methods for UserAgent string and Headers are available var deviceInfo = detection.Detect(HttpRequestBase); // e.g. check device model name via Parameter List var modelname = deviceInfo.GetStringValue("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.
The second may be more useful, because it takes either the
HttpRequestBase, Headers or User-Agent, and the
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 detection 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 detection method.
Updating Device Data
It is important to make sure that the device data is kept updated, and this can be done using the
DeviceDataDownloader. You can download the new database version using the same filename as an already existing database. In this case a backup will be created, and if the download fails, the backup will be restored as well. Alternatively, you can provide a custom new name for every download.
To minimize downtimes related to database updates, it is possible to use an already initialized Detection instance and at the same time initialize a new instance with a different device database. After successful initialization, the detection instances can be exchanged, and the no longer used instance should be disposed (see next section) to save resources.
See the following code sample for initialization and download using
// Optional: Provide a location where to download the device database (a backup will be created, if file exists) var databaseFile = "C:\tmp\onpremise.db"; // Optional: Provide a location where to download the geolocation database (a backup will be created, if file exists) var geolocationFile = "C:\tmp\geolocation.mmdb"; // the account shortcode will have been added automatically. var shortCode = "[account_name]"; // the detection token will used for download authorization and to encrypt the database on the Netbiscuits servers. var detectionToken = "[token]"; // in order to use a different static profile, create one via my.netbiscuits var staticProfileName = "[profile]"; // Optional DeviceDataDownloader var deviceDataDownloader = new DeviceDataDownloader(databaseFile, geolocationFile, shortCode, detectionToken, staticProfileName); // Perform the download(s) deviceDataDownloader.Download();
Shutting down the detection instance
The Detection class implements the IDisposable interface and should be disposed of when it is no longer required (e.g. application shutdown or replacement with a newer database version). Depending on the architecture of your application, this can be also achieved by using a
<code>using</code> block, but most likely this must be done manually:
We hope this has helped you understand Netbiscuits On-Premise .Net 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!