Initializing the Configuration
The createConfig() method must be called in order to initialize the configuration.
The createConfig() method creates a configuration for the SDK instance. A configuration is passed in a file, specified by configFilePath, productID, and appName. If two or more SDK instances, in the same process or in different processes, use the same values for these three parameters, then those SDK instances are bound together through a shared configuration. When multiple different executables are being used, such usage is generally not desirable nor recommended. Instead, each executable should use a different appName value.
The SDK has two communications modes: HTTPS or HTTP + AES-128 encryption. The mode is configured by protocol. When protocol is set to HTTP_PLUS_ENCRYPTION or HTTPS_WITH_FALLBACK, the AES key must be supplied as a 128-bit hex-encoded string (aesKeyHex). When protocol is HTTPS, then aesKeyHex must be empty.
On first execution of a client application, no SDK configuration file will exist. This situation is detected by the SDK and will result in a New Registration message to the Server at startSDK(). Once the configuration is received from the Server, the SDK writes the configuration file, that is then used for subsequent client application executions.
createConfig() must be called before most other APIs and must only be successfully called once.
createConfig() is a synchronous function, returning when all functionality is completed.
RUIResult createConfig(String configFilePath, String productID, String appName, String serverURL, RUIProtocol protocol, String aesKeyHex, boolean multiSessionEnabled, boolean reachOutOnAutosync)
Parameters
The createConfig() method has the following parameters.
|
Parameter |
Description |
|
configFilePath (String) |
The directory to use for the SDK instance’s configuration file. Cannot be empty; must exist and be writable. |
|
productID (String) |
The Revenera-supplied product ID for this client; 10 digits. You obtain this ID after registering with Revenera. |
|
appName (String) |
The customer-supplied application name for this client, to distinguish suites with the same productID. Cannot be empty or contain white space; at most 16 UTF-8 characters. More information about the purpose of the appName parameter can be found in the Knowledge Base article: What is the purpose of the appName parameter when creating config in the SDK? |
|
serverUrl (String) |
Every product registered with Usage Intelligence has its own unique URL usually in the form xxxxx.tbnet1.com. This URL is generated automatically on account creation and is used by the SDK to communicate with the Usage Intelligence server. You can get this URL from the Developer Zone once you login to the Usage Intelligence dashboard. If you have a Premium product account, you may opt to use your own custom server URL (such as http://updates.yourdomain.com) that must be set up as a CNAME DNS entry pointing to your unique Usage Intelligence URL. Note:Before you can use your own custom URL, you must first inform Usage Intelligence support (support@revenera.com) to register your domain with the Usage Intelligence server. If you fail to do this, the server will automatically reject any incoming calls using yourdomain.com as a server URL. The URL should not contain a protocol prefix. |
|
protocol (RUIProtocol) |
Indicates whether HTTP + AES, HTTPS with fall-back to HTTP + AES, or HTTPS only is used to communicate with the Server. Valid choices can be found in the RUIProtocol enum and are: HTTP_PLUS_ENCRYPTION (1) HTTPS_WITH_FALLBACK (2) HTTPS (3) |
|
aesKeyHex (String) |
AES Key to use when protocol includes encryption (HTTP_PLUS_ENCRYPTION or HTTPS_WITH_FALLBACK); 32 hex chars (128 bit) key. |
|
multiSessionEnabled (boolean) |
Indicates whether or not the client will explicitly manage sessionIDs via startSession() and stopSession(), and supply those sessionIDs to the various event tracking APIs. Refer to Single vs. Multiple Session Modes. |
|
reachOutOnAutosync (boolean) |
Indicates whether or not a ReachOut should be requested as part of each SDK Automatic sync. A ReachOut request will be made only if a ReachOut handler has been set by registering the default graphical handler (SDKImpl()) or a custom handler (setReachOutHandler()). This value may be changed at runtime using the call setReachOutOnAutoSync(). |
Returns
The createConfig() method returns one of the return status constants below.
|
Return |
Description |
|
OK |
Function successful. |
|
SDK_INTERNAL_ERROR_FATAL |
Irrecoverable internal fatal error. No further API calls should be made. |
|
SDK_PERMANENTLY_DISABLED |
The Server has instructed a permanent disable. |
|
CONFIG_ALREADY_CREATED |
Configuration has already been successfully created. |
|
INVALID_PARAMETER_EXPECTED_NON_EMPTY |
Some API parameter is expected to be non-empty, and is not. |
|
INVALID_PARAMETER_EXPECTED_NO_WHITESPACE |
Some API parameter is expected to be free of white space, and is not. |
|
INVALID_PARAMETER_TOO_LONG |
Some API parameter violates its allowable maximum length. |
|
INVALID_CONFIG_PATH |
The configFilePath is not a well-formed directory name. |
|
INVALID_CONFIG_PATH_NONEXISTENT_DIR |
The configFilePath identifies a directory that does not exist. |
|
INVALID_CONFIG_PATH_NOT_WRITABLE |
The configFilePath identifies a directory that is not writable. |
|
INVALID_PRODUCT_ID |
The productID is not a well-formed Product ID. |
|
INVALID_SERVER_URL |
The serverURL is not a well-formed URL. |
|
INVALID_PROTOCOL |
The protocol is not a legal value. |
|
INVALID_AES_KEY_EXPECTED_EMPTY |
The AES Key is expected to be NULL/empty, and it's not. |
|
INVALID_AES_KEY_LENGTH |
The AES Key is not the expected length (32 hex chars). |
|
INVALID_AES_KEY_FORMAT |
The AES Key is not valid hex encoding. |
Code Example
The following example shows how to initialize the Usage Intelligence configuration:
String myPath = "<path to directory for RUI SDK logging>";
String myProductId = "<Product ID>";
String myAppName = "<AppName>";
String myURL = "<CallHome URL without protocol prefix>";
String myKey = "<Your AES HEX Key>";
RUIProtocol myProtocol = RUIProtocol.HTTP_PLUS_ENCRYPTION;
boolean myMultiSessionSetting = false;
boolean myReachOutAutosyncSetting = false;
mySDK.createConfig(myPath, myProductId, myAppName, myURL, myProtocol, myKey, myMultiSessionSetting, myReachOutAutosyncSetting);