Knowledge base

.NET

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?

  1. First of all, you will need to be working with .Net Framework 4.5 or higher.
  2. Make sure you’ve created a Netbiscuits account and have logged in.
  3. If you’re all set there, then you need to contact our team to get your on-premise file.
  4. Next, copy your configuration code.
  5. The exact configuration code you copied will be broken down and explained in detail below.

Initialization

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);

Default Setup

Get Device Data

After the code is implemented, you need to take the user agent from the request and pass it to a DeviceInformation object.

// 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");

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. You can get this JavaScript snippet using the detection method:

// convenience methods for HttpRequestBase and Headers are available
var deviceInfo = detection.Detect("user agent");
// inject JavaScript into your website, retrieve device data via 'dcs.get(parametername)'
var 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.

There are two ways to collect the required JavaScript to retrieve dynamic device data. The first will return the JavaScript as required but will not return any of the static parameters and makes no values available on the server-side:

var dynamicDetectionScript = detection.GetDynamicDetectionScript(javascriptToken);

The second may be more useful, because it takes either the HttpRequestBase, Headers or User-Agent, and the javascriptToken as mandatory, and a set of sensors and clusters as optional. This method will return the DeviceInformation object that provides the static parameters server-side, plus the JavaScript including the dynamic detection code:

// get JavaScript token from my.netbiscuits
var javaScriptToken = "[token]";
// inject JavaScript into your website and use similar to the
// DetectionCode (required part:'dcs.dynamic.init(configurationobject)')
var deviceInfo = detection.DetectAndGetDynamicDetectionScript("user agent", javaScriptToken, sensors, clusterNames);
var 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 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.

var javaScriptToken = "[token]";
var sensors = detection.GetAvailableSensors();
// exclude bandwidth information
sensors.Remove("bandwidth");
// exclude geolocation
sensors.Remove("geolocation");
var clusterNames = new HashSet<String>();
// choose names from Custom Cluster Builder
clusterNames.Add("time_personas");
var deviceInfo = detection.DetectAndGetDynamicDetectionScript(HttpRequestBase/Headers/UserAgent, javaScriptToken, sensors, clusterNames);
var javaScript = deviceInfo.GetJavascript();

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 DeviceDataDownloader.

// 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:

detection.Dispose();

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!

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?