Initializing the Configuration
The createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: method must be called in order to initialize the configuration. The method signature is as follows.
createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:
(RUIRESULTOBJC) (createConfig: (NSString*) configFilePath productID: (NSString*)productID appName: (NSString*)appName serverURL: (NSString*)serverURL protocol: (int32_t)protocol aesKeyHex: (NSString*)aesKeyHex multiSessionEnabled: (BOOL)multiSessionEnabled reachOutOnAutoSync: (BOOL)reachOutOnAutoSync
Parameters
The createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: method has the following parameters.
|
Parameter |
Description |
|
configFilePath (NSString*) |
The directory to use for the SDK instance’s configuration file. Cannot be empty; must exist and be writeable. |
|
serverURL (NSString*) |
CallHome URL: Every product registered with Usage Intelligence has its own unique CallHome URL usually in the form of http://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. |
|
productID (NSString*) |
This is a unique 10-digit Product ID number that identifies your product with the Usage Intelligence Server. |
|
appName (NSString*) |
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 following knowledge base article: What is the purpose of the appName parameter when creating config in the SDK? |
|
protocol (int32) |
Indicates whether HTTP + AES, HTTPS with fall back to HTTP + AES, or HTTPS is used to communicate with the RUI Server. Valid values are RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION (1), RUI_PROTOCOL_HTTPS_WITH_FALLBACK (2), or RUI_PROTOCOL_HTTPS (3). |
|
aesKeyHex (NSString*) |
AES Key to use when protocol includes encryption; 32 hex chars (128 bit) key. Used with protocol RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION and RUI_PROTOCOL_HTTPS_WITH_FALLBACK. |
|
multiSessionEnabled (BOOL) |
Whether multiple user sessions can be present in a single application runtime. 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 (initRegisterDefaultGraphicalReachOutHandler) or a custom handler (setReachOutHandler:). This value may be changed at runtime using the call setReachOutOnAutoSync:. |
Returns
The createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: method returns an Integer constant value with the following possible values:
|
Return |
Description |
|
RUI_OK |
Function successful |
|
RUI_SDK_INTERNAL_ERROR_FATAL |
Irrecoverable internal fatal error. No further API calls should be made. |
|
RUI_SDK_PERMANENTLY_DISABLED |
The Server has instructed a permanent disable. |
|
RUI_CONFIG_ALREADY_CREATED |
Configuration has already been successfully created. |
|
RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY |
Some API parameter is expected to be non-empty, and is not. |
|
RUI_INVALID_PARAMETER_EXPECTED_NO_WHITESPACE |
Some API parameter is expected to be free of whitespace, and is not. |
|
RUI_INVALID_PARAMETER_TOO_LONG |
Some API parameter violates its allowable maximum length. |
|
RUI_INVALID_CONFIG_PATH |
The configFilePath is not a well-formed directory name. |
|
RUI_INVALID_CONFIG_PATH_NONEXISTENT_DIR |
The configFilePath identifies a directory that does not exist. |
|
RUI_INVALID_CONFIG_PATH_NOT_WRITABLE |
The configFilePath identifies a directory that is not writable. |
|
RUI_INVALID_PRODUCT_ID |
The productID is not a well-formed Product ID. |
|
RUI_INVALID_SERVER_URL |
The serverURL is not a well-formed URL. |
|
RUI_INVALID_PROTOCOL |
The protocol is not a legal value. |
|
RUI_INVALID_AES_KEY_EXPECTED_EMPTY |
The AES Key is expected to be NULL/empty, and it not. |
|
RUI_INVALID_AES_KEY_LENGTH |
The AES Key is not the expected length (32 hex chars; 16 bytes). |
|
RUI_INVALID_AES_KEY_FORMAT |
The AES Key is not valid hex encoding. |
Code Example
RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.
NSString* myURL = @"CALLHOME-URL-WITHOUT-PROTOCOL-PREFIX";
NSString* myProductID = @"INSERT-YOUR-PROD-ID";
NSString* myPath = @"<Path name to RUI writable directory>";
int32 myProtocol = RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION;
NSString* myKey = @"0123456789abcdeffedcba98765.5.10";
NSString* myAppName = "<YOUR APP NAME>";
BOOL myReachOutAutoSyncSetting = YES;
BOOL myMultiSessionSetting = NO;
[mySDK createConfig:myPath productID:productID appName:myAppName serverURL:myURL protocol:myProtocol aesKeyHex:myKey multiSessionEnabled:myMultiSessionSetting reachOutOnAutoSync:myReachOutAutoSyncSetting];