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

Java API

What's Covered

This tutorial illustrates how to return a match for a Device Id. It shows how to first get the Device Id from a match, then get a match for that Device Id and return the value of the IsMobile property. This can be useful to look at devices that have already been matched at a previous date.

Code and Explanation

Example shows how to use an existing 51Degrees deviceId to obtain a Match object with relevant properties and values.

Example illustrates:

  • Loading a Provider from a Disk-based (Stream) Pattern Dataset
          provider = new Provider(StreamFactory.create
          (Shared.getLitePatternV32(), false));
      
  • Matching a User-Agent string header value
          provider.match(mobileUserAgent);
      
  • Using the match object to retrieve and store deviceId
          Match matchFromUA;
      

    as a string:

          matchFromUA.getDeviceId();
      

    as byte array:

          matchFromUA.getDeviceIdAsByteArray();
      

    as list of profile IDs:

          for (Profile profile : matchFromUA.getProfiles()) {
      
  • Creating a match object from deviceId
          device.matchForDeviceIdArray(deviceIdByteArray);
      
          device.matchForDeviceIdString(deviceIdString);
      
          device.matchForDeviceIdList(deviceIdList);
      

At the end a short console message will be printed containing a hash code of the object, deviceId and the value for the IsMobile property. Notice that all three objects are different as demonstrated by hash value but have the same deviceId and value for the IsMobile property.

Storing deviceId as opposed to the individual properties is a much more efficient way of retaining device information for future use. Byte array is the most efficient of the three options demonstrated as it only requires enough space to store the number of integers corresponding to the number of profiles (one profile per component).



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";
    
    /**
     * Creates new provider object with the Stream dataset.
     * @throws IOException if there was a problem accessing the data file.
     */
    public MatchForDeviceId() throws IOException {
        provider = new Provider(StreamFactory.create(
                Shared.getLitePatternV32(), false));
    }
    
    /**
     * Performs a match of the pre-defined User-Agent to retrieve Id, then 
     * shows how to use the Id to get a Match object. The Id can be stored as a 
     * byte array, string or a list of integers corresponding to profiles.
     * <p>
     * Three match objects with different references but same deviceId and 
     * IsMobile values are generated to demonstrate that all three methods of 
     * storing deviceId produce the same result.
     * @param args command line arguments.
     * @throws IOException if there was a problem accessing data file.
     */
    public static void main(String[] args) throws IOException {
        MatchForDeviceId device = new MatchForDeviceId();
        // Get deviceId for some User-Agent.
        Match matchFromUA = device.matchForUserAgent(device.mobileUserAgent);
        // Store for future use.
        String deviceIdString = matchFromUA.getDeviceId();
        byte[] deviceIdByteArray = matchFromUA.getDeviceIdAsByteArray();
        ArrayList<Integer> deviceIdList = new ArrayList<Integer>();
        for (Profile profile : matchFromUA.getProfiles()) {
            deviceIdList.add(profile.profileId);
        }
        // Some time has passed. Get match for each of the storage methods.
        Match matchFromByteArray = device.matchForDeviceIdArray(deviceIdByteArray);
        Match matchFromIdString = device.matchForDeviceIdString(deviceIdString);
        Match matchFromIdList = device.matchForDeviceIdList(deviceIdList);
        
        System.out.println("Match object: " +
                System.identityHashCode(matchFromByteArray) + 
                " created from deviceId as byte array. " + 
                "deviceId: " + matchFromByteArray.getDeviceId() + 
                "IsMobile: " + matchFromByteArray.getValues("IsMobile"));
        
        System.out.println("Match object: " +
                System.identityHashCode(matchFromIdString) + 
                " created from deviceId as string. " + 
                "deviceId: " + matchFromIdString.getDeviceId() + 
                " IsMobile: " + matchFromIdString.getValues("IsMobile"));
        
        System.out.println("Match object: " +
                System.identityHashCode(matchFromIdList) + 
                " created from deviceId as list of profile Ids. " + 
                "deviceId: " + matchFromIdList.getDeviceId() + 
                "IsMobile: " + matchFromIdList.getValues("IsMobile"));
    }
    
    /**
     * Performs match for a User-Agent string and returns Match object with 
     * detection results.
     * 
     * @param userAgent String representing typical HTTP User-Agent header.
     * @return Match object with detection results.
     * @throws IOException if there was a problem accessing the data file.
     */
    public Match matchForUserAgent(String userAgent) throws IOException {
        return provider.match(mobileUserAgent);
    }
    
    /**
     * Returns a Match object corresponding to the provided string deviceId.
     * String deviceId derived by: <code>match.getDeviceId();</code>
     * 
     * @param deviceId String representation of the deviceId.
     * @return Match object with detection results.
     * @throws IOException if there was a problem accessing the data file.
     */
    public Match matchForDeviceIdString(String deviceId) throws IOException {
        return provider.matchForDeviceId(deviceId);
    }
    
    /**
     * Returns a Match object corresponding to the provided byte array Id. 
     * Byte array id is retrieved by: 
     * <code>match.getDeviceIdAsByteArray();</code>
     * 
     * @param deviceId byte array representation of deviceId.
     * @return Match object with detection results.
     * @throws IOException if there was a problem accessing the data file.
     */
    public Match matchForDeviceIdArray(byte[] deviceId) throws IOException {
        return provider.matchForDeviceId(deviceId);
    }
    
    /**
     * Returns a Match object corresponding to the provided list of profile IDs.
     * A list of profile IDs is derived from: 
     * <code>for (Profile profile : match.getProfiles()) {</code>
     * 
     * @param deviceIds a list of integers where each integer is a profile Id.
     * @return Match object with detection results.
     * @throws IOException if there was a problem accessing the data file.
     */
    public Match matchForDeviceIdList(ArrayList<Integer> deviceIds) 
                                                            throws IOException {
        return provider.matchForDeviceId(deviceIds);
    }
    
    /**
     * 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.
     */
    public void close() throws IOException {
        provider.dataSet.close();
    }

Full Source File

Summary

In this tutorial you have seen how to use the detector to retrieve the IsMobile property for a pre-defined Device ID string. The example can easily be modified to retrieve the value of any other property. Premium and Enterprise data files provide considerably more properties such as IsCrawler, PriceBand, HardwareVendor and ScreenInchesWidth. For a full list of properties and the data files they exist in please see the Property Dictionary.