Getting started example of using 51Degrees device detection.
Getting started example of using 51Degrees device detection.The example shows how to:
- Specify the name of the data file, properties the data set should be initialised with, and the configuration. using namespace FiftyoneDegrees;string fileName = "51Degrees-V4.1.hash";string propertiesString = "ScreenPixelsWidth,HardwareModel,IsMobile,BrowserName";Common::RequiredPropertiesConfig *properties =new Common::RequiredPropertiesConfig(&propertiesString);new DeviceDetection::Hash::DeviceDetection::Hash::ConfigHash();C++ class wrapper for the fiftyoneDegreesPropertiesRequired structure.Definition RequiredPropertiesConfig.hpp:59C++ class wrapper for the fiftyoneDegreesConfigHash configuration structure.Definition ConfigHash.hpp:72Hash Device Detection specific classes.Definition ComponentMetaDataBuilderHash.hpp:35A C++ wrapper class for transform.h conversion routines.Definition ComponentMetaDataBuilderHash.hpp:33
- Construct a new engine from the specified data file with the required properties and the specified configuration. using namespace FiftyoneDegrees;DeviceDetection::Hash::EngineHash *engine =dataFilePath,config,properties);Encapsulates the Hash engine class which implements EngineDeviceDetection.Definition EngineHash.hpp:96
- Create a evidence instance and add a single HTTP User-Agent string to be processed. using namespace FiftyoneDegrees;evidence->operator[]("header.user-agent") = userAgent;Device detection specific evidence class containing evidence to be processed by a device detection en...Definition EvidenceDeviceDetection.hpp:64Definition GettingStarted.c:67
- Process the evidence using the engine to retrieve the values associated with the User-Agent for the selected properties.
- Obtain the drift, which is the largest number of characters a matched substring of a result was from where it was expected to be found, added up over the results, one for each component. The maximum drift to allow when finding a match can be set through the configuration structure. int drift = results->getDrift();
- Obtain the difference, which is the total difference in hash code values between the matched substrings and the actual substrings. The maximum difference to allow when finding a match can be set through the configuration structure. int difference = results->getDifference();
- Obtain the iterations, which are the number of iterations required to get the device offset in the devices collection in the graph of nodes. This is indicative of the time taken to fetch the result. int iterations = results->getIterations();
- Obtain the method, which is the highest method any result used and 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. fiftyoneDegreesHashMatchMethod method = results->getMethod();
- Obtain the matched User-Agent of the first result, which holds the matched substrings of the User-Agent separated with underscores. string matchedUserAgent = results->getUserAgent(0);
- Release the memory used by the results and the evidence. delete results;delete evidence;
- Finally release the memory used by the engine. delete engine;
/* *********************************************************************
* This Original Work is copyright of 51 Degrees Mobile Experts Limited.
* Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
* Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
*
* This Original Work is licensed under the European Union Public Licence
* (EUPL) v.1.2 and is subject to its terms as set out below.
*
* If a copy of the EUPL was not distributed with this file, You can obtain
* one at https://opensource.org/licenses/EUPL-1.2.
*
* The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
* amended by the European Commission) shall be deemed incompatible for
* the purposes of the Work and the provisions of the compatibility
* clause in Article 5 of the EUPL shall not apply.
*
* If using the Work as, or as part of, a network application, by
* including the attribution notice(s) required under Article 5 of the EUPL
* in the end user terms of the application under an appropriate heading,
* such notice(s) shall fulfill the requirements of that article.
* ********************************************************************* */
// Include ExmapleBase.h before others as it includes Windows 'crtdbg.h'
// which requires to be included before 'malloc.h'.
#include "../../C/Hash/ExampleBase.h"
#include "ExampleBase.hpp"
using namespace FiftyoneDegrees::Examples::Hash;
namespace FiftyoneDegrees {
namespace Examples {
namespace Hash {
public:
{};
const char* getMethodString(int method) {
switch (method) {
case FIFTYONE_DEGREES_HASH_MATCH_METHOD_PERFORMANCE:
return "PERFORMANCE";
case FIFTYONE_DEGREES_HASH_MATCH_METHOD_COMBINED:
return "COMBINED";
case FIFTYONE_DEGREES_HASH_MATCH_METHOD_PREDICTIVE:
return "PREDICTIVE";
case FIFTYONE_DEGREES_HASH_MATCH_METHOD_NONE:
default:
return "NONE";
}
}
// Each std::unique_ptr in this example frees what it holds
// when it is reset or goes out of scope, including when an
// exception is thrown. Results hold a reference to the
// engine's data set, so they must always be freed.
std::unique_ptr<DeviceDetection::Hash::ResultsHash> results;
// Create an evidence instance to store and process User-Agents.
std::unique_ptr<EvidenceDeviceDetection> evidence(
new EvidenceDeviceDetection());
cout << "Starting Match Metrics Example.\n";
// Carries out a match for a mobile User-Agent.
cout << "\nMobile User-Agent: " <<
evidence->operator[]("header.user-agent")
cout <<
" IsMobile: " <<
(*results->getValueAsString("IsMobile")).c_str() << "\n" <<
" Id: " << results->getDeviceId() << "\n" <<
" Drift: " << results->getDrift() << "\n" <<
" Difference: " << results->getDifference() << "\n" <<
" Iterations: " << results->getIterations() << "\n" <<
" Method: " <<
getMethodString(results->getMethod()) << "\n" <<
" Sub Strings: " << results->getUserAgent(0);
// Carries out a match for a desktop User-Agent.
cout << "\nDesktop User-Agent: " <<
evidence->operator[]("header.user-agent")
cout <<
" IsMobile: " <<
(*results->getValueAsString("IsMobile")).c_str() << "\n" <<
" Id: " << results->getDeviceId() << "\n" <<
" Drift: " << results->getDrift() << "\n" <<
" Difference: " << results->getDifference() << "\n" <<
" Iterations: " << results->getIterations() << "\n" <<
" Method: " <<
getMethodString(results->getMethod()) << "\n" <<
" Sub Strings: " << results->getUserAgent(0);
// Carries out a match for a MediaHub User-Agent.
cout << "\nMediaHub User-Agent: " <<
evidence->operator[]("header.user-agent")
cout <<
" IsMobile: " <<
(*results->getValueAsString("IsMobile")).c_str() << "\n" <<
" Id: " << results->getDeviceId() << "\n" <<
" Drift: " << results->getDrift() << "\n" <<
" Difference: " << results->getDifference() << "\n" <<
" Iterations: " << results->getIterations() << "\n" <<
" Method: " <<
getMethodString(results->getMethod()) << "\n" <<
" Sub Strings: " << results->getUserAgent(0);
// On the free Lite data file, say what the Enterprise data
// file adds and where to ask for a copy.
cout << "\n";
"/contact-us?utm_source=code&utm_medium=example&utm_campaign=51degrees-cxx&utm_content=examples-cpp-hash-matchmetrics.cpp&utm_term=lite-data-file");
}
};
}
}
}
extern "C" void fiftyoneDegreesExampleCPPMatchMetricsRun(ExampleParameters *params) {
// Call the actual function.
try {
// The example, and the engine it holds, is freed when it goes out of
// scope, including when an exception is thrown.
MatchMetrics matchMetrics(params->dataFilePath, cppConfig);
matchMetrics.run();
}
catch (const StatusCodeException &e) {
ExampleBase::reportStatus(e.getCode(), params->dataFilePath);
exit(1);
}
}
#ifndef TEST
int main(int argc, char* argv[]) {
if (argc > 1) {
strcpy(dataFilePath, argv[1]);
}
else {
status = ExampleBase::getFilePath(
dataDir,
dataFileName,
dataFilePath,
sizeof(dataFilePath));
}
if (status != FIFTYONE_DEGREES_STATUS_SUCCESS) {
ExampleBase::reportStatus(status, dataFileName);
fgetc(stdin);
return 1;
}
ExampleParameters params;
params.dataFilePath = dataFilePath;
// run the example
fiftyoneDegreesExampleMemCheck(
¶ms,
fiftyoneDegreesExampleCPPMatchMetricsRun);
// Wait for a character to be pressed.
fgetc(stdin);
return 0;
}
#endif
Base class extended by all Hash examples.
Definition ExampleBase.hpp:59
static fiftyoneDegreesStatusCode getFilePath(const char *dataFolderName, const char *fileName, char *destination, size_t size)
Finds a file in the data folder, and downloads it first when it is missing and the data repository li...
std::unique_ptr< DeviceDetection::Hash::ConfigHash > config
Configuration for the Engine.
Definition ExampleBase.hpp:261
ExampleBase(byte *data, long length, DeviceDetection::Hash::ConfigHash *config)
Construct a new instance of the example to be run using the data pointer provided.
std::unique_ptr< EngineHash > engine
Hash Engine used for the example.
Definition ExampleBase.hpp:266
static const char * mobileUserAgent
Example mobile User-Agent string.
Definition ExampleBase.hpp:104
static const char * mediaHubUserAgent
Example media hub User-Agent string.
Definition ExampleBase.hpp:116
static void reportStatus(fiftyoneDegreesStatusCode status, const char *fileName)
Reports the status of the data file initialization.
static const char * desktopUserAgent
Example desktop User-Agent string.
Definition ExampleBase.hpp:107
void offerEnterprise(const char *contactUs) const
On the free Lite data file, says what the Enterprise data file adds and where to ask for a copy.
Match Metrics Hash Example.
Definition MatchMetrics.cpp:137
void run()
Run the example.
Definition MatchMetrics.cpp:163
MatchMetrics(string dataFilePath, DeviceDetection::Hash::ConfigHash *config)
Construct a new instance of the example to be run using the data file provided.
Definition MatchMetrics.cpp:142
#define FIFTYONE_DEGREES_FILE_MAX_PATH
Define the max path length on the target system.
Definition file.h:217
EXTERNAL_VAR fiftyoneDegreesConfigHash fiftyoneDegreesHashDefaultConfig
Default detection configuration.
Definition hash.h:460
fiftyoneDegreesStatusCode
Status returned from the initialisation of a resource.
Definition status.h:81