Usage

The usage plugin enables the recording and uploading of tracing and timing events in an application. Some basic app information is automatically recorded such as device platform, device version and application connection ID. This information is saved in a database on the device and periodically uploaded to the CPms or SMP server. A UI screen is provided that enables users to opt in or out for this data collection.

For additional details on the Usage plugin, see C:\SAP\MobileSDK3\KapselSDK\docs\api\sap.Usage.html, Usage plugin or Client Usage Reporting.

The following steps will demonstrate this plugin.

  • Add the usage plugin.
    cd C:\Kapsel_Projects\KapselGSDemo
    cordova plugin add kapsel-plugin-usage --searchpath %KAPSEL_HOME%/plugins
    
    or on a Mac 
    cd ~/Documents/Kapsel_Projects/KapselGSDemo 
    cordova plugin add kapsel-plugin-usage --searchpath $KAPSEL_HOME/plugins
    
  • Modify index.html. Add the following code below var resumeTime;
    var readTimerID = null;
    var startUpTime = null;
    ...
    
    

    Modify the logonSuccessCallback and add the following line below var endTime2 = new Date();

    function logonSuccessCallback(result) {
        ...
        startUpTime = ((endTime2 - t0)/1000).toFixed(3);
        ...
    

    Add the following methods.

    function makeTimerSuccessCallback(result) {
        console.log("EventLogging:  makeTimerSuccess");
        readTimerID = result;
    }
    
    function stopTimerSuccessCallback(result) {
        console.log("EventLogging:  stopTimerSuccess");
    }
    
    function showConsentCallback() {
        var consent = sap.Usage.getUserConsent(getUserConsentCallback);
    }
    
    function getUserConsentCallback(consentGiven) {
        console.log("EventLogging: Consent for usage collection is: " + consentGiven);
        if (consentGiven) {
            initUsagePlugin();
        }
    }
    
    function initUsagePlugin() {
        var host = applicationContext.registrationContext.serverHost;
        var port = applicationContext.registrationContext.serverPort;
        var path = '/clientusage';
        s = "";
        if (applicationContext.registrationContext.https) { 
            s = "s"
        };
        var uploadUrl = "http" + s + '://' + host + ":" + port + path;
        var timeFor3GUpload = 0;
        sap.Usage.init(uploadUrl, "myEncryptionKey", 1 /* how often to upload */, usageInitSuccessCallback, errorCallback);
    }
    
    function usageInitSuccessCallback(status) {
        console.log("EventLogging: Successfully initialized the Usage plugin");
    }
    
    function usageReportsCallback(usageData) {
        console.log("EventLogging: " + usageData);
        alert(usageData);
    }
    
    function onUsageInitialized(initialized) {
        if (initialized.detail.args) {
            console.log("EventLogging: onUsageInitialized");
            var info = new sap.Usage.InfoType();
            info.setMeasurement(startUpTime);
            info.setResult("App started in  " + startUpTime + " seconds");
            sap.Usage.log("startUpTime", info, "startUpTimer");
            console.log("EventLogging: Added startup time to usage");
        }
        else {
            alert("Usage initialization failed");
        }
    }
    
    document.addEventListener("onUsageInitialized", onUsageInitialized, false);

    Add the following code to the read method to start a timer.

    function read() {
        sap.Usage.makeTimer("readTimerKey", makeTimerSuccessCallback, errorCallback);
        ...
    }
    

    At the end of the method readSuccessCallback add the following methods to stop the timer.

    function readSuccessCallback(data, response) {
        ...
        var info = new sap.Usage.InfoType();
        info.setResult("Read " + data.results.length + " records");
        sap.Usage.stopTimer(readTimerID, info, "readTimer", stopTimerSuccessCallback, errorCallback);       
    }
    ...
    <button id="showConsent" onclick="sap.Usage.showConsentDialog(showConsentCallback)">Show Consent Dialog</button>
    <button id="getUsage" onclick="sap.Usage.getReports(usageReportsCallback)">Show Usage Data</button>
    
  • In the management cockpit, enable log upload for all new registrations and turn off the upload report after X days by setting the value to 0.
    Applications > com.kapsel.gs > Client Policies > Usage Report Policy
  • Delete the app if it is already installed on a device.Prepare, build and deploy the app with the following command.
    cordova run android
    or
    cordova run ios
  • Notice that after registration, a new screen is showing asking if the user wishes to opt in for usage collection to help improve the application. Press Allow to opt in for usage collection.
    Register, then press the Read button. Remove the app from memory and reopen the app while using WI-FI which should trigger the usage log to be uploaded to the server. Note the usage report should also be uploaded if using cellular data connection as the Upload Usage Report After was set to 0 but as of SP 14, this only works over WI-FI.
  • In the management cockpit, under Reporting > Client Log Data, examine the available charts based off of the collected usage data.
    After choosing Download, examine the collected and uploaded usage content for the application.Notice that there is a set of default data that is collected which includes the application ID, device model, platform, version, registration ID, and session ID.
    The first record shows when the user consented to data collection.
    The second record indicates the time taken for the app to start. Note this time requires making a change to MainActivity.java and is covered further at Timing and Performance.
    The third record indicates the time taken for the OData read call.
    The fourth record is a user session timer and records how long the application was open for. This is automatically provided by the usage plugin.

Back to Getting Started With Kapsel

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply