Check out the latest documentation.

What's Covered

This tutorial illustrates how to access match metrics. The following is covered:

  • How to retrieve device Id.
  • How to retrieve match method.
  • How to retrieve difference.
  • How to retrieve rank.

Code and Explanation

Match metrics example of using 51Degrees device detection. The example shows how to:

  1. Set the data set for the 51Degrees detector

    												
    string fileName = args[0];
    DataSet dataSet = StreamFactory.Create(fileName, false);
    
    												

  • Instantiate the 51Degrees device detection provider with these settings

    									
    Provider provider = new Provider(dataSet);
    
    									
  • Produce a match for a single HTTP User-Agent

    									
    match = provider.Match(userAgent);
    
    									
  • Obtain device Id: consists of four components separated by a hyphen symbol: Hardware-Platform-Browser-IsCrawler where each Component represents an ID of the corresponding Profile.

    									
    deviceId = match.DeviceId;
    
    									
  • Obtain match method: provides information about the algorithm that was used to perform detection for a particular User-Agent. For more information on what each method means please see: How device detection works

    									method = match.Method;
    									
  • Obtain difference: used when detection method is not Exact or None. This is an integer value and the larger the value the less confident the detector is in this result.

    									difference = match.Difference;
    									
  • Obtain signature rank: an integer value that indicates how popular the device is. The lower the rank the more popular the signature.

    									rank =  match.Signature.Rank;
    									
    This tutorial assumes you are building this from within the 51Degrees Visual Studio solution. Running the executable produced inside Visual Studio will ensure all the command line arguments are preset correctly. If you are running outside of Visual Studio, make sure to add the path to a 51Degrees data file as an argument.

    Full Source File
    												
            public static void Run(string fileName)
            {
                // DataSet is the object used to interact with the data file.
                // StreamFactory creates Dataset with pool of binary readers to 
                // perform device lookup using file on disk.
                DataSet dataSet = StreamFactory.Create(fileName, false);
    
                // Provides access to device detection functions.
                Provider provider = new Provider(dataSet);
    
                // Used to store and access detection results.
                Match match;
    
                // User-Agent string of an iPhone mobile device.
                string mobileUserAgent = ("Mozilla/5.0 (iPhone; CPU iPhone " +
                    "OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like " +
                    "Gecko) 'Version/7.0 Mobile/11D167 Safari/9537.53");
    
                // User-Agent string of Firefox Web browser version 41 on desktop.
                string desktopUserAgent = ("Mozilla/5.0 (Windows NT 6.3; " +
                    "WOW64; rv:41.0) Gecko/20100101 Firefox/41.0");
    
                // User-Agent string of a MediaHub device.
                string mediaHubUserAgent = ("Mozilla/5.0 (Linux; Android " +
                    "4.4.2; X7 Quad Core Build/KOT49H) AppleWebKit/537.36 " +
                    "(KHTML, like Gecko) Version/4.0 Chrome/30.0.0.0 " +
                    "Safari/537.36");
    
                Console.WriteLine("Starting Match Metrics Example.");
    
                // Carries out a match for a mobile User-Agent.
                Console.WriteLine("*** Mobile ***");
                match = provider.Match(mobileUserAgent);
                OutputMatchMetrics(match);
    
                // Carries out a match for a desktop User-Agent.
                Console.WriteLine("*** Desktop ***");
                match = provider.Match(desktopUserAgent);
                OutputMatchMetrics(match);
    
                // Carries out a match for a MediaHub User-Agent.
                Console.WriteLine("*** MediaHub ***");
                match = provider.Match(mediaHubUserAgent);
                OutputMatchMetrics(match);
    
                // Finally close the dataset, releasing resources and file locks.
                dataSet.Dispose();
            }
    
            /// <summary>
            /// Prints match metrics associated with a given match object.
            /// </summary>
            /// <param name="match">a Match object</param>
            public static void OutputMatchMetrics(Match match)
            {
                Console.WriteLine();
                Console.WriteLine("Target User-Agent:");
                Console.WriteLine(match.TargetUserAgent);
                Console.WriteLine();
                Console.WriteLine("Relevant Sub Strings:");
                Console.WriteLine(match.UserAgent);
                Console.WriteLine();
                Console.WriteLine("Metrics:");
                Console.WriteLine("   Device Id: " + match.DeviceId);
                Console.WriteLine("   Method: " + match.Method);
                Console.WriteLine("   Difference: " + match.Difference);
                Console.WriteLine("   Rank: " + match.Signature.Rank);
                Console.WriteLine();
            }
    
    
    												
    Full Source File

  • Summary

    Match metrics is an additional piece of information about each match result. It can help developers spot fake User-Agents and determine the general level of confidence the detector has in the current detection results.

    Device metrics consists of four parts: device Id, detection method, difference and rank.

    Device Id is composed of four components, each represented as a number and separated by the hyphen symbol. Numbers correspond to profile IDs the detector has selected for that particular component. The four components are: hardware, software, browser and crawler. For more information please see the 51Degrees Data Model .

    The detection method provides information on what algorithm was used for this particular detection and difference indicates by how much the provided User-Agent is different to the best signatures found in the data file. The larger the number the less confident the detector is. Difference for the 'exact' method is always zero. Difference for the 'none' detection method is irrelevant. For more information see the How Device Detection Works page.

    Rank value tells you how popular the identified device is. The lower the value the more popular the device. Popularity is derived by 51Degrees based on our observed usage level.

    Other uses for match metrics include:

    • Ranking devices by popularity. Best used in conjunction with other tutorials to rank the results based on the general device popularity.
    • Storing device Id for analytics instead of individual profiles.

    The Lite data file contains 446,634 device combinations, whilst Premium and Enterprise contain 940,018 and 1,407,838 device combinations respectively. A larger set of device combinations leads to the 'exact' detection method being used more frequently and the rank providing a more accurate value.