API reference for the Device Detection service

Current version: 9.2

The Sitecore Device Detection module consists of the following assemblies:

  • Sitecore.CES.DeviceDetection contains the API that enables detection of devices and provides information on the device's parameters.

  • Sitecore.CES.DeviceDetection.Rules contains conditions that are used in Device Detection rules.

These assemblies enable you to use the following API references to further customize your Sitecore solution:

Sitecore.CES.DeviceDetection

This namespace contains the main Device Detection API classes.

Class name

DeviceInformationProviderBase

Description

This is an abstract base class for the device information provider. You need to derive from this class to implement your own device information provider.

Fields

  • DeviceCache

    Contains information about the device's cache instance.

Methods

  • DeviceInformation GetDeviceInformation(string userAgent)

    Gets device information from the cache for the userAgent. If the cache does not contain the required device information, it calls the DoGetDeviceInformation method and adds the response to the cache.

  • DeviceInformation DoGetDeviceInformation(string userAgent)

    Gets the device information based on a user agent string.

  • string GetExtendedProperty(string userAgent, string propertyName)

    Gets the device's property from the cache for the userAgent. If the cache does not contain the required device property, it calls the DoGetExtendedProperty method and adds the response to cache.

  • string DoGetExtendedProperty(string userAgent,string propertyName)

    Gets a device property from the device database, in the case where this property is not a part of the DeviceInformation class.

Properties

  • boolIsEnabled

    Determines whether the provider is enabled and is usable. Override this property if your provider can be disabled, for example if it requires a subscription to the default provider.

  • boolIsInitialized

    Determines whether the provider is initialized. Override this property if your provider can be initialized asynchronously, and the initialize method only starts the initialization process.

Class name

DeviceDetectionManager

Description

This is the static class that resolves device information based on a user agent string.

Methods

  • DeviceInformation GetDeviceInformation(string userAgent)

    Gets the device information based on the user agent string.

  • string GetExtendedProperty(string userAgent, string propertyName)

    Gets an extended property from the device database if it is not found in DeviceInformation.

  • boolCheckInitialization(TimeSpan timeout)

    Tries to initialize the provider and waits until the provider is either initialized or timeout is expired. The method returns true if the provider is initialized, otherwise it returns false.

  • boolCheckInitialization()

    Tries to initialize the provider and waits until the provider is either initialized or the default timeout has expired. See DeviceDetection.CheckInitializationTimeout. The method returns true when the provider is initialized, otherwise it returns false.

Properties

  • boolIsEnabled

    Indicates whether the device detection service and the provider are enabled in the configuration. This property is true if you have a valid license and DeviceDetectionEnabled = true in the config file.

  • boolIsReady

    Gets the value that indicates whether device detection is enabled, and that the provider is initialized.

Class name

DeviceDetectionManagerBase

Description

This class resolves device information based on a user agent string.

Methods

  • DeviceInformation GetDeviceInformation(string userAgent)

    Gets the device information based on the user agent string.

  • string GetExtendedProperty(string userAgent, string propertyName)

    Gets an extended property from the device database if it is not found in DeviceInformation.

  • boolCheckInitialization(TimeSpan timeout)

    Tries to initialize the provider and waits until the provider is either initialized or timeout is expired. The method returns true if the provider is initialized, otherwise it returns false.

  • boolCheckInitialization()

    Tries to initialize the provider and waits until the provider is either initialized or the default timeout has expired. See DeviceDetection.CheckInitializationTimeout. The method returns

    true when the provider is initialized, otherwise it returns false.

Properties

  • boolIsEnabled

    Indicates whether the device detection service and the provider are enabled in the configuration. This property is true if you have a valid license and DeviceDetectionEnabled = true in the config file.

  • boolIsReady

    Gets the value that indicates whether device detection is enabled, and that the provider is initialized.

Class name

DefaultDeviceDetectionManager

Description

This class is the default implementation of the service that resolves device information based on a user agent string.

Methods

  • DeviceInformation GetDeviceInformation(string userAgent)

    Gets the device information based on the user agent string.

  • string GetExtendedProperty(string userAgent, string propertyName)

    Gets an extended property from the device database if it is not found in DeviceInformation.

  • boolCheckInitialization(TimeSpan timeout)

    Tries to initialize the provider and waits until the provider is either initialized or timeout is expired. The method returns true if the provider is initialized, otherwise it returns false.

  • boolCheckInitialization()

    Tries to initialize the provider and waits until the provider is either initialized or the default timeout has expired. See DeviceDetection.CheckInitializationTimeout. The method returns true when the provider is initialized, otherwise it returns false.

Properties

  • boolIsEnabled

    Indicates whether the device detection service and the provider are enabled in the configuration. This property is true if you have a valid license and DeviceDetectionEnabled = true in the config file.

  • boolIsReady

    Gets the value that indicates whether device detection is enabled, and that the provider is initialized.

Class name

DeviceInformation

Description

This class contains basic information about a device.

Properties

  • Browser

    Contains the browser name and version.

  • BrowserCanJavaScript

    Specifies whether the browser supports JavaScript.

  • BrowserHtml5AudioCanAudio

    Specifies whether the browser supports HTML5 audio.

  • BrowserHtml5VideoCanVideo

    Specifies whether the browser supports HTML5 video.

  • CanTouchScreen

    Specifies whether the browser and the device are touch screen enabled.

  • DeviceIsSmartphone

    Specifies whether the device is a smartphone.

  • DeviceModelName

    Specifies the model name of the device.

  • DeviceOperatingSystemModel

    Specifies the model of the device's operating system.

  • DeviceOperatingSystemVendor

    Specifies the vendor of the device's operation system.

  • DeviceType

    Specifies the device type.

  • DeviceVendor

    Specifies the vendor of the device.

  • HardwareDisplayHeight

    Specifies the display height of the device. The value is 0 for a browser.

  • HardwareDisplayWidth

    Specifies the display width of the device. The value is 0 for a browser.

  • IsBot

    Specifies whether the device is, for example. a crawler, bot, robot, or spider.

Class name

DeviceDetectionServicesConfigurator

Description

This class represents the IServicesConfigurator for the Sitecore.CES.DeviceDetection assembly.

Methods

  • void Configure(IServiceCollection serviceCollection)

    Registers the Device Detection services.

Enumeration name

DeviceType

Description

This enumeration represents a type of device.

Members

  • Other

  • MobilePhone

  • MobileConsole

  • EReader

  • Tablet

  • MediaPlayer

  • SettopBox

  • Camera

  • Bot

    Note

    The enum DeviceType.Bot is now obsolete. To check robots, use the following code instead:

    RequestResponse
    var isRobot = DeviceDetectionManager.GetExtendedProperty(HttpContext.Current.Request.UserAgent, "IsCrawler");
  • WearableComputer

  • Computer

Sitecore.CES.DeviceDetection.Cache

This namespace contains the Device Detection cache class.

Note

The cache name is DeviceDetection

Class name

DeviceDetectionCache

Description

This class implements a cache for device information and extended properties.

Methods

  • DeviceInformationGetDeviceInformation(string userAgent)

    Gets device information from cache

  • string GetExtendedProperty(string userAgent, string propertyName)

    Gets an extended property from cache

  • AddDeviceInformation(string userAgent and DeviceInformation deviceInfo)

    Adds device information to the cache

  • AddExtendedProperty(string userAgentand string propertyNameand string value)

    Adds an extended property to the cache

Sitecore.CES.DeviceDetection.Configuration

This namespace contains the class that provides access to the settings of the Device Detection module.

Class name

DeviceDetectionSettings

Description

This class provides access to the settings of the Device Detection module.

Properties

  • Enabled

    Specifies whether the Device Detection module is enabled.

  • DatabaseUpdateCheckInterval

    Specifies how frequently database update checks are performed.

  • FailDatabaseCheckInterval

    Specifies how frequently the database tries to reinitialize in the case of an initialize fail.

  • DeviceDetectionCacheSize

    Specifies the Device Detection cache size.

  • DeviceDetectionServiceName

    Specifies the name of the Device Detection service.

  • DatabasePath

    Specifies the path where the device databases are stored.

Sitecore.CES.DeviceDetection.Data

This namespace contains the classes for communicating with the Sitecore cloud service.

Class name

KeyInfo

Description

This class specifies information about the Device Detection database decryption key.

Properties

  • Key

    Specifies the decryption key.

  • RecommendedCacheTimeSpan

    Make recommendations for future cache timespans.

Class name

UpdateInfo

Description

This class contains information about database updates.

Properties

  • DatabaseLink

    Specifies the link for an encrypted database file.

  • DatabaseVersion

    Specifies the database version

Sitecore.CES.DeviceDetection.Diagnostics.PerformanceCounters

This namespace contains the Device Detection performance counter classes.

Class name

DeviceDetectionCount

Description

This is a static class that provides access to the Device Detection performance counters.

Properties

  • RequestsTotal

    Counts the total number of requests for device information

  • CacheHits

    Counts the number of cache hits

  • CacheMisses

    Counts the number of cache misses

  • AverageResolveTime

    Counts the average time it takes to resolve a request to the database.

Sitecore.CES.DeviceDetection.Diagnostics.Exceptions

This namespace contains the Device Detection exception class.

Class name

DeviceDetectionException

Description

This class represents a Device Detection exception. The API throws this exception when there is either no subscription for the Device Detection service or the provider is not initialized or it is disabled.

Sitecore.CES.DeviceDetection.Providers.FiftyOneDegrees

This namespace implements the default provider.

Class name

DeviceInformationProvider51Degrees

Description

This class implements the DeviceInformationProviderBase and ensures the database is updated.

Methods

  • DeviceInformation GetDeviceInformation(string userAgent)

    Checks the license and calls the GetDeviceInformation method from the base class

  • DeviceInformation DoGetDeviceInformation(string userAgent)

    Gets the information of the device, based on a user agent string from a database.

  • string GetExtendedProperty(string userAgent, string propertyName)

    Checks the license and calls the GetExtendedProperty method from the base class

  • string DoGetExtendedProperty(string userAgent, string propertyName)

    Gets a device property from the device database, in case the device property is not included in DeviceInformation

  • Initialize(string name, NameValueCollection config)

    Initializes the provider and starts update monitoring

Sitecore.CES.DeviceDetection.Rules

This namespace contains the helper interface for the condition classes.

Class name

IRuleDeviceInformationManager

Description

This interface is used to get device information for rules.

Methods

  • DeviceInformation GetDeviceInformation(RuleContext ruleContext)

    Gets the device information from context.

  • string GetExtendedProperty( RuleContext ruleContext, string propertyName)

    Gets the extended property from context.

Sitecore.CES.DeviceDetection.Rules.Conditions

This namespace contains the condition classes.

Class name

DeviceBoolConditionBase

Description

This is an abstract class for creating rules with Boolean conditions.

Methods

  • boolExecute(T ruleContext)

    Gets information about the device from the RuleDeviceInformationManager and calls the GetDeviceProperty method

  • boolGetDeviceProperty(DeviceInformation deviceInformation)

    Gets the device's Boolean property

Class name

DeviceBrowserCanJavaScriptCondition

Description

This class implements a rule that checks whether the browser can execute JavaScript.

Method

  • boolGetDeviceProperty(DeviceInformation deviceInformation)

    Returns the BrowserCanJavaScript property from Device Information.

Class name

DeviceBrowserCondition

Description

This class implements a rule which specifies if the browser name and version meet the condition.

Method

  • string GetDeviceProperty(DeviceInformation deviceInformation)

    Returns the Browser property from Device Information.

Class name

DeviceBrowserHtml5AudioCanAudioCondition

Description

This class implements a rule which defines whether the browser can play HTML5 audio.

Method

  • boolGetDeviceProperty(DeviceInformation deviceInformation)

    Returns the BrowserHtml5AudioCanAudio property from Device Information.

Class name

DeviceBrowserHtml5VideoCanVideoCondition

Description

This class implements a rule which defines whether the browser can play HTML5 video.

Method

  • boolGetDeviceProperty(DeviceInformation deviceInformation)

    Returns the BrowserHtml5VideoCanVideo property from Device Information.

Class name

DeviceCanTouchScreenCondition

Description

This class implements a rule which defines whether the device and browser support touch screen.

Method

  • boolGetDeviceProperty(DeviceInformation deviceInformation)

    Returns the CanTouchScreen property from Device Information.

Class name

DeviceModelNameCondition

Description

This class implements a rule which defines whether the browser model name meets the condition.

Method

  • string GetDeviceProperty(DeviceInformation deviceInformation)

    Returns the DeviceModelName property from Device Information.

Class name

DeviceHardwareDisplayHeightCondition

Description

This class implements a rule which defines whether the device height meets the condition. Note that this does not work correctly for a browser.

Method

  • int GetDeviceProperty(DeviceInformation deviceInformation)

    Returns the HardwareDisplayHeight property from Device Information.

Class name

DeviceHardwareDisplayWidthCondition

Description

This class implements a rule which defines whether the device width meets the condition. Note that this does not work correctly for a browser.

Method

  • int GetDeviceProperty(DeviceInformation deviceInformation)

    Returns the HardwareDisplayWidth property from Device Information.

Class name

DeviceIntegerConditionBase

Description

This is an abstract class for creating rules with an integer condition.

Method

  • boolExecute(T ruleContext)

    Gets information about the device from the RuleDeviceInformationManager and calls the GetDeviceProperty method.

  • int GetDeviceProperty(DeviceInformation deviceInformation)

    Gets the device's Integer property.

Class name

DeviceOperatingSystemModelCondition

Description

This class implements a rule which defines whether the device operating system model meets the condition.

Method

  • string GetDeviceProperty(DeviceInformation deviceInformation)

    Returns the DeviceModelName property from Device Information.

Class name

DeviceOperatingSystemVendorCondition

Description

This class implements a rule which defines whether the vendor of the operating system meets the condition.

Method

  • string GetDeviceProperty(DeviceInformation deviceInformation)

    Returns the DeviceOperatingSystemVendor property from Device Information.

Class name

DevicePropertyCondition

Description

This class implements a rule which defines whether the extended property meets the condition.

Method

  • boolExecute(T ruleContext)

    Gets the extended property from the RuleDeviceInformationManager and compares it with the value of the condition.

Properties

  • Value

    The value of the condition

  • PropertyName

    The extended property name.

Class name

DeviceStringConditionBase

Description

This is an abstract class that you use to create rules with a String condition.

Method

  • boolExecute(T ruleContext)

    Gets the device information from the RuleDeviceInformationManager and calls the GetDeviceProperty method.

  • string GetDeviceProperty(DeviceInformation deviceInformation)

    Gets the device string property.

Properties

  • Value

    The value of the condition.

Class name

DeviceTypeCondition

Description

This class implements a rule that checks whether the device type meets the condition.

Method

  • boolExecute(T ruleContext)

    Gets information about the device from the RuleDeviceInformationManager and compares it with the condition value.

Properties

  • Value

    The value of the condition.

Class name

DeviceVendorCondition

Description

This class implements a rule that defines whether the device vendor meets the condition.

Method

  • string GetDeviceProperty(DeviceInformation deviceInformation)

    Returns the DeviceVendor property from Device Information

Class name

DeviceTypeIds - Obsolete, use Sitecore.ContentTesting.Rules.Conditions.DeviceTypeIDs instead.

Description

This class comes from Sitecore.ContentTesting and contains the item IDs that corresponds to the device type.

Constants

  • MobilePhone

  • FeaturePhone

  • Smartphone

  • MobileConsole

  • EReader

  • Tablet

  • MediaPlayer

  • SettopBox

  • Camera

  • Bot

  • WearableComputer

  • Computer

  • Other

Do you have some feedback for us?

If you have suggestions for improving this article,