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
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');
});