Developer Zone

Basic SDK Control

Once the required configuration is initialized (explained in the SDK Configuration page) and set according to the needs of your application, you may inform the SDK that the application has started. This will allow you to use further methods that expect the application to be running such as checkLicenseKey.

(RUIRESULTOBJC) startSDK

Starts the RUI SDK. startSDK must be paired with a call to stopSDK:. After the RUI SDK is started, the various event tracking APIs are available to be used. If createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: did not detect a configuration file, startSDK will perform a New Registration with the RUI Server. Until a New Registration is complete, the RUI SDK will not be able save event data to a log file or perform synchronization with the RUI Server. A successful New Registration (or presence of a configuration file) will put the RUI SDK into a normal running state, whereby events are saved to a log file, automatic and manual synchronizations with the RUI Server are possible, and getting ReachOutTM campaigns from the Server are possible. A failed New Registration will put the RUI SDK into an aborted state, not allowing further activity.

startSDK must be called after createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:, and must be called only once.

startSDK is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

startSDK will always attempt a new registartion or sync with the server. This includes sending data to the server regarding past application and event usage that had not been synced yet, product information which has been set by the application and environment data (OS version, CPU, GPU etc..) automatically collected by the SDK. Refer to optOut: for how to configure the SDK to disable tracking an installation.

Return Type:

RUIRESULTOBJC integer constant value with the following possible values:

* RUI_OK                                        Synchronous functionalitysuccessful
* 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.  StopSDK and RUISDK destructor are possible.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STARTED                       SDK has already been successfully started.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.

(RUIRESULTOBJC) stopSDK: (int32_t)doSync

Stops the RUI SDK that was started with startSDK. If explicit sessions are allowed (multiSessionsEnabled = true in createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:), then any sessions that have been started with startSession: that have not been stopped with stopSession: are automatically stopped. A manual synchronization with the RUI Server, sync:, will be performed at stop depending on the value of doSync:

* -1 : Do not perform a manual synchronization with the RUI Server as part of the stop. RUI_SDK_STOP_NO_SYNC
*  0 : Perform a manual synchronization with the RUI Server as part of the stop; wait indefinitely for completion. RUI_SDK_STOP_SYNC_INDEFINITE_WAIT
* >0 : Perform a manual synchronization with the RUI Server as part of the stop; wait only doSync seconds for completion.

stopSDK: must be called after startSDK and must be called only once. After stopSDK: is called, the various event tracking APIs are no longer available. The only APIs available are getState and the destructor. The RUI SDK cannot be re-started with a subsequent call to startSDK.

stopSDK: is a synchronous function, including the manual synchronization with the RUI Server (if requested), returning when all functionality is completed.

Parameters:

doSync (int32_t) - Determines if the Revulytics Usage Intelligence SDK will Synchronize with the Revulytics Usage Intelligence server

when exiting the Revulytics Usage Intelligence SDK. Normally, doSync is set to RUI_SDK_STOP_SYNC_INDEFINITE_WAIT. Possible values

* -1 : Do not perform a manual synchronization with the RUI Server as part of the stop. RUI_SDK_STOP_NO_SYNC
*  0 : Perform a manual synchronization with the RUI Server as part of the stop; wait indefinitely for completion. RUI_SDK_STOP_SYNC_INDEFINITE_WAIT
* >0 : Perform a manual synchronization with the RUI Server as part of the stop; wait only doSync seconds for completion.

Return Type:

One of the constant return values with the following possible values:

* RUI_OK                                        Function successful
* 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.  StopSDK and DestroySDK are possible.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED                           SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_INVALID_DO_SYNC_VALUE                     The doSync manual sync flag/limit violates its allowable range.

(RUIRESULTOBJC) startSession: (NSString*)sessionID

Starts an explicit session for event tracking in the RUI SDK. Must be paired with a call to stopSession:. Explicit sessions are allowed only if createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: was called with multiSessionEnabled = true. When explicit sessions are enabled, a valid sessionID becomes a required parameter to the event tracking APIs.

The content of a sessionID is conditioned and validated (after conditioning) with the following rules:

* Conditioning: All leading white space is removed.
* Conditioning: All trailing white space is removed.
* Conditioning: All internal white spaces other thanspace characters (' ') are removed.
* Validation: Cannot be shorter than 10 UTF-8 characters.
* Validation: Cannot be longer than 64 UTF-8 characters.

The resulting conditioned and validated sessionID must be unique (i.e. not already in use).

NOTE: With the above conditioning, two sessionID’s that differ only by white space or after the 64th character, will not be unique. A sessionID should not be re-used for different sessions.

startSession: can be called between startSDK and stopSDK:, and can be called zero or more times.

startSession: is a synchronous function, returning when all functionality is completed.

Parameters:

sessionID (NSString*) - The client-created valid and unique session ID to be registered as a new session start. This same
ID should later be used for event tracking.

Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Function successful
 * 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.  StopSDK and RUISDK destructor 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_NOT_STARTED                           SDK has not been successfully started.
 * RUI_FUNCTION_NOT_AVAIL                        Function is not available.
 * RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
 * RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY     The sessionID is expected to be non-empty, and it was not.
 * RUI_INVALID_SESSION_ID_TOO_SHORT              The sessionID violates its allowable minimum length.
 * RUI_INVALID_SESSION_ID_TOO_LONG               The sessionID violates its allowable maximum length.
 * RUI_INVALID_SESSION_ID_ALREADY_ACTIVE         The sessionID is already currently in use.

(RUIRESULTOBJC) stopSession: (NSString*)sessionID

Stops an explicit session started with startSession:. Explicit sessions are allowed only if createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: was called with multiSessionEnabled = true. Any explicit sessions not ended with a call to stopSession: are automatically ended when stopSDK: is called. In case this method is never called, eventually this session will be considered as "timed-out", and the time of the last recorded event will be assumed to be the time when the last event was recorded.

stopSession: can be called between startSDK and stopSDK:, and can be called zero or more times.

stopSession: is a synchronous function, returning when all functionality is completed.

Parameters:

sessionID (NSString*) - This parameter should contain a unique ID that refers to the user session that is being started. This same
ID should later be used for event tracking.

Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Function successful
* 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.  StopSDK and DestroySDK 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_NOT_STARTED                           SDK has not been successfully started.
* RUI_FUNCTION_NOT_AVAIL                        Function is not available.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY     The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT              The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG               The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE             The sessionID is not currently in use.

Caching and Synchronizing

The Revulytics Usage Intelligence SDK was designed to minimize network traffic and load on the end user’s machine. In order to do this, all the collected architecture info and runtime tracking data is cached locally and then compressed and sent to the Revulytics Usage Intelligence server in batches at various intervals whenever appropriate. Log data is usually sent at least once for every runtime session (during stopSDK:), however this may vary based on the type of application and usage activity.

Data may be sent via HTTP (port 80) or HTTPS (port 443) depending on application preference. When data is sent over HTTP, AES encryption is used to encrypt the data payload. When data is sent on HTTPS, normal HTTPS security measures are used. The application may also choose to start with HTTPS communication and if blocked or unsuccessful the RUI SDK will fall back to using encrypted HTTP.

Forced Synchronization

Under normal conditions, you do not need to instruct the Revulytics Usage Intelligence SDK when to synchronize with the cloud server, since this happens automatically and is triggered by application interaction with the API. In a typical runtime session, the SDK will always attempt to synchronize with the server at least once whenever the application calls stopSDK:. For long running applications, the RUI SDK will periodically sync with the server every 20 minutes.

For applications that require a more customized synchronization, the API also provides an option to request manual synchronization of all cached data. This is done by calling the sync function.

(RUIRESULTOBJC) sync: (BOOL)getReachout

Performs a manual synchronization with the RUI Server. The RUI SDK periodically performs automatic synchronizations with the RUI Server. sync: provides the client an ability to explicitly synchronize with the RUI Server at a specific time. The manual synchronization can request a ReachOutTM with getReachOut. NOTE: Similar to reachOutOnAutoSync setting (createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:), the ReachOutTM will not be requested if there is no registered handler (initRegisterDefaultGraphicalReachOutHandler: and setReachOutHandler:).

sync: can be called between startSDK and stopSDK: and can be called zero or more times. NOTE: sync: will not be successful if a New Registration is in progress (i.e. createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: and startSDK). A manual synchronization with the RUI Server can be associated with stopSDK:.

sync: is an asynchronous function returning immediately with further functionality executed on separate thread(s).

Parameters:

getReachout (BOOL) - This parameter instructs the server whether to send a ReachOutTM message during this particular sync if available.

Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Synchronous functionalitysuccessful
* 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.  StopSDK and DestroySDK 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_NOT_STARTED                           SDK has not been successfully started.
* RUI_SYNC_ALREADY_RUNNING                      A sync with the RUI Server is already running.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_TIME_THRESHOLD_NOT_REACHED                The API call frequency threshold (set by the RUI Server) has not been reached.