Package com.sap.cloud.mobile.foundation.usage

Class AppUsage

  • All Implemented Interfaces:
    
public final class AppUsage

    The mobile services server supports a specific format of usage data and event types. Its client usage implementation, AppUsage, follows the Usage Framework API (Usage) and provides simplified utility methods and encrypted usage store.

    1. Initializing AppUsage-- A one-time initialization is required via initialize. It is recommended to use EncryptionUtil to obtain the encryption key. If this is the first time AppUsage is being initialized and null is provided as the encryption key, an encryption key will be generated transparently and will be used for subsequent initialize calls. 

    
    // Application Id and version will be used during upload to form the mobile services URL.

    byte[] encryptionKey = EncryptionUtil.getEncryptionKey("aliasForAppUsage", myPasscode);
    AppUsage.initialize(appContext, "myUsageStore", settingsParameter, encryptionKey);

    2. Reporting-- All usage reported will be persisted to a encrypted backing store. The reporting needs to begin with a sessionStart, followed by one or more event() or pairs of eventStart() and eventEnd() methods, then end with a sessionEnd method.

    Repeat these method call sequences if you want to have multiple report sessions.

    If the sessionStart() or sessionEnd() method is missing, all events reported will be skipped.

    Use one of the event() methods if you know the duration. Otherwise, use a pair of eventStart() and eventEnd() methods, and the duration will be calculated for you.

    The system default target ID will be used when a target ID is not specified for the reporting methods. 

    
    // 1. Marks the beginning of a Session.
    AppUsage.sessionStart();

    // 2. Adds one or more events.
    AppUsage.event(
        "eventType1",          // Event type, optional.
        "testEvent1Key",       // Event key. When not specified, 'other' will be used.
        4L,                    // Duration.
        new AppUsageInfo()      // Event details using AppUsageInfo.
            .screen("firstScreen")  // Chained method from AppUsageInfo.
            .value("randomValue")); // Chained method from AppUsageInfo.

    AppUsage.event(
        null,                  // Null event type.
        "testEvent2Key",
        4L,
        new AppUsageInfo()
            .screen("second screen")
            .category("value2"));

    // Or use eventStart and eventEnd pairs, the duration will be calculated for you.
    AppUsage.eventStart(
        "eventType2",
        "key1",
        new AppUsageInfo()
            .screen("third screen")
            .value("value2"));
    AppUsage.eventEnd(
        "eventType2",
        "key1",
        new AppUsageInfo()
        .measurement("measurement"));

    AppUsage.eventStart( // The default event key 'other' is used when no key is specified.
        "eventType3",
        "key3",
        new AppUsageInfo()
            .screen("home")
            .others("otherValue"));
    AppUsage.eventEnd(
        "eventType3",
        "key3",
        new AppUsageInfo()
            .screen("home")
            .others("otherValue"));

    // Marks the end of a session. Can have more than one sessions using pairs of sessionStart()
    // and sessionEnd().
    AppUsage.sessionEnd();

    3. Uploading-- Before using AppUsageUploader, you need to enable the server to upload application-specific usage statistics and reports from mobile devices.

    See Defining Usage Report Policy.

    AppUsageUploader runs in an AsyncTask, it retrieves the snapshot from the usage store, converts the usage records to the format required by mobile services, then uploads them to the server. 

    
    // Establishes a connection to mobile services using okHttpClient.

    ....

    // Uploads to the server.
    AppUsageUploader.upload(okHttpClient, targetID);

    4. Viewing Usage Reports on Server-- After successful client data upload, you can find your reports on the server.

    See Viewing Client Usage Reports.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Field Summary

      Fields 
      Modifier and Type Field Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Method Summary

      Modifier and Type Method Description
      static void initialize(@NonNull() Context context, @NonNull() String storeName, @NonNull() SettingsParameters settingsParameters, @Nullable() Array<byte> encryptionKey) Initializes the mobile services usage.
      static void initialize(@NonNull() Context context, @NonNull() String storeName, @Nullable() Array<byte> encryptionKey) Initializes the mobile services usage.
      static boolean isInitialized() Checks if AppUsage has been initialized.
      static void changeEncryptionKey(@Nullable() Array<byte> newEncryptionKey) Changes the encryption key of the store while the store is open.
      static void sessionStart(@NonNull() String targetId) Reports a SESSION_START event for the specified targetID.
      static void sessionStart() Reports a SESSION_START event for the system default targetID.
      static void sessionEnd(@NonNull() String targetId) Reports a SESSION_END event for the specified targetID.
      static void sessionEnd() Reports a SESSION_END event for the system default targetID.
      static void event(@NonNull() String targetId, @Nullable() String type, @Nullable() String key, @Nullable() Long duration, @NonNull() AppUsageInfo info) Reports an EVENT event for the system default targetID.
      static void event(@Nullable() String type, @Nullable() String key, @Nullable() Long duration, @NonNull() AppUsageInfo info) Reports an EVENT event for the system default targetID.
      static void eventStart(@NonNull() String targetId, @Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info) Reports an EVENT_START event for the system default targetID.
      static void eventStart(@Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info) Reports an EVENT_START event for the system default targetID.
      static void eventEnd(@NonNull() String targetId, @Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info) Reports an EVENT_END event for the system default targetID.
      static void eventEnd(@Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info) Reports an EVENT_END event for the system default targetID.
      static void eventBehaviorViewDisplayed(@NonNull() String viewId, @Nullable() String elementId, @Nullable() String action, @Nullable() String interactionValue) Submit a ViewDisplayed analytics behavior event.
      static void eventBehaviorUserInteraction(@NonNull() String viewId, @Nullable() String elementId, @Nullable() String action, @Nullable() String interactionValue) Submit a UserInteraction analytics behavior event.
      static void deleteStore() Deletes the underlying usage persistence store and leaves AppUsage in un-initialized state, that is, isInitialized would return false after calling this method.
      static void enableReporter(@Nullable() String targetId, boolean enable) Enables or disables a usage reporter with the specified target ID.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

    • Method Detail

      • initialize

         static void initialize(@NonNull() Context context, @NonNull() String storeName, @NonNull() SettingsParameters settingsParameters, @Nullable() Array<byte> encryptionKey)

        Initializes the mobile services usage.

        Parameters:
        context - Android application context
        storeName - the name of the usage record persistence store
        settingsParameters - Application ID, device ID, and application version will be retrieved from this object.
        encryptionKey - the key to encrypt the underlying persistence store.

      • initialize

         static void initialize(@NonNull() Context context, @NonNull() String storeName, @Nullable() Array<byte> encryptionKey)

        Initializes the mobile services usage.

        Parameters:
        context - Android application context
        storeName - the name of the usage record persistence store
        encryptionKey - the key to encrypt the underlying persistence store.

      • isInitialized

         static boolean isInitialized()

        Checks if AppUsage has been initialized.

        Returns:

        True if AppUsage has been initialized, false otherwise.

      • changeEncryptionKey

         static void changeEncryptionKey(@Nullable() Array<byte> newEncryptionKey)

        Changes the encryption key of the store while the store is open.

        Parameters:
        newEncryptionKey - new encryption key.

      • sessionStart

         static void sessionStart(@NonNull() String targetId)

        Reports a SESSION_START event for the specified targetID.

        Parameters:
        targetId - target ID of a usage reporter

      • sessionStart

         static void sessionStart()

        Reports a SESSION_START event for the system default targetID.

      • sessionEnd

         static void sessionEnd(@NonNull() String targetId)

        Reports a SESSION_END event for the specified targetID.

        Parameters:
        targetId - target ID of a usage reporter

      • sessionEnd

         static void sessionEnd()

        Reports a SESSION_END event for the system default targetID.

      • event

         static void event(@NonNull() String targetId, @Nullable() String type, @Nullable() String key, @Nullable() Long duration, @NonNull() AppUsageInfo info)

        Reports an EVENT event for the system default targetID.

        Parameters:
        targetId - target ID of a usage reporter
        type - type of the event
        key - event key.
        duration - duration of the event in milliseconds as Long.
        info - a map of additional attributes that should be reported for the event

      • event

         static void event(@Nullable() String type, @Nullable() String key, @Nullable() Long duration, @NonNull() AppUsageInfo info)

        Reports an EVENT event for the system default targetID.

        Parameters:
        type - type of the event
        key - event key.
        duration - duration of the event in milliseconds as Long.
        info - a map of additional attributes that should be reported for the event

      • eventStart

         static void eventStart(@NonNull() String targetId, @Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info)

        Reports an EVENT_START event for the system default targetID.

        Note that the user needs to call eventEnd (or its variant) with the same key, and the time between the reported EVENT_START and EVENT_END will be calculated as the duration.

        If eventEnd method is not called, this EVENT_START will be ignored.

        Parameters:
        targetId - target ID of a usage reporter
        type - type of the event
        key - event key.
        info - a map of additional attributes that should be reported for the event

      • eventStart

         static void eventStart(@Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info)

        Reports an EVENT_START event for the system default targetID.

        Note that the user needs to call eventEnd (or its variant) with the same key, and the time between the reported EVENT_START and EVENT_END will be calculated as the duration.

        If eventEnd method is not called, this EVENT_START will be ignored.

        Parameters:
        type - type of the event
        key - event key.
        info - a map of additional attributes that should be reported for the event

      • eventEnd

         static void eventEnd(@NonNull() String targetId, @Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info)

        Reports an EVENT_END event for the system default targetID.

        Note that before calling this method, eventStart (or one of its variant) must be called, otherwise, this EVENT_END will be discarded.

        The time between the reported EVENT_START and EVENT_END will be calculated as the duration.

        Parameters:
        targetId - target ID of a usage reporter
        type - type of the event
        key - event key.
        info - a map of additional attributes that should be reported for the event

      • eventEnd

         static void eventEnd(@Nullable() String type, @Nullable() String key, @NonNull() AppUsageInfo info)

        Reports an EVENT_END event for the system default targetID.

        Note that before calling this method, eventStart (or one of its variant) must be called, otherwise, this EVENT_END will be discarded.

        The time between the reported EVENT_START and EVENT_END will be calculated as the duration.

        Parameters:
        type - type of the event
        key - event key.
        info - a map of additional attributes that should be reported for the event

      • eventBehaviorViewDisplayed

         static void eventBehaviorViewDisplayed(@NonNull() String viewId, @Nullable() String elementId, @Nullable() String action, @Nullable() String interactionValue)

        Submit a ViewDisplayed analytics behavior event.

        Parameters:
        viewId - Screen/View name
        elementId - interacted UI Element or on screen control
        action - user performed action
        interactionValue - value related to the interaction, if applicable

      • eventBehaviorUserInteraction

         static void eventBehaviorUserInteraction(@NonNull() String viewId, @Nullable() String elementId, @Nullable() String action, @Nullable() String interactionValue)

        Submit a UserInteraction analytics behavior event. For example, a Button-click or row select.

        Parameters:
        viewId - Screen/View name
        elementId - interacted UI Element or on screen control
        action - user performed action.
        interactionValue - value related to the interaction, if applicable.

      • deleteStore

         static void deleteStore()

        Deletes the underlying usage persistence store and leaves AppUsage in un-initialized state, that is, isInitialized would return false after calling this method.

      • enableReporter

         static void enableReporter(@Nullable() String targetId, boolean enable)

        Enables or disables a usage reporter with the specified target ID.

        Parameters:
        targetId - target ID of a usage reporter.
        enable - Enables the reporter if true.