The Usage Intelligence SDK version 5 was released on July 3, 2017. This release contains various enhancements and new functionality. If you are planning to upgrade to SDK V5, please note that API calls have changed and this is not a simple drop in replacement. This article is intended to give developers an overview of the changes. For full details please review the SDK V5 documentation on the Usage Intelligence SDK Download Links and API Documentation page.

Upgrading From Version 3 to Version 4 and 5

• Change from singleton to dynamic classes. This requires you to create an instance of the class instead of making use of static functions. To create and destroy an instance:
  
  
  • V4 - tbCreateInstance() and tbDestroyInstance()
  • V5 - ruiCreateInstance() and ruiDestroyInstance()
• Setting the path where the Usage Intelligence SDK files will be saved is compulsory. In V4 this is set by calling tbSetFilePath() and in V5 set by ruiCreateConfig().
• Key check/change and message check always allocate memory, tbFree() in V4 and ruiFree() in V5 must be called on the message or license array to free memory.
• The following functions have been deprecated:
  
  
  • tbVersionCheck()
  • tbSetPrivacyMode()

Upgrading From Version 3 and 4 to Version 5

• The naming convention has changed from tb to rui prefix for all SDK functions, e.g. tbCreateConfig() is now ruiCreateConfig(). This change was done to reflect the new company branding that was changed from Trackerbird to Revulytics in 2016.
• ruiCreateInstance() accepts a boolean parameter to specify if the default ReachOut™ handler should be registered. If set to true, the SDK will handle the display of the window when an automatic ReachOut™ is delivered. If set to false, you will need to use ruiSetReachOutHandler() to specify custom functions which will be called to display and close ReachOut™ windows. The default ReachOut™ handler is available for the Windows and Mac SDK. For Linux, a custom handler must be set to display automatic ReachOut™ messages. Refer to the documentation for more information on ruiSetReachOutHander():
  
  
  • Windows: C/C++ | .NET
  • Mac: C/C++ | Objective-C
  • Linux: C/C++
• V5 does not save product and licensing info in the config file anymore and it is recommended to set all known info before every start. This includes product edition, language, version, build, custom properties, and license key type and flags (activated, expired, blacklisted, whitelisted) when licensing is client managed. If these settings are only set once and the SDK is not able to callhome during that application runtime, the settings will be lost.
• tbSetFilePath() and tbCreateConfig() have been consolidated to ruiCreateConfig(), which now accepts the file path as the first parameter.
• ruiCreateConfig() parameters have changed, the following are now required:
  
  
  • configFilePath – The path where the Usage Intelligence files will be saved, in previous versions this used to be set by tbSetFilePath()
  • productID – The ID of your product, retrieved from the Usage Intelligence Dashboard > Administration page
  • appName – A name for the application, it cannot contain spaces. If multiple applications in the same product suite are tracked under the same product ID they should have different app names
  • serverURL – The callhome URL for your product, retrieved from the Usage Intelligence Dashboard > Administration page
  • protocol – The protocol used when communicating with the server:
    
    
    • 1 - HTTP with AES-128 encrypted payload
    • 2 - HTTPS with fall back to HTTP with AES-128 encrypted payload
    • 3 - HTTPS only (with no fallback)
  • aesKeyHex – AES key retrieved from the Usage Intelligence Dashboard > Administration page to be used for HTTP with AES-128 encryption communication. Must be empty if HTTPS only is used
  • multiSessionEnabled – true/false whether sessions are managed by the application
  • reachOutOnAutoSync – true/false whether the SDK should check for available automatic ReachOut™ campaigns when it automatically syncs with the server
• Setting product version and build is no longer done when creating config. To set product details in V5:
  
  
  • ruiSetProductData() accepts parameters for product edition, language, version and build
  • Functions to set individual product details still remain, ruiSetProductEdition(), ruiSetProductVersion() etc..
• tbStartAutoSync() and tbStopAutoSync() are no longer available. The SDK now automatically syncs with the server every 20 minutes by default. This setting cannot be changed or switched off.
• Function names to set license properties and check / track license changes have changed:
  
  
  • tbSetLicense() is now ruiSetLicenseData()
  • tbKeyCheck() is now ruiCheckLicenseKey()
  • tbKeyChanged() is now ruiSetLicenseKey()
• ruiSetLicenseData() now accepts a session ID parameter, which can be specified when running in multi session mode or left empty.
• The order of the license array values when using ruiCheckLicenseKey() and ruiSetLicenseKey() has changed. The new order is:
  
  
  • RUI_LICENSE_ARRAY_INDEX_KEY_TYPE (0)
  • RUI_LICENSE_ARRAY_INDEX_KEY_EXPIRED (1)
  • RUI_LICENSE_ARRAY_INDEX_KEY_ACTIVE (2)
  • RUI_LICENSE_ARRAY_INDEX_KEY_BLACKLISTED (3)
  • RUI_LICENSE_ARRAY_INDEX_KEY_WHITELISTED (4)
• Function names to check for manual ReachOut™ messages have changed:
  
  
  • tbMessageCheck() is now ruiCheckForReachOut()
  • tbMessageCheckWithMessageType() is now ruiCheckForReachOutOfType()
• In V5 there are different ways to track events with custom data:
  
  
  • Same functionality of tbEventTrackTxt() is available in ruiTrackEventText()
  • New function ruiTrackEventCustom() accepts an array of key/value pairs and will be saved in the format (Key1, Value1)&&(Key2,Value2). Refer to the documentation for more info:
    
    
    • Windows: C/C++ | .NET
    • Mac: C/C++ | Objective-C
    • Linux: C/C++
• ruiTrackException() accepts a struct with exception details instead of individual parameters. Refer to the documentation for more info:
  
  
  • Windows: C/C++ | .NET
  • Mac: C/C++ | Objective-C
  • Linux: C/C++
• The Mac and Linux SDK now support setting proxy settings through ruiSetProxy(). This functionality was previously only available for Windows.
• Function return values have changed:
  
  
  • “OK” value has been changed from 1 in V3 and V4 to 0 in V5, i.e. TB_OK (1) is now RUI_OK (0)
  • In general, a negative return value now means an error occurred, while positive values are info
  • Check respective function documentation for new return values

If you require further technical assistance during the upgrade/migration process, contact Revenera Support.