Class UsageService
-
- All Implemented Interfaces:
public final class UsageService extends MobileService
Represents the usage service to handle all usage related tasks.
By default, UsageService will manage the usage session automatically, An event of 'session start' event will be recorded in the following cases:
the usage service is started again with startUsageBroker, at this time, a new session will be started after ending the old one.
recording events with the functions start with 'event', or logDeviceInfoEvents if there is no open session.
An event of 'session end' will be recorded when the app is put into background, or the usage service is stopped with stopUsageBroker.
The client code can also disable the 'auto session' feature at any time. If 'auto session' feature is disabled, using any of the event log functions here will also log a 'session start' automatically if no session started yet. But it's the client code's responsibility to record the session start and session end event.
When uploading the usage data, the current session without a 'session end' will NOT be uploaded. By default, UsageService also enables the 'auto upload' feature. The 'auto upload' might happen after a 'session end' is recorded and the record count exceeds the threshold of recordCount.
After a 'session start' event recorded, functions like eventStart, event, eventEnd, eventBehaviorUserInteraction, eventBehaviorViewDisplayed and logDeviceInfoEvents can be used to log events.
eventStart and eventEnd can help the client code determine the duration of a group operations. To use this feature, make sure the two functions are invoked with the same 'key' argument value. for example:
SDKInitializer.getService(UsageService::class)?.also { srv -> srv.eventStart(key = EVENT_KEY, info = AppUsageInfo().screen(VIEW_ID)) srv.eventBehaviorUserInteraction( viewId = VIEW_ID, action = item.title.toString() ) srv.event(key = EVENT_KEY, info = AppUsageInfo().action("test_event_action")) srv.eventEnd(key = EVENT_KEY, info = AppUsageInfo().action("test_event_end_action")) }
-
-
Field Summary
Fields Modifier and Type Field Description private Boolean
userConsented
private Application
application
private String
apiKey
-
Constructor Summary
Constructors Constructor Description UsageService(Boolean autoSession, Boolean autoUpload, Integer recordCount, Integer uploadAfterDays, UUID storeName)
UsageService(Boolean autoSession, Boolean autoUpload, Integer recordCount, Integer uploadAfterDays)
UsageService(Boolean autoSession, Boolean autoUpload, Integer recordCount)
UsageService(Boolean autoSession, Boolean autoUpload)
UsageService(Boolean autoSession)
UsageService()
-
Method Summary
Modifier and Type Method Description final Boolean
getUserConsented()
The service does not maintain the user consent by itself, the client code needs to update this before starting the service, for example, when a new user onboarded, or switching to another user in the multiple user mode app. final Unit
setUserConsented(Boolean userConsented)
The service does not maintain the user consent by itself, the client code needs to update this before starting the service, for example, when a new user onboarded, or switching to another user in the multiple user mode app. Unit
init(Application application, String apiKey)
Initializes the mobile service Unit
onStateChange(ApplicationState state)
Notified when application state changes. Unit
reset()
Resets the usage service, deletes all the usage databases. final Unit
updateUsagePolicy(UsagePolicy policy)
Updates the usage policy. final UsageService
setStoreName(UUID storeName)
Sets the usage store name. final UsageService
setAutoSession(Boolean autoSession)
Specifies whether auto session will be used. final UsageService
setAutoUpload(Boolean autoUpload)
Specifies whether auto upload will be used. final UsageService
setUploadThresholdKB(Integer sizeOfKB)
Specifies the record size that will trigger usage auto upload. final Unit
startUsageBroker()
Starts the usage broker if it was not started yet. final Unit
stopUsageBroker(Boolean reset)
Stops the usage broker if it was started. final Unit
stopUsageBroker()
Stops the usage broker if it was started. final Boolean
isUsageServiceStarted()
Checks whether usage service is starting or not final Unit
eventBehaviorViewDisplayed(String viewId, String elementId, String action, String interactionValue)
Submits a ViewDisplayed analytics behavior event. final Unit
eventBehaviorViewDisplayed(String viewId, String elementId, String action)
Submits a ViewDisplayed analytics behavior event. final Unit
eventBehaviorViewDisplayed(String viewId, String elementId)
Submits a ViewDisplayed analytics behavior event. final Unit
eventBehaviorViewDisplayed(String viewId)
Submits a ViewDisplayed analytics behavior event. final Unit
eventBehaviorUserInteraction(String viewId, String elementId, String action, String interactionValue)
Submits a UserInteraction analytics behavior event. final Unit
eventBehaviorUserInteraction(String viewId, String elementId, String action)
Submits a UserInteraction analytics behavior event. final Unit
eventBehaviorUserInteraction(String viewId, String elementId)
Submits a UserInteraction analytics behavior event. final Unit
eventBehaviorUserInteraction(String viewId)
Submits a UserInteraction analytics behavior event. final Unit
event(AppUsageInfo info, String type, String key, Long duration)
Records a custom event information. final Unit
event(AppUsageInfo info, String type, String key)
Records a custom event information. final Unit
event(AppUsageInfo info, String type)
Records a custom event information. final Unit
event(AppUsageInfo info)
Records a custom event information. final Unit
eventStart(AppUsageInfo info, String type, String key)
Records an event start. final Unit
eventStart(AppUsageInfo info, String type)
Records an event start. final Unit
eventStart(AppUsageInfo info)
Records an event start. final Unit
eventEnd(AppUsageInfo info, String type, String key)
Records an event end. final Unit
eventEnd(AppUsageInfo info, String type)
Records an event end. final Unit
eventEnd(AppUsageInfo info)
Records an event end. final Unit
recordSessionStart(Context context)
Starts an usage collection session final Unit
recordSessionEnd(Context context)
Ends the current usage collection session final Unit
logDeviceInfoEvents(Context context)
Collects device information event final Unit
deleteStoreByName(String storeName)
Tries to delete the usage store by the given name. final Unit
uploadUsageData(LifecycleOwner owner, ServiceListener<Boolean> listener)
final Unit
uploadUsageData(LifecycleOwner owner)
final Unit
uploadUsageData()
final Unit
uploadUsage(Boolean forceUpload, LifecycleOwner owner, ServiceListener<Boolean> listener, Function1<Integer, Unit> progressReporter)
Uploads the usage data. final Unit
uploadUsage(Boolean forceUpload, LifecycleOwner owner, ServiceListener<Boolean> listener)
Uploads the usage data. final Unit
uploadUsage(Boolean forceUpload, LifecycleOwner owner)
Uploads the usage data. final Unit
uploadUsage(Boolean forceUpload)
Uploads the usage data. final Unit
uploadUsage()
Uploads the usage data. -
Methods inherited from class com.sap.cloud.mobile.foundation.mobileservices.MobileService
enableNetworkPolicy, getApiKey, getApplication, isApplicationInitialized, mayStartNewProcess, setApiKey, setApplication
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
-
Constructor Detail
-
UsageService
UsageService(Boolean autoSession, Boolean autoUpload, Integer recordCount, Integer uploadAfterDays, UUID storeName)
-
UsageService
UsageService(Boolean autoSession, Boolean autoUpload, Integer recordCount, Integer uploadAfterDays)
-
UsageService
UsageService(Boolean autoSession, Boolean autoUpload, Integer recordCount)
-
UsageService
UsageService(Boolean autoSession, Boolean autoUpload)
-
UsageService
UsageService(Boolean autoSession)
-
UsageService
UsageService()
-
-
Method Detail
-
getUserConsented
final Boolean getUserConsented()
The service does not maintain the user consent by itself, the client code needs to update this before starting the service, for example, when a new user onboarded, or switching to another user in the multiple user mode app.
-
setUserConsented
final Unit setUserConsented(Boolean userConsented)
The service does not maintain the user consent by itself, the client code needs to update this before starting the service, for example, when a new user onboarded, or switching to another user in the multiple user mode app.
-
init
Unit init(Application application, String apiKey)
Initializes the mobile service
-
onStateChange
Unit onStateChange(ApplicationState state)
Notified when application state changes. This function will be called on Main thread.
-
reset
Unit reset()
Resets the usage service, deletes all the usage databases.
-
updateUsagePolicy
final Unit updateUsagePolicy(UsagePolicy policy)
Updates the usage policy. This is usually when retrieving the usage policy from the server side and apply the new usage policy.
There are 2 parameters in UsagePolicy related to usage service, the days between 2 uploads and usage enable/disable status. So whether the usage service could be started or not will depend on 2 factors, it's enabled from the server side, and user consents the data collection.
-
setStoreName
final UsageService setStoreName(UUID storeName)
Sets the usage store name.
-
setAutoSession
final UsageService setAutoSession(Boolean autoSession)
Specifies whether auto session will be used.
-
setAutoUpload
final UsageService setAutoUpload(Boolean autoUpload)
Specifies whether auto upload will be used.
-
setUploadThresholdKB
final UsageService setUploadThresholdKB(Integer sizeOfKB)
Specifies the record size that will trigger usage auto upload. Default value is 100 KB.
-
startUsageBroker
final Unit startUsageBroker()
Starts the usage broker if it was not started yet.
-
stopUsageBroker
@JvmOverloads() final Unit stopUsageBroker(Boolean reset)
Stops the usage broker if it was started.
-
stopUsageBroker
@JvmOverloads() final Unit stopUsageBroker()
Stops the usage broker if it was started.
-
isUsageServiceStarted
final Boolean isUsageServiceStarted()
Checks whether usage service is starting or not
-
eventBehaviorViewDisplayed
@JvmOverloads() final Unit eventBehaviorViewDisplayed(String viewId, String elementId, String action, String interactionValue)
Submits a ViewDisplayed analytics behavior event.
-
eventBehaviorViewDisplayed
@JvmOverloads() final Unit eventBehaviorViewDisplayed(String viewId, String elementId, String action)
Submits a ViewDisplayed analytics behavior event.
-
eventBehaviorViewDisplayed
@JvmOverloads() final Unit eventBehaviorViewDisplayed(String viewId, String elementId)
Submits a ViewDisplayed analytics behavior event.
-
eventBehaviorViewDisplayed
@JvmOverloads() final Unit eventBehaviorViewDisplayed(String viewId)
Submits a ViewDisplayed analytics behavior event.
-
eventBehaviorUserInteraction
@JvmOverloads() final Unit eventBehaviorUserInteraction(String viewId, String elementId, String action, String interactionValue)
Submits a UserInteraction analytics behavior event. For example, a Button-click or row select.
-
eventBehaviorUserInteraction
@JvmOverloads() final Unit eventBehaviorUserInteraction(String viewId, String elementId, String action)
Submits a UserInteraction analytics behavior event. For example, a Button-click or row select.
-
eventBehaviorUserInteraction
@JvmOverloads() final Unit eventBehaviorUserInteraction(String viewId, String elementId)
Submits a UserInteraction analytics behavior event. For example, a Button-click or row select.
-
eventBehaviorUserInteraction
@JvmOverloads() final Unit eventBehaviorUserInteraction(String viewId)
Submits a UserInteraction analytics behavior event. For example, a Button-click or row select.
-
event
@JvmOverloads() final Unit event(AppUsageInfo info, String type, String key, Long duration)
Records a custom event information.
-
event
@JvmOverloads() final Unit event(AppUsageInfo info, String type, String key)
Records a custom event information.
-
event
@JvmOverloads() final Unit event(AppUsageInfo info, String type)
Records a custom event information.
-
event
@JvmOverloads() final Unit event(AppUsageInfo info)
Records a custom event information.
-
eventStart
@JvmOverloads() final Unit eventStart(AppUsageInfo info, String type, String key)
Records an event start.
-
eventStart
@JvmOverloads() final Unit eventStart(AppUsageInfo info, String type)
Records an event start.
-
eventStart
@JvmOverloads() final Unit eventStart(AppUsageInfo info)
Records an event start.
-
eventEnd
@JvmOverloads() final Unit eventEnd(AppUsageInfo info, String type, String key)
Records an event end. When generating the data for uploading, the info of the corresponding start event with the same key will be merged with the info of this function, the information in info of this end event will win if both the start and end event have the same information.
-
eventEnd
@JvmOverloads() final Unit eventEnd(AppUsageInfo info, String type)
Records an event end. When generating the data for uploading, the info of the corresponding start event with the same key will be merged with the info of this function, the information in info of this end event will win if both the start and end event have the same information.
-
eventEnd
@JvmOverloads() final Unit eventEnd(AppUsageInfo info)
Records an event end. When generating the data for uploading, the info of the corresponding start event with the same key will be merged with the info of this function, the information in info of this end event will win if both the start and end event have the same information.
-
recordSessionStart
final Unit recordSessionStart(Context context)
Starts an usage collection session
-
recordSessionEnd
final Unit recordSessionEnd(Context context)
Ends the current usage collection session
-
logDeviceInfoEvents
final Unit logDeviceInfoEvents(Context context)
Collects device information event
-
deleteStoreByName
final Unit deleteStoreByName(String storeName)
Tries to delete the usage store by the given name. When the application is being reset, this API can be used to delete usage database for all users.
-
uploadUsageData
@Deprecated(message = "Deprecated since 4.0", replaceWith = @ReplaceWith(imports = {}, expression = "Replaced with 'uploadUsage'"))@JvmOverloads() final Unit uploadUsageData(LifecycleOwner owner, ServiceListener<Boolean> listener)
-
uploadUsageData
@Deprecated(message = "Deprecated since 4.0", replaceWith = @ReplaceWith(imports = {}, expression = "Replaced with 'uploadUsage'"))@JvmOverloads() final Unit uploadUsageData(LifecycleOwner owner)
-
uploadUsageData
@Deprecated(message = "Deprecated since 4.0", replaceWith = @ReplaceWith(imports = {}, expression = "Replaced with 'uploadUsage'"))@JvmOverloads() final Unit uploadUsageData()
-
uploadUsage
@JvmOverloads() final Unit uploadUsage(Boolean forceUpload, LifecycleOwner owner, ServiceListener<Boolean> listener, Function1<Integer, Unit> progressReporter)
Uploads the usage data. To monitor the upload status or progress, owner must be provided, otherwise the provided listener could not work.
- Parameters:
forceUpload
- Whether to upload usage data without honoring the parameter of uploadAfterDaysowner
- It can be either an activity or a fragment which has a lifecycle.listener
- The optional ServiceListener to monitor the upload status.
-
uploadUsage
@JvmOverloads() final Unit uploadUsage(Boolean forceUpload, LifecycleOwner owner, ServiceListener<Boolean> listener)
Uploads the usage data. To monitor the upload status or progress, owner must be provided, otherwise the provided listener could not work.
- Parameters:
forceUpload
- Whether to upload usage data without honoring the parameter of uploadAfterDaysowner
- It can be either an activity or a fragment which has a lifecycle.listener
- The optional ServiceListener to monitor the upload status.
-
uploadUsage
@JvmOverloads() final Unit uploadUsage(Boolean forceUpload, LifecycleOwner owner)
Uploads the usage data. To monitor the upload status or progress, owner must be provided, otherwise the provided listener could not work.
- Parameters:
forceUpload
- Whether to upload usage data without honoring the parameter of uploadAfterDaysowner
- It can be either an activity or a fragment which has a lifecycle.
-
uploadUsage
@JvmOverloads() final Unit uploadUsage(Boolean forceUpload)
Uploads the usage data. To monitor the upload status or progress, owner must be provided, otherwise the provided listener could not work.
- Parameters:
forceUpload
- Whether to upload usage data without honoring the parameter of uploadAfterDays
-
uploadUsage
@JvmOverloads() final Unit uploadUsage()
Uploads the usage data. To monitor the upload status or progress, owner must be provided, otherwise the provided listener could not work.
-
-
-
-