Package com.microsoft.appcenter.analytics

Class Analytics

  • All Implemented Interfaces:
    android.app.Application.ActivityLifecycleCallbacks, com.microsoft.appcenter.AppCenterService, com.microsoft.appcenter.utils.ApplicationLifecycleListener.ApplicationLifecycleCallbacks
    public class Analytics
extends com.microsoft.appcenter.AbstractAppCenterService
    Analytics service.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String LOG_TAG
      TAG used in logging for Analytics.

      • Fields inherited from class com.microsoft.appcenter.AbstractAppCenterService

        mChannel

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void applyEnabledState​(boolean enabled)
      React to enable state change.
      static void enableManualSessionTracker()
      Enable manual session tracker.
      protected com.microsoft.appcenter.channel.Channel.GroupListener getChannelListener()  
      protected java.lang.String getGroupName()  
      static Analytics getInstance()
      Get shared instance.
      java.util.Map<java.lang.String,​com.microsoft.appcenter.ingestion.models.json.LogFactory> getLogFactories()  
      protected java.lang.String getLoggerTag()  
      java.lang.String getServiceName()  
      static AnalyticsTransmissionTarget getTransmissionTarget​(java.lang.String transmissionTargetToken)
      Get a transmission target to use to track events.
      protected long getTriggerInterval()  
      boolean isAppSecretRequired()  
      protected static boolean isAutoPageTrackingEnabled()
      Check if automatic page tracking is enabled.
      static com.microsoft.appcenter.utils.async.AppCenterFuture<java.lang.Boolean> isEnabled()
      Check whether Analytics service is enabled or not.
      void onActivityPaused​(android.app.Activity activity)  
      void onActivityResumed​(android.app.Activity activity)  
      void onConfigurationUpdated​(java.lang.String appSecret, java.lang.String transmissionTargetToken)  
      void onStarted​(android.content.Context context, com.microsoft.appcenter.channel.Channel channel, java.lang.String appSecret, java.lang.String transmissionTargetToken, boolean startedFromApp)  
      static void pause()
      Pauses log transmission.
      protected void post​(java.lang.Runnable runnable)  
      static void resume()
      Resumes log transmission if paused.
      protected static void setAutoPageTrackingEnabled​(boolean autoPageTrackingEnabled)
      If enabled (which is the default), automatic page tracking will call trackPage(String, Map) automatically every time an activity is resumed, with a generated name and no properties.
      static com.microsoft.appcenter.utils.async.AppCenterFuture<java.lang.Void> setEnabled​(boolean enabled)
      Enable or disable Analytics service.
      protected static void setListener​(AnalyticsListener listener)
      Sets an analytics listener.
      static boolean setTransmissionInterval​(int seconds)
      Set transmission interval.
      static void startSession()
      Start a new session if manual session tracker is enabled, otherwise do nothing.
      static void trackEvent​(java.lang.String name)
      Track a custom event with name.
      static void trackEvent​(java.lang.String name, EventProperties properties)
      Track a custom event with name and optional typed properties.
      static void trackEvent​(java.lang.String name, EventProperties properties, int flags)
      Track a custom event with name and optional typed properties.
      static void trackEvent​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> properties)
      Track a custom event with name and optional string properties.
      static void trackEvent​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> properties, int flags)
      Track a custom event with name and optional string properties.
      protected static void trackPage​(java.lang.String name)
      Track a custom page with name.
      protected static void trackPage​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> properties)
      Track a custom page with name and optional properties.

      • Methods inherited from class com.microsoft.appcenter.AbstractAppCenterService

        getEnabledPreferenceKey, getTriggerCount, getTriggerMaxParallelRequests, isInstanceEnabled, isInstanceEnabledAsync, isStarted, onActivityCreated, onActivityDestroyed, onActivitySaveInstanceState, onActivityStarted, onActivityStopped, onApplicationEnterBackground, onApplicationEnterForeground, onStarting, post, postAsyncGetter, setInstanceEnabled, setInstanceEnabledAsync

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface android.app.Application.ActivityLifecycleCallbacks

        onActivityPostCreated, onActivityPostDestroyed, onActivityPostPaused, onActivityPostResumed, onActivityPostSaveInstanceState, onActivityPostStarted, onActivityPostStopped, onActivityPreCreated, onActivityPreDestroyed, onActivityPrePaused, onActivityPreResumed, onActivityPreSaveInstanceState, onActivityPreStarted, onActivityPreStopped

    • Field Detail

      • LOG_TAG

        public static final java.lang.String LOG_TAG
        TAG used in logging for Analytics.
        See Also:
        Constant Field Values

    • Method Detail

      • getInstance

        public static Analytics getInstance()
        Get shared instance.
        Returns:
        shared instance.

      • isEnabled

        public static com.microsoft.appcenter.utils.async.AppCenterFuture<java.lang.Boolean> isEnabled()
        Check whether Analytics service is enabled or not.
        Returns:
        future with result being true if enabled, false otherwise.
        See Also:
        AppCenterFuture

      • setEnabled

        public static com.microsoft.appcenter.utils.async.AppCenterFuture<java.lang.Void> setEnabled​(boolean enabled)
        Enable or disable Analytics service.

        The state is persisted in the device's storage across application launches.

        Parameters:
        enabled - true to enable, false to disable.
        Returns:
        future with null result to monitor when the operation completes.

      • setTransmissionInterval

        public static boolean setTransmissionInterval​(int seconds)
        Set transmission interval. The transmission interval should be between 3 seconds and 86400 seconds (1 day). Should be called before the service is started.
        Parameters:
        seconds - the latency of sending events to Analytics in seconds.
        Returns:
        true if the interval is set, false otherwise.

      • pause

        public static void pause()
        Pauses log transmission. This API cannot be used if the service is disabled. Transmission is resumed:
        • when calling resume().
        • when restarting the application process and calling AppCenter.start again.
        • when disabling and re-enabling the SDK or the Analytics module.

      • resume

        public static void resume()
        Resumes log transmission if paused. This API cannot be used if the service is disabled.

      • setListener

        protected static void setListener​(AnalyticsListener listener)
        Sets an analytics listener.

        Note: it needs to be protected for Xamarin to change it back to public in bindings.

        Parameters:
        listener - The custom analytics listener.

      • isAutoPageTrackingEnabled

        protected static boolean isAutoPageTrackingEnabled()
        Check if automatic page tracking is enabled.

        TODO the backend does not support that service yet, will be public method later.

        Returns:
        true if automatic page tracking is enabled. false otherwise.
        See Also:
        setAutoPageTrackingEnabled(boolean)

      • setAutoPageTrackingEnabled

        protected static void setAutoPageTrackingEnabled​(boolean autoPageTrackingEnabled)
        If enabled (which is the default), automatic page tracking will call trackPage(String, Map) automatically every time an activity is resumed, with a generated name and no properties. Call this method with false if you want to track pages yourself in your application.

        TODO the backend does not support that service yet, will be public method later.

        Parameters:
        autoPageTrackingEnabled - true to let the service track pages automatically, false otherwise (default state is true).

      • trackPage

        protected static void trackPage​(java.lang.String name)
        Track a custom page with name.

        TODO the backend does not support that service yet, will be public method later.

        Parameters:
        name - A page name.

      • trackPage

        protected static void trackPage​(java.lang.String name,
                                java.util.Map<java.lang.String,​java.lang.String> properties)
        Track a custom page with name and optional properties. The name parameter can not be null or empty. Maximum allowed length = 256. The properties parameter maximum item count = 20. The properties keys can not be null or empty, maximum allowed key length = 125. The properties values can not be null, maximum allowed value length = 125. Any length of name/keys/values that are longer than each limit will be truncated.

        TODO the backend does not support that service yet, will be public method later.

        Parameters:
        name - A page name.
        properties - Optional properties.

      • trackEvent

        public static void trackEvent​(java.lang.String name)
        Track a custom event with name.

        The name cannot be null or empty.

        Additional validation rules apply depending on the configured secret.

        For App Center, the name cannot be longer than 256 and is truncated otherwise. For One Collector, the name needs to match the [a-zA-Z0-9]((\.(?!(\.|$)))|[_a-zA-Z0-9]){3,99} regular expression.

        Parameters:
        name - An event name.

      • trackEvent

        public static void trackEvent​(java.lang.String name,
                              java.util.Map<java.lang.String,​java.lang.String> properties)
        Track a custom event with name and optional string properties.

        The name cannot be null or empty.

        The property names or values cannot be null.

        Additional validation rules apply depending on the configured secret.

        For App Center:

        • The event name cannot be longer than 256 and is truncated otherwise.
        • The property names cannot be empty.
        • The property names and values are limited to 125 characters each (truncated).
        • The number of properties per event is limited to 20 (truncated).

        For One Collector:

        • The event name needs to match the [a-zA-Z0-9]((\.(?!(\.|$)))|[_a-zA-Z0-9]){3,99} regular expression.
        • The baseData and baseDataType properties are reserved and thus discarded.
        • The full event size when encoded as a JSON string cannot be larger than 1.9MB.
        Parameters:
        name - An event name.
        properties - Optional properties.

      • enableManualSessionTracker

        public static void enableManualSessionTracker()
        Enable manual session tracker.

      • startSession

        public static void startSession()
        Start a new session if manual session tracker is enabled, otherwise do nothing.

      • trackEvent

        public static void trackEvent​(java.lang.String name,
                              java.util.Map<java.lang.String,​java.lang.String> properties,
                              int flags)
        Track a custom event with name and optional string properties.

        The name cannot be null or empty.

        The property names or values cannot be null.

        Additional validation rules apply depending on the configured secret.

        For App Center:

        • The event name cannot be longer than 256 and is truncated otherwise.
        • The property names cannot be empty.
        • The property names and values are limited to 125 characters each (truncated).
        • The number of properties per event is limited to 20 (truncated).

        For One Collector:

        • The event name needs to match the [a-zA-Z0-9]((\.(?!(\.|$)))|[_a-zA-Z0-9]){3,99} regular expression.
        • The baseData and baseDataType properties are reserved and thus discarded.
        • The full event size when encoded as a JSON string cannot be larger than 1.9MB.
        Parameters:
        name - An event name.
        properties - Optional properties.
        flags - Optional flags. Events tracked with the Flags.CRITICAL flag will take precedence over all other events in storage. An event tracked with this option will only be dropped if storage must make room for a newer event that is also marked with the Flags.CRITICAL flag.

      • trackEvent

        public static void trackEvent​(java.lang.String name,
                              EventProperties properties)
        Track a custom event with name and optional typed properties.

        The name cannot be null or empty.

        The property names or values cannot be null.

        Double values must be finite (NaN or Infinite values are discarded).

        Additional validation rules apply depending on the configured secret.

        For App Center:

        • The event name cannot be longer than 256 and is truncated otherwise.
        • The property names cannot be empty.
        • The property names and values are limited to 125 characters each (truncated).
        • The number of properties per event is limited to 20 (truncated).

        For One Collector:

        • The event name needs to match the [a-zA-Z0-9]((\.(?!(\.|$)))|[_a-zA-Z0-9]){3,99} regular expression.
        • The baseData and baseDataType properties are reserved and thus discarded.
        • The full event size when encoded as a JSON string cannot be larger than 1.9MB.
        Parameters:
        name - An event name.
        properties - Optional properties.

      • trackEvent

        public static void trackEvent​(java.lang.String name,
                              EventProperties properties,
                              int flags)
        Track a custom event with name and optional typed properties.

        The name cannot be null or empty.

        The property names or values cannot be null.

        Double values must be finite (NaN or Infinite values are discarded).

        Additional validation rules apply depending on the configured secret.

        For App Center:

        • The event name cannot be longer than 256 and is truncated otherwise.
        • The property names cannot be empty.
        • The property names and values are limited to 125 characters each (truncated).
        • The number of properties per event is limited to 20 (truncated).

        For One Collector:

        • The event name needs to match the [a-zA-Z0-9]((\.(?!(\.|$)))|[_a-zA-Z0-9]){3,99} regular expression.
        • The baseData and baseDataType properties are reserved and thus discarded.
        • The full event size when encoded as a JSON string cannot be larger than 1.9MB.
        Parameters:
        name - An event name.
        properties - Optional properties.
        flags - Optional flags. Events tracked with the Flags.CRITICAL flag will take precedence over all other events in storage. An event tracked with this option will only be dropped if storage must make room for a newer event that is also marked with the Flags.CRITICAL flag.

      • getTransmissionTarget

        public static AnalyticsTransmissionTarget getTransmissionTarget​(java.lang.String transmissionTargetToken)
        Get a transmission target to use to track events. Will create a new transmission target if necessary.
        Parameters:
        transmissionTargetToken - A string to identify a transmission target.
        Returns:
        a transmission target.

      • isAppSecretRequired

        public boolean isAppSecretRequired()
        Specified by:
        isAppSecretRequired in interface com.microsoft.appcenter.AppCenterService
        Overrides:
        isAppSecretRequired in class com.microsoft.appcenter.AbstractAppCenterService

      • getGroupName

        protected java.lang.String getGroupName()
        Specified by:
        getGroupName in class com.microsoft.appcenter.AbstractAppCenterService

      • getServiceName

        public java.lang.String getServiceName()

      • getLoggerTag

        protected java.lang.String getLoggerTag()
        Specified by:
        getLoggerTag in class com.microsoft.appcenter.AbstractAppCenterService

      • getLogFactories

        public java.util.Map<java.lang.String,​com.microsoft.appcenter.ingestion.models.json.LogFactory> getLogFactories()
        Specified by:
        getLogFactories in interface com.microsoft.appcenter.AppCenterService
        Overrides:
        getLogFactories in class com.microsoft.appcenter.AbstractAppCenterService

      • onActivityResumed

        public void onActivityResumed​(android.app.Activity activity)
        Specified by:
        onActivityResumed in interface android.app.Application.ActivityLifecycleCallbacks
        Overrides:
        onActivityResumed in class com.microsoft.appcenter.AbstractAppCenterService

      • getTriggerInterval

        protected long getTriggerInterval()
        Overrides:
        getTriggerInterval in class com.microsoft.appcenter.AbstractAppCenterService

      • onActivityPaused

        public void onActivityPaused​(android.app.Activity activity)
        Specified by:
        onActivityPaused in interface android.app.Application.ActivityLifecycleCallbacks
        Overrides:
        onActivityPaused in class com.microsoft.appcenter.AbstractAppCenterService

      • getChannelListener

        protected com.microsoft.appcenter.channel.Channel.GroupListener getChannelListener()
        Overrides:
        getChannelListener in class com.microsoft.appcenter.AbstractAppCenterService

      • applyEnabledState

        protected void applyEnabledState​(boolean enabled)
        React to enable state change.
        Overrides:
        applyEnabledState in class com.microsoft.appcenter.AbstractAppCenterService
        Parameters:
        enabled - current state.

      • onStarted

        public void onStarted​(@NonNull
                      android.content.Context context,
                      @NonNull
                      com.microsoft.appcenter.channel.Channel channel,
                      java.lang.String appSecret,
                      java.lang.String transmissionTargetToken,
                      boolean startedFromApp)
        Specified by:
        onStarted in interface com.microsoft.appcenter.AppCenterService
        Overrides:
        onStarted in class com.microsoft.appcenter.AbstractAppCenterService

      • onConfigurationUpdated

        public void onConfigurationUpdated​(java.lang.String appSecret,
                                   java.lang.String transmissionTargetToken)
        Specified by:
        onConfigurationUpdated in interface com.microsoft.appcenter.AppCenterService
        Overrides:
        onConfigurationUpdated in class com.microsoft.appcenter.AbstractAppCenterService

      • post

        protected void post​(java.lang.Runnable runnable)
        Overrides:
        post in class com.microsoft.appcenter.AbstractAppCenterService