Package io.appmetrica.analytics

Class AppMetrica

java.lang.Object
io.appmetrica.analytics.AppMetrica
public final class AppMetrica extends Object
Class assistant for analytic processing.

  • Method Details

    • activate

      public static void activate(@NonNull android.content.Context context, @NonNull AppMetricaConfig config)
      Initializes AppMetrica with Context and AppMetricaConfig.
      Parameters:
      context - Context object. Any application context.
      config - AppMetrica configuration object.
      See Also:

    • sendEventsBuffer

      public static void sendEventsBuffer()
      Initiates forced sending of all stored events from the buffer.

      AppMetrica SDK doesn't send events immediately after they occurred. It stores events data in the buffer. This method forcibly initiates sending all the data from the buffer and flushes it.

      Use the method after important checkpoints of user scenarios.

      WARNING: Frequent use of the method can lead to increasing outgoing internet traffic and energy consumption.

      See Also:

    • resumeSession

      public static void resumeSession(@Nullable android.app.Activity activity)

      Helper method for tracking the life cycle of the application.

      It should be called into Activity.onResume() ()}.
      Parameters:
      activity - Activity object.
      Throws:
      IllegalArgumentException - If activity is null.
      See Also:

    • pauseSession

      public static void pauseSession(@Nullable android.app.Activity activity)

      Helper method for tracking the life cycle of the application.

      It should be called into Activity.onPause().
      Parameters:
      activity - Activity object.
      Throws:
      IllegalArgumentException - If activity is null.
      See Also:

    • enableActivityAutoTracking

      public static void enableActivityAutoTracking(@NonNull android.app.Application application)
      Sessions should be tracked automatically without invoking this method. See AppMetricaConfig.Builder.withSessionsAutoTrackingEnabled(boolean) Use this method only if your case is special and you don't see automatically tracked user sessions.

      Helper method for tracking the lifecycle of the application

      Sessions should be tracked automatically
      Parameters:
      application - Application whose activities starts and stops should be tracked automatically
      Throws:
      IllegalArgumentException - if application is null. *

    • reportEvent

      public static void reportEvent(@NonNull String eventName)
      Sends report by event name.
      Parameters:
      eventName - Event name. In the eventName parameter, pass a short name or description of the event.
      Throws:
      IllegalArgumentException - If eventName is null.
      See Also:

    • reportError

      public static void reportError(@NonNull String message, @Nullable Throwable error)
      Sends an error. Use this method to report un unexpected situation. If you use this method errors will be grouped by error stacktrace. If you want to influence the way errors are grouped use reportError(String, String, Throwable) or reportError(String, String)
      Parameters:
      message - Short description or name of the error.
      error - Throwable object for the error. Can be null.
      Throws:
      IllegalArgumentException - If message is null.
      See Also:

    • reportError

      public static void reportError(@NonNull String identifier, @Nullable String message)
      Sends an error. Use this method to report un unexpected situation. This method should be used if you want to customize error grouping. If not use reportError(String, Throwable)
      Parameters:
      identifier - An identifier used for grouping errors. Errors that have the same identifiers will belong in one group. Do not use dynamically formed strings or exception messages as identifiers to avoid having too many small crash groups. Cannot be null.
      message - Short description or name of the error. Can be null.
      Throws:
      IllegalArgumentException - If identifier is null.

    • reportError

      public static void reportError(@NonNull String identifier, @Nullable String message, @Nullable Throwable error)
      Sends an error. Use this method to report un unexpected situation. This method should be used if you want to customize error grouping. If not use reportError(String, Throwable) error stacktrace will NOT be used for grouping, only identifier.
      Parameters:
      identifier - An identifier used for grouping errors. Errors that have the same identifiers will belong in one group. Do not use dynamically formed strings or exception messages as identifiers to avoid having too many small crash groups. Cannot be null.
      message - Short description or name of the error. Can be null.
      error - Throwable object for the error. Its stacktrace will not be considered for error grouping. Can be null.
      Throws:
      IllegalArgumentException - If identifier is null.

    • reportUnhandledException

      public static void reportUnhandledException(@NonNull Throwable exception)
      Sends unhandled exception by Throwable object.
      Parameters:
      exception - Throwable object for the unhandled exception.
      Throws:
      IllegalArgumentException - If exception is null.
      See Also:

    • reportEvent

      public static void reportEvent(@NonNull String eventName, @Nullable String jsonValue)
      Sends report by event name and event value.
      Parameters:
      eventName - Event name. In the eventName parameter, pass a short name or description of the event.
      jsonValue - Event value. In the eventValue parameter, pass a JSONObject represented as a String object or pass a String object represented in the Java JSON format. Maximum level of nesting (for JSON object) - 5.

      EXAMPLE:

                        
                   {
                       "firstName": "John",
                       "lastName": "Smith",
                       "age": 25,
                       "nickname": "JS"
                       "address": {
                           "streetAddress": "21 2nd Street",
                           "city": "New York",
                           "state": "NY",
                       },
                       "phoneNumbers": [
                           {
                               "type": "HOME",
                               "number": "212 555-1234"
                           },
                           {
                               "type": "FAX",
                               "number": "646 555-4567"
                           }
                       ]
                    }
      Throws:
      IllegalArgumentException - If eventName or jsonValue is null.
      See Also:

    • reportEvent

      public static void reportEvent(@NonNull String eventName, @Nullable Map<String,Object> attributes)
      Sends report by dictionary.
      Parameters:
      eventName - Event name. In the eventName parameter, pass a short name or description of the event.
      attributes - Event value. In the attributes parameter, pass a Map whose keys are of type String and whose values are of supported types: Boolean, String, and the wrappers for the primitive number types Double, Integer, ...
      Throws:
      IllegalArgumentException - If eventName is null.
      See Also:

    • reportAppOpen

      public static void reportAppOpen(@NonNull android.app.Activity activity)
      Sends report about open app via deeplink
      Parameters:
      activity - - opened activity with corresponding intent with deeplink

    • reportAppOpen

      public static void reportAppOpen(@NonNull String deeplink)
      Sends report about open app via deeplink. Null and empty values will be ignored.
      Parameters:
      deeplink - Deeplink value.

    • reportAppOpen

      public static void reportAppOpen(@NonNull android.content.Intent intent)
      Sends report about open app via deeplink
      Parameters:
      intent - - intent used to open activity with deeplink

    • reportReferralUrl

      public static void reportReferralUrl(@NonNull String referralUrl)
      Deprecated.
      Sets referral URL for this installation. This might be required to track some specific traffic sources like Facebook.
      Parameters:
      referralUrl - referral URL value.

    • setLocation

      public static void setLocation(@Nullable android.location.Location location)

      Sets Location to be used as location for reports of AppMetrica.

      If location is set using this method, it will be used instead of auto collected location. To switch back to auto collected location, pass null to setLocation(Location).

      NOTE: Permissions: Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION improve the quality of auto collected location.

      Parameters:
      location - location that will be used instead of auto collected
      See Also:

    • setLocationTracking

      public static void setLocationTracking(boolean enabled)
      Sets whether AppMetrica should include location information within its reports.

      NOTE: Default value is false.

      Parameters:
      enabled - true to allow AppMetrica to record location information in reports, otherwise false.
      See Also:

    • setAdvIdentifiersTracking

      public static void setAdvIdentifiersTracking(boolean enabled)
      Enables/disables including advertising identifiers like GAID, Huawei OAID within its reports.

      NOTE: Default value is true.

      Parameters:
      enabled - true to allow AppMetrica to record advertising identifiers information in reports, otherwise false.
      See Also:

    • setDataSendingEnabled

      public static void setDataSendingEnabled(boolean enabled)
      Enables/disables data sending to the AppMetrica server. By default, the sending is enabled.

      NOTE: Disabling this option also turns off data sending from the reporters that initialized for different apiKey.

      Parameters:
      enabled - true to allow AppMetrica sending data, otherwise false.

    • activateReporter

      public static void activateReporter(@NonNull android.content.Context context, @NonNull ReporterConfig config)
      Activates the reporter with ReporterConfig.
      Parameters:
      context - Context object.
      config - The ReporterConfig object.

    • getReporter

      @NonNull public static IReporter getReporter(@NonNull android.content.Context context, @NonNull String apiKey)

      Creates an IReporter that can send events to an alternative api key.

      For every api key only one IReporter instance is created. You can either query it each time you need it, or save the reference by yourself.
      Parameters:
      context - Context object
      apiKey - api key of the reporter
      Returns:
      reporter instance for given api key

    • getLibraryVersion

      @NonNull public static String getLibraryVersion()
      Returns:
      VERSION of library.
      See Also:

    • getLibraryApiLevel

      public static int getLibraryApiLevel()
      Returns:
      API LEVEL of library.
      See Also:

    • requestDeferredDeeplinkParameters

      public static void requestDeferredDeeplinkParameters(@NonNull DeferredDeeplinkParametersListener listener)
      Requests deferred deeplink parameters. Parameters will be available after receiving Google Play installation referrer from Google Play. Google Play installation referrer is usually received soon after first launch of application. After Google Play installation referrer is received, deferred deeplink parameters will be extracted and delivered to DeferredDeeplinkParametersListener.onParametersLoaded(Map) listener. If error occurs it will be delivered to DeferredDeeplinkParametersListener.onError(DeferredDeeplinkParametersListener.Error, String)
      Parameters:
      listener - the object that receives callbacks when Google Play referrer is received or error occurs.

    • requestDeferredDeeplink

      public static void requestDeferredDeeplink(@NonNull DeferredDeeplinkListener listener)
      Requests deferred deeplink. It will be available after receiving Google Play installation referrer from Google Play. Google Play installation referrer is usually received soon after first launch of application. After Google Play installation referrer is received, deferred deeplink will be extracted and delivered to DeferredDeeplinkListener.onDeeplinkLoaded(String) listener. If error occurs it will be delivered to DeferredDeeplinkListener.onError(DeferredDeeplinkListener.Error, String)
      Parameters:
      listener - the object that receives callbacks when Google Play referrer is received or error occurs.

    • setUserProfileID

      public static void setUserProfileID(@Nullable String userProfileID)
      Sets the ID of the user profile. NOTE: The string value can contain up to 200 characters.
      Parameters:
      userProfileID - The custom user profile ID.

    • reportUserProfile

      public static void reportUserProfile(@NonNull UserProfile profile)
      Sends information about the user profile.
      Parameters:
      profile - The UserProfile object. Contains user profile information.

    • reportRevenue

      public static void reportRevenue(@NonNull Revenue revenue)
      Sends information about the purchase.
      Parameters:
      revenue - The Revenue object. It contains purchase information

    • reportECommerce

      public static void reportECommerce(@NonNull ECommerceEvent event)
      Sends e-commerce event.
      Parameters:
      event - The ECommerceEvent object to be sent.
      See Also:

    • putErrorEnvironmentValue

      public static void putErrorEnvironmentValue(@NonNull String key, @Nullable String value)
      Sets key - value data to be used as additional information, associated with your unhandled exception and error reports.
      Parameters:
      key - the environment key.
      value - the environment value. To remove pair from environment pass null value.

    • initWebViewReporting

      @MainThread public static void initWebViewReporting(@NonNull android.webkit.WebView webView)
      Adds Javascript interface named "AppMetrica" to WebView's javascript. It allows then to report events to AppMetrica from JS code.
      NOTE: This method must be called from main thread.
      NOTE: Reporting from JS code will not be enabled on API levels 16 and less due to security issues.
      Parameters:
      webView - WebView where AppMetrica should enable reporting
      See Also:
      • AppMetricaJsInterface

    • getPluginExtension

      @NonNull public static AppMetricaPlugins getPluginExtension()

      Creates a AppMetricaPlugins instance that can send plugin events to main API key.

      Only one AppMetricaPlugins instance is created per each app process. You can either query it each time you need it, or save the reference by yourself.
      NOTE: to use this extension you must activate AppMetrica first via activate(android.content.Context, AppMetricaConfig).
      Returns:
      plugin extension instance

    • reportAdRevenue

      public static void reportAdRevenue(@NonNull AdRevenue adRevenue)
      Sends information about ad revenue.
      Parameters:
      adRevenue - Object containing the information about ad revenue.
      See Also:

    • getDeviceId

      @Nullable public static String getDeviceId(@NonNull android.content.Context context)
      Returns deviceId.
      Parameters:
      context - any Context object
      Returns:
      deviceId if present, null otherwise.
      See Also:

    • getUuid

      @Nullable public static String getUuid(@NonNull android.content.Context context)
      Returns uuid.
      Parameters:
      context - any Context object
      Returns:
      uuid if present, null otherwise.
      See Also:

    • putAppEnvironmentValue

      public static void putAppEnvironmentValue(@NonNull String key, @Nullable String value)
      Sets key - value pair to be used as additional information, associated with your application runtime's environment. This environment is unique for every unique APIKey and shared between processes. Application's environment persists to storage and retained between application launches. To reset environment use clearAppEnvironment()

      If called before metrica initialization, environment will be added right after metrica initialize

      WARNING: Application's environment is a global permanent state and can't be changed too often. For frequently changed parameters use extended reportMessage methods.

      Parameters:
      key - the environment key.
      value - the environment value. To remove pair from environment pass null value.
      See Also:

    • clearAppEnvironment

      public static void clearAppEnvironment()
      Clears app environment and removes it from storage.

      If called before metrica initialization, app environment will be cleared right after init

      See Also:

    • requestStartupParams

      public static void requestStartupParams(@NonNull android.content.Context context, @NonNull StartupParamsCallback callback, @NonNull List<String> params)

      Gets specific startup parameters based on the options in StartupParamsCallback. Parameters might not be available right away. When they do arrive, the callback is informed instantly. If the parameters are already there, the callback also gets notified right away. After one notification, the callback is removed.

      Avoid using anonymous callbacks. They are wrapped by WeakReference and will be removed automatically, which can cause them to disappear unexpectedly after garbage collection (GC).

      NOTE: This method can be called even without initializing via activate(Context, AppMetricaConfig), but it will take more time to get the startup identifiers.
      Parameters:
      context - Context object
      callback - Object that implements the StartupParamsCallback interface.
      params - List of parameters to request. If the list is empty, the default request is for StartupParamsCallback.APPMETRICA_UUID, StartupParamsCallback.APPMETRICA_DEVICE_ID, StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH.

    • registerAnrListener

      public static void registerAnrListener(@NonNull AnrListener listener)
      Add listener for detect ANR. It should be called after activate(android.content.Context, io.appmetrica.analytics.AppMetricaConfig) method.
      Parameters:
      listener - An object that implements AnrListener interface.

    • reportExternalAttribution

      public static void reportExternalAttribution(@NonNull ExternalAttribution value)
      Reports attribution from different sources to AppMetrica.
      Parameters:
      value - An object that implements ExternalAttribution interface.

    • reportExternalAdRevenue

      public static void reportExternalAdRevenue(@NonNull Object... values)
      Sends information about ad revenue from third-party libraries. See documentation for more information.
      Parameters:
      values - Objects that are required to build ad revenue event

    • reportAnr

      public static void reportAnr(@NonNull Map<Thread,StackTraceElement[]> allThreads)
      Sends an ANR event (the application is not responding) manually. It is an alternative for automatic ANR tracking, which is enabled in the $AppMetricaConfig configuration during SDK activation.
      Parameters:
      allThreads - A snapshot of all streams with stack traces. Can be received by calling Thread.getAllStackTraces().
      See Also: