• About Us
  • Blog
  • Basket
  • Account
  • Sign In
  •  

Java API

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

Getting started example of using 51Degrees device detection match metrics information. The example shows how to;
  1. Instantiate 51Degrees detection provider
          provider = new Provider(StreamFactory.create(
          Shared.getLitePatternV32(), false));
      
  2. Pass in a single HTTP User-Agent header
          Match match = provider.match(userAgent);
      
  3. Obtain device Id: consists of four components separated by a hyphen symbol: Hardware-Platform-Browser-IsCrawler where each Component is represented an ID of the corresponding Profile.
          match.getDeviceId();
      
  4. Retrieve 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
          match.getMethod();
      
  5. Get 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.
          match.getDifference();
      
  6. Retrieve signature rank: an integer value that indicates how popular the device is. The lower the rank the more popular the signature.
          match.getSignature().getRank();
      


Full Source File
    // Device detection provider which takes User-Agents and returns matches.
    protected final Provider provider;
    
    // User-Agent string of a iPhone mobile device.
    protected final 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 of version 41 used on desktop.
    protected final 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.
    protected final 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";

    /**
     * Initialises the device detection Provider with the included Lite data
     * file. For more data see: 
     * <a href="https://51degrees.com/compare-data-options">compare data options
     * </a>
     * 
     * @throws IOException can be thrown if there is a problem reading from the 
     * provided data file.
     */
    public MatchMetrics() throws IOException {
        provider = new Provider(StreamFactory.create(
                Shared.getLitePatternV32(), true));
    }
    
    /**
     * Extracts MatchMethods enumeration value from the {@link Match} object.
     * The extracted value represents the algorithm used to perform this
     * detection.
     * <p>
     * {@code Match} object must be created and populated by invoking the 
     * <code>provider.match(userAgentString)</code> before supplying to this 
     * method.
     * 
     * @param match Match object containing detection results, not null.
     * @return MatchMethods enumeration used for this detection.
     */
    public MatchMethods getMethod(Match match) {
        if (match == null) {
            throw new IllegalArgumentException();
        }
        return match.getMethod();
    }
    
    /**
     * Extract the difference value from the {@link Match} object provided.
     * Difference represents the level of confidence the detector has in the 
     * accuracy of the current detection. The higher the number the less 
     * confident the detector is.
     * <p>
     * Difference value is only relevant to Nearest, Closest and Numeric 
     * methods. Exact method will always have a value of zero. Difference is 
     * irrelevant to None as the User-Agent that yielded this result is almost 
     * certainly fake.
     * <p>
     * {@code Match} object must be created and populated by invoking the 
     * <code>provider.match(userAgentString)</code> before supplying to this 
     * method.
     * 
     * @param match Match object containing detection results, not null.
     * @return integer value of difference indicating the level of confidence 
     * the detector has in the current match results.
     */
    public int getDifference(Match match) {
        if (match == null) {
            throw new IllegalArgumentException();
        }
        return match.getDifference();
    }
    
    /**
     * Extracts the signature rank from the {@link Match} object provided.
     * Signature rank indicates the relative level of popularity of the given 
     * signature. The lower the value the more popular the requesting device is.
     * <p>
     * Popularity is determined by 51Degrees and is based on our statistics.
     * <p>
     * {@code Match} object must be created and populated by invoking the 
     * <code>provider.match(userAgentString)</code> before supplying to this 
     * method.
     * 
     * @param match Match object containing detection results, not null.
     * @return integer representing the popularity of the matched device. The 
     * lower the number the more popular device is.
     * @throws IOException if there is a problem accessing the data file.
     */
    public int getRank(Match match) throws IOException {
        if (match == null) {
            throw new IllegalArgumentException();
        }
        return match.getSignature().getRank();
    }
    
    /**
     * Device ID is a string of four numeric components separated by hyphen.
     * A relevant profile is picked by the detector for each of the following 
     * components: Hardware-Platform-Browser-IsCrawler.
     * 
     * @param match Match object containing detection results, not null.
     * @return String with device ID consisting of four profile IDs.
     * @throws IOException if there is a problem accessing the data file.
     */
    public String getDeviceId(Match match) throws IOException {
        if (match == null) {
            throw new IllegalArgumentException();
        }
        return match.getDeviceId();
    }
    
    /**
     * Main entry point for this example. For each of the User-Agents defined 
     * in this class: 
     * <ol>
     * <li>performs detection; 
     * <li>stores detection information in a {@link Match} object;
     * <li>Each {@code Match} object is then passed to one of the relevant 
     * methods to retrieve match metrics information, i.e.: 
     * {@link #getDeviceId} is invoked to return an Id string.
     * </ol>
     * 
     * @param args command line arguments, not used.
     * @throws IOException if there is a problem accessing the data file. 
     */
    public static void main(String[] args) throws IOException {
        MatchMetrics gs = new MatchMetrics();
        Match match;
        try {
            // Display metrics for mobile User-Agent.
            match = gs.provider.match(gs.mobileUserAgent);
            System.out.println("User-Agent: "+gs.mobileUserAgent);
            System.out.println("Id: "+gs.getDeviceId(match));
            System.out.println("Detection method: "+gs.getMethod(match));
            System.out.println("Difference: "+gs.getDifference(match));
            System.out.println("Rank: "+gs.getRank(match));
            // Display metrics for desktop User-Agent.
            match = gs.provider.match(gs.desktopUserAgent);
            System.out.println("User-Agent: "+gs.desktopUserAgent);
            System.out.println("Id: "+gs.getDeviceId(match));
            System.out.println("Detection method: "+gs.getMethod(match));
            System.out.println("Difference: "+gs.getDifference(match));
            System.out.println("Rank: "+gs.getRank(match));
            // Display metrics for mediahub User-Agent.
            match = gs.provider.match(gs.mediaHubUserAgent);
            System.out.println("User-Agent: "+gs.mediaHubUserAgent);
            System.out.println("Id: "+gs.getDeviceId(match));
            System.out.println("Detection method: "+gs.getMethod(match));
            System.out.println("Difference: "+gs.getDifference(match));
            System.out.println("Rank: "+gs.getRank(match));
        } finally {
            gs.close();
        }
    }
    
    /**
     * Closes the {@link fiftyone.mobile.detection.Dataset} by releasing data 
     * file readers and freeing the data file from locks. This method should 
     * only be used when the {@code Dataset} is no longer required, i.e. when 
     * device detection functionality is no longer required, or the data file 
     * needs to be freed.
     * 
     * @throws IOException if there is a problem accessing the data file.
     */
    @Override
    public void close() throws IOException {
        provider.dataSet.close();
    }

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 132,765 device combinations, whilst Premium and Enterprise contain 345,682 and 515,728 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.