The first time an end-user runs your software - assuming you have integrated the Revulytics Usage Intelligence SDK - the Usage Intelligence DLL creates a fingerprint of that machine, which is stored as a hash code inside the ruiconfig file, and sends it to the server during its first call home.
From this point onward, that same hash code will be used to uniquely identify that installation for all subsequent call homes to the Revulytics server.
What happens if the user formats his machine and/or uninstalls and re-installs my software?
Usage Intelligence uses a unique method of generating the hash code which can survive both an uninstall of your software and also formatting of a machine, assuming you always use the same data folder when calling
ruiCreateConfig(). We do not rely on Windows registry, therefore Usage Intelligence is not effected by any registry cleaners either.
Generating a unique fingerprint
The hash code that defines the unique client ID is tied to a machine's hardware architecture (fingerprint) as well as your software's data path set during initialization - using the
ruiCreateConfig() method. This means if users uninstall your software or even format their machine, once they re-install your software the Usage Intelligence SDK will re-generate the exact same hash code. This allows our reporting engine to keep tracking that user uniquely and you will not get a false impression that a new installation has taken place.
If users change any of their hardware without uninstalling your software, the Usage Intelligence SDK will detect this and inform the server that this installation fingerprint has changed.
The only two occasions where Revulytics will lose track of a unique user/installation is when:
- A user uninstalls your software (or formats his/her machine) and your software uses a different data path on re-installation.
- A user uninstalls your software (or formats his/her machine) AND changes their hardware before reinstalling your software.
In such cases, the first time your software is run after being reinstalled, Usage Intelligence will generate a new fingerprint assuming this is a new user installation.
Upgrading or installing concurrent versions of your application
If during an upgrade of your software, the data path of the new version is the same as the old version, then the Usage Intelligence SDK will immediately find the ruiconfig file and will continue to use it. In case this file is deleted during the upgrade, the SDK will recreate it during the first runtime session. Assuming the installation path did not change, the fingerprint/hash identifying this client installation will remain identical and so the server will know that this was an upgrade rather than a new installation.
In the case where your application uses a different data path when calling
ruiCreateConfig() and you want the Revulytics server to know that this was an upgrade (and not a new installation), then you can provide the option to move the ruiconfig file from the old installation folder to the new folder. Since the fingerprint identifying a client installation is stored in this file, during its first run the SDK will note that an upgrade took place and inform the server accordingly whilst regenerating a new fingerprint matching the new installation path.
WARNING: If your software allows concurrent versions to be installed on the same machine, for e.g. you allow users to run version 1.2 whilst still having version 1.1 installed in a different directory, then it is VERY IMPORTANT that you DO NOT COPY the config file to the new installation data folder during an upgrade. Doing so will cause conflicts on the server since the same client ID will be seen as constantly upgrading and downgrading between version 1.1 and 1.2. This will cause your reports to show skewed and inaccurate data. In this case you should not port any Usage Intelligence files to the new folder so that the Usage Intelligence SDK will create a new config file and track these concurrent installations as 2 separate installations.
How does Usage Intelligence handle Virtual Machines?
For Usage Intelligence, a virtual machine is regarded just like any other independent physical machine. Therefore if your software is installed on 2 separate VMs on the same physical machine, each of these VMs will have its own fingerprint and will be tracked as 2 independent installations.
How does Usage Intelligence handle multiple concurrent installations on the same machine?
If your software allows users to install 2 or more instances side-by-side, for example when a single user runs different versions/editions concurrently on the same machine, Usage Intelligence will track each of these installations separately using a unique fingerprint for each installation. In this case these 2 installations are counted as 2 separate users/installations. Of course this does not hold if the user uninstalls and re-installs an updated version of your software using the same installation path. In this case Usage Intelligence will keep tracking that user as a single unique user.