Developer Zone

Custom Properties

Apart from the pre-set values that Revulytics Usage Intelligence collects, such as OS version, product version, edition, language, and license type you also have the ability to collect any custom value that is relevant to your specific application.

Typical examples where you can benefit from custom properties include storing the download source or marketing campaign from where the user downloaded your software or some other status in your application. These custom properties will then be available inside the filters panel on every report so you may use them as part of your report filtering criteria.

Note: By default you can store up to 1000 unique values inside every custom property. Please contact Revulytics Usage Intelligence support (support-rui@revulytics.com) if you want to discuss this limit or alternative uses.

RUIRESULT ruiSetCustomProperty(RUIINSTANCE* ruiInstance, uint32_t customPropertyID, const char* customValue)

Sets or clears the custom property data. NOTE: The custom property data must be set every time the RUI SDK instance is run. This is different than V4 of the RUI SDK where the supplied product data was stored in the RUI SDK configuration file and if it was not supplied, the values in the configuration file were used.

ruiSetCustomProperty() can be called between ruiCreateConfig() and ruiStopSDK(), and can be called zero or more times.

ruiSetCustomProperty() is a synchronous function, returning when all functionality is completed.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

customPropertyID (uint32_t) - This is a numeric index between 1 and 20. On the Revulytics Usage Intelligence dashboard,
custom values are given an ID ranging from C01 to C20. This ID is used to identify which of the 20 possible custom value is being set.

customValue (const char*) - The custom property value to use in RUI Server reports; empty value clears the value.

Returns:One of the return status constants below.
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_INVALID_CUSTOM_PROPERTY_ID - The customPropertyID violates its allowable range.