Namespace: Usage

sap. Usage

Provides usage support. The purpose of this plugin is to enable administrators to view and generate reports on application usage KPI's, across dimensions of device type & version, operating system type & version, and sdk type & version.

Classes

InfoType
PrivacyPolicy

Methods

(static) changeEncryptionKey(oldKeyopt, newKeyopt, successCallback, errorCallback)

Change the data encryption key of the usage database.
Parameters:
Name Type Attributes Description
oldKey String <optional>
the old key of the usage database, can be null
newKey String <optional>
the new key of the usage database, can be null
successCallback function callback invoked on success
errorCallback function callback invoked on error
Example
sap.Usage.changeEncryptionKey("abc", "123", function(result) {}, function(error) {});

(static) checkExistence(successCallback, errorCallback)

Checks whether the usage database was initialized. The result of the check will be returned as argument of the successCallback.
Parameters:
Name Type Description
successCallback function callback invoked on success with the result as parameter
errorCallback function callback invoked on error
Example
sap.Usage.checkExistence(function(result) { console.log("Usage database status" + result);}, function(error) {console.log("Something went wrong" + error);});

(static) destroy(successCallback, errorCallback)

Deletes the usage database.
Parameters:
Name Type Description
successCallback function callback invoked on success
errorCallback function callback invoked on error
Example
sap.Usage.destroy(function(result) {}, function(error){});

(static) getPrivacyPolicies()

Gets all privacy policies, including the SAP-specific policy. If multiple policies have the same id, only the latest will be included.
Returns:
an array of privacy policies
Example
sap.Usage.getPrivacyPolicies();

(static) getReports(successCallback, errorCallback)

Returns Json representation of every Usage data stored locally in the argument of the success callback.
Parameters:
Name Type Description
successCallback function the callback invoked on success with the reports as parameter
errorCallback function callback invoked on error
Example
sap.Usage.getReports(function(reports) { console.log(reports); }, errorCallback);

(static) getSapPrivacyPolicy()

Gets the SAP-specific privacy policy.
Returns:
privacy policy with sap ID
Example
sap.Usage.getSapPrivacyPolicy();

(static) getUserConsent(successCallback, errorCallback)

A function to asynchonously get the value of user consent setting stored in secure storage depending on whether the user has given consent to data collection. Null means the user has not been asked.
Parameters:
Name Type Description
successCallback function callback to be run if user consent value is successfully found. The value given to the success callback will be either true, false, or null. True or false indicates the user has given consent or denied consent for usage collection. Null indicates the usage consent screen has not be shown to the user, so they haven't accepted or denied.
errorCallback function callback to be run if an error occured
Example
sap.Usage.getUserConsent(successCallback, errorCallback);

(static) init(uploadEndpointopt, dataEncryptionKeyopt, timeFor3GUploadopt, successCallbackopt, errorCallbackopt)

Initialize usage plugin. Note that this initialize call happens automatically if you have Logon plugin. - In that case the use of this method is not recommended due to race condition. - An application can subscribe to the 'onUsageInitialized' event ( sap.Usage.onInitializedEvent ), which is fired when the Usage has been initialized. (with Logon plugin only)
Parameters:
Name Type Attributes Description
uploadEndpoint String <optional>
fully qualified URL, pointing to the Hana Mobile servers clientusage log upload endpoint, must be not null
dataEncryptionKey String <optional>
encryption key, to encrypt database content, can be null.
timeFor3GUpload int <optional>
time for 3G upload in days.
successCallback function <optional>
the callback invoked on success
errorCallback sap.Usage.initErrorCb <optional>
the callback invoked on error
Example
sap.Usage.init('uploadEndpoint', 'dataEncryptionKey', 2, function () {
   console.log("Initialization success");
}, function (errorCode, extra) {
   console.log("Initilization failed with error code: " + errorCode);
});

(static) isInitialized(successCallback, errorCallback)

Checks whether the usage was already initialized by calling the Usage.init() method. The result of the check will be returned as argument of the successCallback.
Parameters:
Name Type Description
successCallback function the callback invoked on success with the result as parameter
errorCallback function callback invoked on error
Example
sap.Usage.isInitialized(function(result) { 
    console.log("Usage initialization status" + result);
}, function(error) {
    console.log("Something went wrong" + error);
});

(static) loadAdditionalPrivacyPolicies(successCallbackopt, errorCallbackopt)

Loads any additional privacy policies stored in AppPreferences.
Parameters:
Name Type Attributes Description
successCallback function <optional>
the callback invoked on success
errorCallback function <optional>
the callback invoked on error

(static) log(keyopt, infoopt, typeopt, successCallback, errorCallback)

Log timestamps for specific events. Upon successful completion the successCallback function will be called with "OK".
Parameters:
Name Type Attributes Description
key String <optional>
identifies the usage entry, must be not null
info sap.Usage.InfoType <optional>
A value object containing several predefined elements, will be also logged in the record, can be null
type String <optional>
the type of the event, can be null
successCallback function callback invoked on success
errorCallback function callback invoked on error
Example
var infoType = new sap.Usage.InfoType();
infoType.setScreen("1").setView("2").setAction("3");
sap.Usage.log("Test logging", infoType, "Sample type", successCallback, errorCallback);

(static) makeTimer(key, successCallback, errorCallback)

* Starts a timer with a specific key. If a timer was already started with the same key, a new timer will be initialized. If a timer started Successfully, the timerId will be returned through the successCB callback function parameter.
Parameters:
Name Type Description
key String The identifier for the timer, must be not null
successCallback function callback invoked on success
errorCallback function callback invoked on error
Example
sap.Usage.makeTimer(timerKey, function(timerID) {
    alert("Timer with key " + timerKey + " and ID " + timerID + " successfully started.");
}, errorCallback);

(static) setAdditionalPrivacyPolicies(policiesopt, successCallbackopt)

Sets the list of additional privacy policies and stores in AppPreferences.
Parameters:
Name Type Attributes Description
policies Array <optional>
the list of additional privacy policies.
successCallback function <optional>
the callback invoked on success

(static) setUserConsent(value, callback)

Sets a variable in localStorage regarding whether a particular user has given consent to data collection. If a value of false is sent by the user, the Usage database is destroyed to ensure that data collection stops as soon as user opts out of having their usage data collected Note the user parameter here is used as a key for local storage, so it is assumed that all user keys.
Parameters:
Name Type Description
value boolean sets the user consent value to true / false
callback function callbacks to be run after setUserContent succeeded
Example
sap.Usage.setUserConsent(true, callback);

(static) showConsentDialog(consentCallback)

Generates a pre-made dialog box which asks the user for consent to data collection. The result is automatically stored.
Parameters:
Name Type Description
consentCallback function callback to be run after the user clicks either "Allow" or "Deny"
Example
sap.Usage.showConsentDialog(consentCallback);

(static) stopTimer(timerid, info, type, successCallback, errorCallback)

Stop a timer. Multiple stop calls on the same Timer instance is allowed. If the timer object was not initialized correctly, no further result will occur. Upon successful completion the successCallback function will be called with "OK".
Parameters:
Name Type Description
timerid String The identifier for timer to stop. This value is obtained in the makeTimer call, must be not null
info sap.Usage.InfoType A value object containing several predefined elements, will be also logged in the record, can be null
type String type of the recorded event
successCallback function callback invoked on success
errorCallback function callback invoked on error
Example
var infoType = new sap.Usage.InfoType();
infoType.setAction("Timer stopped").setBehavior("normal").setCase("sample");
sap.Usage.stopTimer(timerID, infoType, "Sample timer", successCallback, errorCallback);

(static) timeEnd(key, info, type, successCallback, errorCallback)

Stops the timer identified by the key argument. If the timer was already stopped by a previous method call, or the timer was not initialized by timeStart, no further result will occur. Upon successful completion the successCallback function will be called with "OK".
Parameters:
Name Type Description
key String The key for the timer to end, must be not null.
info sap.Usage.InfoType A value object containing several predefined elements. The content of the info, will be also stored in the record, to allow more specific queries. Can be null.
type String type of the recorded event, can be null
successCallback function callback invoked on success
errorCallback function callback invoked on error
Example
infoType.setView("Custom View").setResult("Time end called");
sap.Usage.timeEnd(timerKey, infoType, "Timer", successCallback, errorCallback);

(static) timeStart(key, successCallback, errorCallback)

Starts a timer with a specific key. If a timer was already started with the same key, a new timer will be initialized and the old timer will be deleted. Upon successful completion the successCallback function will be called with "OK".
Parameters:
Name Type Description
key String The key for the timer to create, must be not null.
successCallback function callback invoked on success
errorCallback function callback invoked on error
Example
sap.Usage.timeStart('keyvalue', successCallback, errorCallback);

Type Definitions

initErrorCb(errorCode, extraopt)

Error callback upon initialization error Error codes: already_initialized
Parameters:
Name Type Attributes Description
errorCode String the initialization error
extra String <optional>
information associated with the error

onInitializedEvent(initialized)

Initialization event
Parameters:
Name Type Description
initialized CustomEvent contains property initialized.detail.args which is true if the Usage initialization was successful, false otherwise
Example
document.addEventListener('onUsageInitialized', function(initialized) {
    if (initialized.detail.args)
        console.log('Usage is initialized');
    else
        console.log('Usage is not initialized');
});