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)
Change the data encryption key of the usage database.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
oldKey |
<optional> |
the old key of the usage database, can be null. | |
newKey |
<optional> |
the new key of the usage database, can be null. |
Example
sap.Usage.changeEncryptionKey("abc", "123", function(result) {}, function(error) {});(static) checkExistence()
Checks whether the usage database was initialized. The result of the check will be returned as argument of the successCallback.
Example
sap.Usage.ischeckExistence(function(result) { console.log("Usage database status" + result);}, function(error) {console.log("Something went wrong" + error);});(static) destroy()
Deletes the usage database.
Example
sap.Usage.destroy(function(result) {}, function(error){});(static) getReports()
Returns Json representation of every Usage data stored locally in the argument of the success callback.
Example
sap.Usage.getReports(function(reports) { console.log(reports); }, errorCallback);(static) getUserConsent()
Returns the cached value of user consent boolean as it was last set or retrieved by the Usage plugin.
This does not necessarily match the actual value stored by AppPreferences, but will be the same
as long as the preference is not modified without using this plugin to do so.
Example
sap.Usage.getUserConsent();(static) getUserConsent({callback})
Returns the value of user consent boolean stored in local storage depending on whether the user has given consent to data collection.
Parameters:
| Name | Type | Description |
|---|---|---|
{callback} |
function | callback to be run if user consent value is successfully found |
Example
sap.Usage.getUserConsent(callback);(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()
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.
Example
sap.Usage.isInitialized(function(result) { console.log("Usage initialization status" + result);}, function(error) {console.log("Something went wrong" + error);});(static) log(keyopt, infoopt, typeopt)
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 |
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})
* 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 |
Example
sap.Usage.makeTimer('timerKey', function(timerID) {alert("Timer with key " + timerKey + " and ID " + result + " successfully started."); }, errorCallback);(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);(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 Upon successful completion the successCallback function will be called with "OK".({timerid}, {info}, {type{)
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.
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 |
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})
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 |
Example
infoType.setView("Custom View").setResult("Time end called");
sap.Usage.timeEnd(timerKey, infoType, "Timer", successCallback, errorCallback);(static) timeStart Upon successful completion the successCallback function will be called with "OK".({key})
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.
Parameters:
| Name | Type | Description |
|---|---|---|
{key} |
String | The key for the timer to create, must be not null. |
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 |
boolean | true if the Usage initialization was successfull, false otherwise |