How does the Usage Intelligence call home protocol work?

How does the Usage Intelligence call home protocol work?

Once you create a free Usage Intelligence account, register your product and integrate the Usage Intelligence SDK, all your software installations will start calling home to the Usage Intelligence server. The server will collect anonymous information regarding software usage, OS, language, hardware profile such as memory, CPU type and resolution, geographical information, and other information regarding your software version, build number, edition, and license keys (if applicable).

As a software vendor, you also have the option to control what information is collected from your end-users by adding an opt-out mechanism during installation or as a configuration option within your software. If a user chooses not to be tracked, then you can simply bypass the call(s) to the Usage Intelligence API.

Communication Protocol

The Usage Intelligence protocol uses a signing and authentication mechanism which protects all call home data from spoofing or other forms of tampering by rogue users whilst the clients are communicating with the Usage Intelligence servers.

The Usage Intelligence SDK supports two types of communication protocols, HTTPS and HTTP with AES-128 encrypted payload. The protocol to be used can be specified when creating the SDK configuration. Here is a description for each option:

  • HTTP with AES-128 encrypted payload: Connections to the server will be made using HTTP whilst securing the payload using AES-128 encryption.
  • HTTPS only: The client will only attempt to connect to the server using HTTPS. If HTTPS traffic is blocked, callhome will not occur.
  • HTTPS with fallback to HTTP with AES encryption: The client will first attempt to connect to the Usage Intelligence server using standard HTTPS. In cases where HTTPS traffic is blocked, the client will fall back to using HTTP with AES-128 encrypted data. This method is recommended since, in some environments, especially corporate networks, HTTPS traffic may be blocked by gateway firewalls or web filters.
  • HTTP only (deprecated): In version 4 and older of the SDK, communication was made over HTTP without encryption except for license key info. Following the release of SDK version 5 on July 3, 2017, this method is no longer supported.


  • In order to improve your customers’ perception, you also have the option to use a custom callhome URL by setting a CNAME entry in your DNS server. For info on custom URLs please refer to this KBase article.

Caching and Lack of Internet connectivity

By default, the Usage Intelligence SDK calls home to the Usage Intelligence server as soon as your software is loaded, and then every 20 minutes after that while the application is still running. Other calls can occur whenever the developer calls an API which requires a real-time response from the server, such as during Message Check and License key validation.

In the meantime, the Usage Intelligence SDK will cache usage statistics to a log file on disk, ready to be sent on the next callhome. For SDK's older than version 5, a single cache file is maintained with data from all sessions. For SDK version 5 and later, a cache file is created for every runtime session (determined by 'start-stop').

Whenever an internet connection is not available, usage data remains cached until the connection is restored. Note that before a client can track data offline, it must have done at least one successful sync with the Usage Intelligence server to register its existence and get a unique Client ID. A threshold is set on each cache file size so that a machine with a permanent loss of connectivity will stop collecting usage data for that session, once this file threshold is reached. Once the connection is restored, the log files are compressed and sent over to the Usage Intelligence server using minimal bandwidth.



Labels (2)
Was this article helpful? Yes No
No ratings
Version history
Last update:
‎Jul 21, 2020 08:55 AM
Updated by: