Package com.dynatrace.android.agent

Class Dynatrace

java.lang.Object
com.dynatrace.android.agent.Dynatrace
public class Dynatrace extends Object
OneAgent SDK for Android.

  • Constructor Details

  • Method Details

    • startup

      public static void startup(Application application, com.dynatrace.android.agent.conf.Configuration configuration)
      Initializing the mobile agent for capturing and reporting data.

      This method must be called in the Application.onCreate() method.

      Parameters:
      application - Android application context
      configuration - configuration object created by the DynatraceConfigurationBuilder
      Since:
      8.231
      See Also:

    • startup

      public static void startup(Activity activity, com.dynatrace.android.agent.conf.Configuration configuration)
      Initializing the mobile agent for capturing and reporting data.

      This method should be used, when the agent is not immediately started in the application startup phase.

      Parameters:
      activity - instance of the currently active activity
      configuration - configuration object created by the DynatraceConfigurationBuilder
      Since:
      8.231
      See Also:

    • startup

      @Deprecated public static void startup(Context context, com.dynatrace.android.agent.conf.Configuration configuration)
      Deprecated.
      As of version 8.231, use startup(Application, Configuration) or startup(Activity, Configuration) instead
      Initializing the mobile agent for capturing and reporting data.

      It is recommended that this method is invoked as early as possible in your application startup sequence.

      Parameters:
      context - Android application context
      configuration - configuration object created by the DynatraceConfigurationBuilder

    • shutdown

      @Deprecated public static void shutdown()
      Deprecated.
      As of version 8.303, no replacement
      Shuts down the mobile agent.

      All data capturing stops. The mobile agent also attempts to flush the data for up to 5 seconds. This is done in a background thread.

    • getCaptureStatus

      public static boolean getCaptureStatus()
      Get the current data capture state.
      Returns:
      true, if data is captured

    • setGpsLocation

      public static void setGpsLocation(Location location)
      Sets a given GPS location.

      The location is then reported along with other captured data.

      Parameters:
      location - to be saved

    • getRequestTagHeader

      public static String getRequestTagHeader()
      Returns the Dynatrace request tag header name.

      This header is used together with the tag generated by getRequestTag() and placed as HTTP header onto a web request.

      Returns:
      the request tag header name

    • getRequestTag

      public static String getRequestTag()
      Returns the Dynatrace request tag which has to be set manually as HTTP header.

      The header key can be obtained with the method getRequestTagHeader(). If there is an open action in the current thread at the time the request is tagged, the web request is assigned (by the mobile agent) to the open action.

      Returns:
      the request tag value or an empty string, if the mobile agent is not active
      See Also:

    • tagRequest

      @Deprecated public static void tagRequest(HttpURLConnection conn)
      Deprecated.
      As of version 8.255, instead manually obtain the request tag and the header key and add them to the HTTP headers of HttpURLConnection.
      Places a Dynatrace request tag on a HttpURLConnection web request.

      This tag is evaluated by the corresponding web server agent. The Dynatrace server will link the server-side PurePath data with this mobile user action.

      Since there is no explicit action, the web request is correlated to an action according to the following rule:

      1. If there is an open action in the current thread at the time the request is tagged, the web request is assigned (by the mobile agent) to the open action.
      2. If there is no open action in the current thread, the web request is assigned (by the Dynatrace Server) to an action that calls its leaveAction() method in the same thread where the tagging is done. The tagging time must fall between the action enter and leave times.
      3. If neither of the preceding cases apply, the web request is not assigned to any action. In this case the server-side PurePath data is not linked to the mobile user action (but it can be identified as mobile traffic in the transaction flow).
      Parameters:
      conn - the request tag will be added as header to this connection
      See Also:

    • enterAction

      public static DTXAction enterAction(String actionName)
      Enters a DTXAction with a specified name.

      If the given actionName is null or an empty string, no reporting will happen on that action.
      The generated action can be used to report the time elapsed between enterAction(java.lang.String) and DTXAction.leaveAction(). Also other event types (DTXAction.reportEvent(java.lang.String), DTXAction.reportValue(java.lang.String, int) and DTXAction.reportError(java.lang.String, int)) can be reported within the context of this action object, thus creating a series of events within an action scope.

      Parameters:
      actionName - name of the action
      Returns:
      A non null action instance to work with
      See Also:

    • enterAction

      public static DTXAction enterAction(String actionName, DTXAction parentAction)
      Enters a DTXAction with a specified name and a parent action.

      If the given actionName is null or an empty string, no reporting will happen on that action.
      The generated action can be used to report the time elapsed between enterAction(java.lang.String) and DTXAction.leaveAction(). Also other event types (DTXAction.reportEvent(java.lang.String), DTXAction.reportValue(java.lang.String, int) and DTXAction.reportError(java.lang.String, int)) can be reported within the context of this action object, thus creating a series of events within an action scope.

      Parameters:
      actionName - name of the action
      parentAction - a parent action
      Returns:
      A non null action instance to work with
      See Also:

    • endVisit

      public static void endVisit()
      Can be called to end the current visit and start a new visit.

      All current actions are closed and sent to the server.

    • reportError

      public static void reportError(String errorName, int errorCode)
      Reports an error with a specified name and error code.

      If given errorName is null or an empty String then no event is reported to the system. The error is reported as root action.

      Parameters:
      errorName - name of this error
      errorCode - numeric error code of this error
      See Also:

    • reportError

      public static void reportError(String errorName, Throwable throwable)
      Reports an error with a specified name and a Throwable.

      If given errorName is null or an empty string then no event is reported to the system. The error is reported as root action.

      Parameters:
      errorName - name of this error
      throwable - Throwable causing this error
      See Also:

    • startView

      public static void startView(String name)
      Starts monitoring of a view.

      A view refers to a view/screen/window which is presented to the user at any time. On every opening of a view the startView method can be called to highlight the current view context of the user. All events happening thereafter can be evaluated in context of that view. When another view was started previously, then this method will stop view monitoring for the previous view and start it for the current view.

      Note: This feature is currently only supported for Real User Monitoring powered by Grail on Dynatrace SaaS deployments.

      Parameters:
      name - the name of the view that is presented to the user
      Since:
      8.303

    • stopView

      public static void stopView()
      Stops monitoring of the view that was previously started via startView(String). It will remove the view context and all events happening afterwards will be reported without view information.

      Note: This feature is currently only supported for Real User Monitoring powered by Grail on Dynatrace SaaS deployments.

      Since:
      8.303

    • flushEvents

      public static void flushEvents()
      Call this function to flush all collected events immediately.

      To reduce network chatter, the collected events are usually sent in packages where the oldest event has an age of up to 2 minutes (the default; the maximum age can be configured). Using this function, you can force sending of all collected events regardless of their age.

    • setBeaconHeaders

      public static void setBeaconHeaders(Map<String,String> headers)
      Puts a set of http headers on every agent http request.

      For example: adding an Authorization header. It also triggers the agent to reconnect to the beacon endpoint with the new headers. To clear the previous headers, call the method with a null or empty value.

      Parameters:
      headers - a set of http headers
      See Also:

    • getWebRequestTiming

      public static WebRequestTiming getWebRequestTiming(String tag)
      This represents a network timing instance for reporting the time elapsed between two user-defined events.

      You must call WebRequestTiming.startWebRequestTiming() to start and WebRequestTiming.stopWebRequestTiming(URL, int, String) or WebRequestTiming.stopWebRequestTiming(String, int, String) to complete the timing.

      Parameters:
      tag - the tag generated by getRequestTag()
      Returns:
      a non-null WebRequestTiming instance

    • getWebRequestTiming

      public static WebRequestTiming getWebRequestTiming(HttpURLConnection connection)
      This represents a network timing instance for reporting the time elapsed between two user-defined events.

      You must call WebRequestTiming.startWebRequestTiming() to start and WebRequestTiming.stopWebRequestTiming() to complete the timing.

      Parameters:
      connection - a non-null HttpURLConnection instance
      Returns:
      a non-null WebRequestTiming instance

    • identifyUser

      public static void identifyUser(String userId)
      The current visit/session will be tagged with the provided user id.

      The value will not be stored and has to be renewed for every new session.

      Parameters:
      userId - a unique id that allows you to identify the current user. If userId is null or empty, then the user tag will be removed from the session.

    • identifyUser

      @Deprecated public static void identifyUser(String userId, DTXAction parentAction)
      Deprecated.
      As of version 8.215, use identifyUser(String) instead
      The current visit/session will be tagged with the provided user id.

      The value will not be stored and has to be renewed on every agent startup.

      Parameters:
      userId - a unique id that allows you to identify the current user. If userId is null or empty, then the user tag will be removed from the session.
      parentAction - The parent action for the user identify event

    • getUserPrivacyOptions

      public static UserPrivacyOptions getUserPrivacyOptions()
      Returns the previously specified privacy settings from the user.
      Returns:
      the previously specified privacy settings from the user
      Since:
      8.191
      See Also:

    • applyUserPrivacyOptions

      public static void applyUserPrivacyOptions(UserPrivacyOptions userPrivacyOptions)
      Creates a new session with the specified privacy settings and stores the privacy settings for future sessions.

      This method can only be used, when user opt-in feature is enabled. This method call has no effect if the given privacy settings are identical to the previously specified privacy settings.

      Parameters:
      userPrivacyOptions - the new privacy settings from the user
      Since:
      8.191
      See Also:

    • isCrashReportingOptedIn

      @Deprecated public static boolean isCrashReportingOptedIn()
      Deprecated.
      As of version 8.191, replaced by getUserPrivacyOptions()
      Returns the current privacy setting for crash reporting.

      This method will always return true, when the user opt-in feature is not used.

      Returns:
      current privacy setting for crash reporting
      Throws:
      IllegalStateException - if the agent is not started

    • setCrashReportingOptedIn

      @Deprecated public static void setCrashReportingOptedIn(boolean confirmed)
      Deprecated.
      As of version 8.191, replaced by applyUserPrivacyOptions(UserPrivacyOptions)
      Allows the user to activate/deactivate crash reporting and stores the users decisions for future sessions.

      This method can only be used, when the agent is started with the user opt-in feature. To use this feature properly, you also have to activate the crash reporting feature.

      Parameters:
      confirmed - true, if crash reporting is confirmed by the user
      Throws:
      IllegalStateException - if the agent is not started
      See Also:

    • getDataCollectionLevel

      @Deprecated public static DataCollectionLevel getDataCollectionLevel()
      Deprecated.
      As of version 8.191, replaced by getUserPrivacyOptions()
      Returns the current data collection level.

      This method will always return DataCollectionLevel.USER_BEHAVIOR, when the user opt-in feature is not used.

      Returns:
      current data collection level
      Throws:
      IllegalStateException - if the agent is not started

    • setDataCollectionLevel

      @Deprecated public static void setDataCollectionLevel(DataCollectionLevel dataCollectionLevel)
      Deprecated.
      As of version 8.191, replaced by applyUserPrivacyOptions(UserPrivacyOptions)
      Allows the user to set the data collection level and stores the users decisions for future sessions.

      This method can only be used, when the agent is started with the user opt-in feature. When the user changes the data collection level a new session will be started.

      Parameters:
      dataCollectionLevel - new data collection level
      Throws:
      IllegalStateException - if the agent is not started

    • modifyUserAction

      public static void modifyUserAction(UserActionModifier modifier)
      Allows to modify the currently pending user action.

      If there is no user action pending or if it is already closed upon modification, no modification takes place.

      Parameters:
      modifier - modifications that should be applied to the newly created user action
      Since:
      8.189

    • addEventModifier

      public static boolean addEventModifier(EventModifier eventModifier)
      Adds an EventModifier that enriches future events by applying the modifier function to them.

      Note: This feature is currently only supported for Real User Monitoring powered by Grail on Dynatrace SaaS deployments.

      Parameters:
      eventModifier - the modification function that is applied to each event
      Returns:
      true if modifier has been successfully added; false otherwise
      Since:
      8.303

    • removeEventModifier

      public static boolean removeEventModifier(EventModifier eventModifier)
      Removes a previously added EventModifier.

      Note: This feature is currently only supported for Real User Monitoring powered by Grail on Dynatrace SaaS deployments.

      Parameters:
      eventModifier - the previously added modification function
      Returns:
      true if it has been successfully removed; false if not found
      Since:
      8.303

    • instrumentWebView

      public static void instrumentWebView(WebView webView)
      Instruments the given WebView to allow communication between the RUM JavaScript tag and OneAgent for Android.

      For hybrid apps with the RUM JavaScript tag inside a WebView, it is required to execute this method for every WebView that contains the RUM JavaScript tag. Without this method call it can't be ensured that the monitoring data will be combined into same session.

      Parameters:
      webView - the web view that should be instrumented
      Since:
      8.191
      See Also:

    • restoreCookies

      public static void restoreCookies()
      Restores the Dynatrace cookies for the specified domains.

      For hybrid apps with web view instrumentation you have to ensure that the Dynatrace cookies are not deleted. You must call this method, when you delete all cookies via CookieManager.removeAllCookies(ValueCallback) and CookieManager.removeSessionCookies(ValueCallback). Without the cookies it is not possible to combine the data from the RUM JavaScript tag and OneAgent for Android into one session.

      Since:
      8.191
      See Also:

    • sendEvent

      public static void sendEvent(JSONObject fields, Object[] eventContext)
      Sends a RUM event with the given fields to the Dynatrace Platform.

      The provided fields must be a flat JSON object that does not contain nested objects or arrays.

      The event will be filled with the provided fields and enriched with basic context information such as user session details and application metadata. After auto-enrichment the event can be modified using an EventModifier. At this stage it's also possible to use the provided event context objects for further manual enrichment of the event.

      Note: This feature is currently only supported for Real User Monitoring powered by Grail on Dynatrace SaaS deployments.

      Parameters:
      fields - flat JSON containing fields that will be added to the event
      eventContext - optional context objects that can be used to manipulate the resulting event using an EventModifier
      Since:
      8.303
      See Also:

    • sendBizEvent

      public static void sendBizEvent(String type, JSONObject attributes)
      Send a Business Event.

      With sendBizEvent, you can report a business event. These standalone events are being sent detached from user actions or sessions. The 'dt' key, as well as all 'dt.' prefixed keys are considered reserved by Dynatrace and will be stripped from the passed in attributes.

      Note: Business events are only supported on Dynatrace SaaS deployments currently.

      Parameters:
      type - event type that is neither null or empty
      attributes - a non null JSON object
      Since:
      8.243