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

C 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

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

  1. Specify name of the data file and properties the dataset should be initialised with.

    	const char* fileName = argv[1];
    	const char* properties = "IsMobile";
    	

  2. Instantiate the 51Degrees provider from the specified data file with the required properties, number of worksets in the pool and cache of the specific size.

    	fiftyoneDegreesInitProviderWithPropertyString(
    	fileName, &provider, properties, 4, 1000);
    	

  3. Retrieve a workset from the pool and use it for a single match.

    	fiftyoneDegreesWorkset *ws = NULL;
    	ws = fiftyoneDegreesProviderWorksetGet(&provider);
    	

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

    ws->method

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

    	ws->difference

  6. Obtain signature rank: an integer value that indicates how popular the device is. The lower the rank the more popular the signature.

    	fiftyoneDegreesGetSignatureRank();
    	

  7. Release the workset back into the pool of worksets to be reused in one of the next matches.

    	fiftyoneDegreesWorksetRelease(ws);
    	

  8. Finally release the memory taken by the provider.

    	fiftyoneDegreesProviderFree(&provider);
    	

This example assumes you have compiled with 51Degrees.c and city.c. This will happen automatically if you are compiling as part of the Visual Studio solution. Additionally, when running the program, the location of a 51Degrees data file must be passed as a command line argument if you wish to use Premium or Enterprise data files.

Full Source File
#include <stdio.h>
#include "../src/pattern/51Degrees.h"

// Global settings and properties.
static fiftyoneDegreesProvider provider;

// Function declarations.
static void reportDatasetInitStatus(
    fiftyoneDegreesDataSetInitStatus status,
    const char* fileName);
void output_match_metrics(fiftyoneDegreesWorkset* ws);
void run(fiftyoneDegreesProvider* provider);

int main(int argc, char* argv[]) {
    const char* properties = "IsMobile";
    const char* fileName = argc > 1 ? argv[1] : "../../../data/51Degrees-LiteV3.2.dat";

#ifdef _DEBUG
#ifndef _MSC_VER
    dmalloc_debug_setup("log-stats,log-non-free,check-fence,log=dmalloc.log");
#endif
#endif

    // Create a pool of 4 worksets with a cache for 1000 items.
    fiftyoneDegreesDataSetInitStatus status =
        fiftyoneDegreesInitProviderWithPropertyString(
        fileName, &provider, properties, 4, 1000);
    if (status != DATA_SET_INIT_STATUS_SUCCESS) {
        reportDatasetInitStatus(status, fileName);
        fgetc(stdin);
        return 1;
    }

    run(&provider);

    // Free the pool, dataset and cache.
    fiftyoneDegreesProviderFree(&provider);

#ifdef _DEBUG
#ifdef _MSC_VER
    _CrtDumpMemoryLeaks();
#else
    printf("Log file is %s\r\n", dmalloc_logpath);
#endif
#endif

    // Wait for a character to be pressed.
    fgetc(stdin);

    return 0;
}
void run(fiftyoneDegreesProvider* provider) {
    fiftyoneDegreesWorkset *ws = NULL;

    // User-Agent string of an iPhone mobile device.
    const char* 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.
    const char* desktopUserAgent = ("Mozilla/5.0 (Windows NT 6.3; WOW64; rv:41.0) "
    "Gecko/20100101 Firefox/41.0");

    // User-Agent string of a MediaHub device.
    const char* 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");

    printf("Starting Getting Started Match Metrics Example\n");

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Carries out a match with a mobile User-Agent.
    printf("\nUser-Agent: %s\n", mobileUserAgent);
    fiftyoneDegreesMatch(ws, mobileUserAgent);
    output_match_metrics(ws);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Carries out a match with a desktop User-Agent.
    printf("\nUser-Agent: %s\n", desktopUserAgent);
    fiftyoneDegreesMatch(ws, desktopUserAgent);
    output_match_metrics(ws);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Carries out a match with a MediaHub User-Agent.
    printf("\nUser-Agent: %s\n", mediaHubUserAgent);
    fiftyoneDegreesMatch(ws, mediaHubUserAgent);
    output_match_metrics(ws);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);
}

/**
 * Gets device id for given match and prints match metrics
 * associated with it.
 * @param initialised workset of type fiftyoneDegreesWorkset
 */
void output_match_metrics(fiftyoneDegreesWorkset* ws) {
    char deviceId[40];
    fiftyoneDegreesGetDeviceId(ws, deviceId, 40);

    int method = ws->method;
    int difference = ws->difference;
    int rank = fiftyoneDegreesGetSignatureRank(ws);

    printf("   Id: %s\n", deviceId);
    printf("   Method: %d\n", method);
    printf("   Difference: %d\n", difference);
    printf("   Rank: %d\n", rank);
    return;
}

/**
* Reports the status of the data file initialization.
*/
static void reportDatasetInitStatus(fiftyoneDegreesDataSetInitStatus status,
    const char* fileName) {
    switch (status) {
    case DATA_SET_INIT_STATUS_INSUFFICIENT_MEMORY:
        printf("Insufficient memory to load '%s'.", fileName);
        break;
    case DATA_SET_INIT_STATUS_CORRUPT_DATA:
        printf("Device data file '%s' is corrupted.", fileName);
        break;
    case DATA_SET_INIT_STATUS_INCORRECT_VERSION:
        printf("Device data file '%s' is not correct version.", fileName);
        break;
    case DATA_SET_INIT_STATUS_FILE_NOT_FOUND:
        printf("Device data file '%s' not found.", fileName);
        break;
    case DATA_SET_INIT_STATUS_NULL_POINTER:
        printf("Null pointer to the existing dataset or memory location.");
        break;
    case DATA_SET_INIT_STATUS_POINTER_OUT_OF_BOUNDS:
        printf("Allocated continuous memory containing 51Degrees data file "
            "appears to be smaller than expected. Most likely because the"
            " data file was not fully loaded into the allocated memory.");
        break;
    default:
        printf("Device data file '%s' could not be loaded.", fileName);
        break;
    }
}

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.