Initializing the Configuration
The RUISDK.CreateConfig method must be called in order to initialize the configuration. The method signature is below.
RUISDK.CreateConfig creates a configuration for the SDK instance. A configuration is passed on 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 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 RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION or RUI_PROTOCOL_HTTPS_WITH_FALLBACK, the AES key must be supplied as a 128-bit hex-encoded string (aesKeyHex). When protocol is RUI_PROTOCOL_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 RUI SDK and will result in a New Registration message to the Usage Intelligence Server at RUISDK.StartSDK. Once the configuration is received from the Server, the SDK writes the configuration file, that is then used for subsequent client application executions.
RUISDK.CreateConfig must be called before most other APIs and must only be successfully called once.
RUISDK.CreateConfig is a synchronous function, returning when all functionality is completed.
RUIResult RUISDK.CreateConfig (String configFilePath, String productID, String appName, String serverURL, Int32 protocol, String aesKeyHex, Boolean multiSessionEnabled, Boolean reachOutOnAutoSync)
Parameters
The RUISDK.CreateConfig function 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 CallHome 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 CallHome URL (such as http://updates.yourdomain.com) that must be setup 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 CallHome URL. The URL should not contain a protocol prefix. |
|
protocol (int32) |
Indicates whether HTTP + AES, HTTPS with fall-back to HTTP + AES, or HTTPS is used to communicate with the server. Valid choices can be found in the RUIProtocolType enum and are: httpPlusEncryption (1), httpsWithFallback (2), or https (3). |
|
aesKeyHex (String) |
AES Key to use when protocol includes encryption (httpPlusEncryption or httpsWithFallback); 32 hex chars (128 bit) key. |
|
multiSessionEnabled (bool) |
Indicates whether or not the client will explicitly manage sessionIDs via RUISDK.StartSession and RUISDK.StopSession, and supply those sessionIDs to the various event tracking APIs. Refer to Single vs. Multiple Session Modes. |
|
reachOutOnAutoSync (bool) |
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 (RUISDK constructor) or a custom handler (RUISDK.SetReachOutHandler). This value may be changed at runtime using the call SetReachOutOnAutoSync. |
Returns
The RUISDK.CreateConfig function returns a RUIResult enum value with the following possible values:
|
Return |
Description |
|
ok |
Function successful. |
|
sdkInternalErrorFatal |
Irrecoverable internal fatal error. No further API calls should be made. |
|
sdkPermantelyDisabled |
The Server has instructed a permanent disable. |
|
configAlreadyCreated |
Configuration has already been successfully created. |
|
invalidParameterExpectedNonEmpty |
Some API parameter is expected to be non-empty, and is not. |
|
invalidParameterExpectedNoWhitespace |
Some API parameter is expected to be free of white space, and is not. |
|
invalidParameterTooLong |
Some API parameter violates its allowable maximum length. |
|
invalidConfigPath |
The configFilePath is not a well-formed directory name. |
|
invalidConfigPathNonexistentDir |
The configFilePath identifies a directory that does not exist. |
|
invalidConfigPathNotWritable |
The configFilePath identifies a directory that is not writable. |
|
invalidProductID |
The productID is not a well-formed Product ID. |
|
invalidServerURL |
The serverURL is not a well-formed URL. |
|
invalidProtocol |
The protocol is not a legal value. |
|
invalidAESKeyEpxectedEmpty |
The AES Key is expected to be NULL/empty, and it is not. |
|
invalidAESKeyLength |
The AES Key is not the expected length of 32 hex chars. |
|
invalidAESKeyFormat |
The AES Key is not valid hex encoding. |