This website uses cookies. By clicking Accept, you consent to the use of cookies. Click Here to learn more about how we use cookies.
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
- Revenera Community
- :
- Usage Intelligence
- :
- Usage Intelligence Knowledge Base
- :
- Migrating From Usage Intelligence SDK Version 3 and 4 to Version 5
Subscribe
- Mark as New
- Mark as Read
- Subscribe
- Printer Friendly Page
- Report Inappropriate Content
Migrating From Usage Intelligence SDK Version 3 and 4 to Version 5
Migrating From Usage Intelligence SDK Version 3 and 4 to Version 5
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()
andtbDestroyInstance()
- V5 -
ruiCreateInstance()
andruiDestroyInstance()
- V4 -
- 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 byruiCreateConfig().
- Key check/change and message check always allocate memory,
tbFree()
in V4 andruiFree()
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 nowruiCreateConfig()
. 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 useruiSetReachOutHandler()
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 onruiSetReachOutHander()
:
- 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()
andtbCreateConfig()
have been consolidated toruiCreateConfig()
, 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
- configFilePath – The path where the Usage Intelligence files will be saved, in previous versions this used to be set by
- 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()
andtbStopAutoSync()
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 nowruiSetLicenseData()
tbKeyCheck()
is nowruiCheckLicenseKey()
tbKeyChanged()
is nowruiSetLicenseKey()
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()
andruiSetLicenseKey()
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 nowruiCheckForReachOut()
tbMessageCheckWithMessageType()
is nowruiCheckForReachOutOfType()
- In V5 there are different ways to track events with custom data:
- Same functionality of
tbEventTrackTxt()
is available inruiTrackEventText()
- 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++
- Same functionality of
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.
No ratings