Package com.yandex.metrica

Class YandexMetrica

java.lang.Object
com.yandex.metrica.YandexMetrica
public final class YandexMetrica
extends java.lang.Object
Class assistant for analytic processing.

  • Method Summary

    Modifier and Type Method Description
    static void activate​(android.content.Context context, YandexMetricaConfig config)
    Initializes YandexMetrica with Context and YandexMetricaConfig.
    static void activateReporter​(android.content.Context context, ReporterConfig config)
    Activates the reporter with ReporterConfig.
    static void enableActivityAutoTracking​(android.app.Application application)
    Sessions should be tracked automatically without invoking this method.
    static int getLibraryApiLevel()  
    static java.lang.String getLibraryVersion()  
    static YandexMetricaPlugins getPluginExtension()
    Creates a YandexMetricaPlugins instance that can send plugin events to main API key.
    static IReporter getReporter​(android.content.Context context, java.lang.String apiKey)
    Creates an IReporter that can send events to an alternative api key.
    static void initWebViewReporting​(android.webkit.WebView webView)
    Adds Javascript interface named "AppMetrica" to WebView's javascript.
    static void pauseSession​(android.app.Activity activity)
    Helper method for tracking the life cycle of the application.
    static void putErrorEnvironmentValue​(java.lang.String key, java.lang.String value)
    Sets key - value data to be used as additional information, associated with your unhandled exception and error reports.
    static void reportAppOpen​(android.app.Activity activity)
    Sends report about open app via deeplink
    static void reportAppOpen​(android.content.Intent intent)
    Sends report about open app via deeplink
    static void reportAppOpen​(java.lang.String deeplink)
    Sends report about open app via deeplink.
    static void reportECommerce​(ECommerceEvent event)
    Sends e-commerce event.
    static void reportError​(java.lang.String identifier, java.lang.String message)
    Sends an error.
    static void reportError​(java.lang.String identifier, java.lang.String message, java.lang.Throwable error)
    Sends an error.
    static void reportError​(java.lang.String message, java.lang.Throwable error)
    Sends an error.
    static void reportEvent​(java.lang.String eventName)
    Sends report by event name.
    static void reportEvent​(java.lang.String eventName, java.lang.String jsonValue)
    Sends report by event name and event value.
    static void reportEvent​(java.lang.String eventName, java.util.Map<java.lang.String,​java.lang.Object> attributes)
    Sends report by dictionary.
    static void reportNativeCrash​(java.lang.String nativeCrash)
    Deprecated.
    Will be removed in future versions.
    static void reportReferralUrl​(java.lang.String referralUrl)
    Deprecated. 
    static void reportRevenue​(Revenue revenue)
    Sends information about the purchase.
    static void reportUnhandledException​(java.lang.Throwable exception)
    Sends unhandled exception by Throwable object.
    static void reportUserProfile​(UserProfile profile)
    Sends information about the user profile.
    static void requestAppMetricaDeviceID​(AppMetricaDeviceIDListener listener)
    Retrieves unique AppMetrica device identifier.
    static void requestDeferredDeeplink​(DeferredDeeplinkListener listener)
    Requests deferred deeplink.
    static void requestDeferredDeeplinkParameters​(DeferredDeeplinkParametersListener listener)
    Requests deferred deeplink parameters.
    static void resumeSession​(android.app.Activity activity)
    Helper method for tracking the life cycle of the application.
    static void sendEventsBuffer()
    Initiates forced sending of all stored events from the buffer.
    static void setLocation​(android.location.Location location)
    Sets Location to be used as location for reports of AppMetrica.
    static void setLocationTracking​(boolean enabled)
    Sets whether AppMetrica should include location information within its reports.
    static void setLocationTracking​(android.content.Context context, boolean enabled)
    Sets whether AppMetrica should include location information within its reports.
    static void setStatisticsSending​(android.content.Context context, boolean enabled)
    Enables/disables statistics sending to the AppMetrica server.
    static void setUserProfileID​(java.lang.String userProfileID)
    Sets the ID of the user profile.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • activate

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

    • 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.

    • 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:
      java.lang.IllegalArgumentException - If activity is null.
      See Also:
      Activity, Activity.onResume(), pauseSession(android.app.Activity)

    • 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:
      java.lang.IllegalArgumentException - If activity is null.
      See Also:
      Activity, Activity.onPause(), resumeSession(android.app.Activity)

    • enableActivityAutoTracking

      public static void enableActivityAutoTracking​(@NonNull android.app.Application application)
      Sessions should be tracked automatically without invoking this method. See YandexMetricaConfig.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:
      java.lang.IllegalArgumentException - if application is null. *

    • reportEvent

      public static void reportEvent​(@NonNull java.lang.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:
      java.lang.IllegalArgumentException - If eventName is null.
      See Also:
      reportEvent(String)

    • reportError

      public static void reportError​(@NonNull java.lang.String message, @Nullable java.lang.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:
      java.lang.IllegalArgumentException - If message is null.
      See Also:
      reportUnhandledException(Throwable)

    • reportError

      public static void reportError​(@NonNull java.lang.String identifier, @Nullable java.lang.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:
      java.lang.IllegalArgumentException - If identifier is null.

    • reportError

      public static void reportError​(@NonNull java.lang.String identifier, @Nullable java.lang.String message, @Nullable java.lang.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:
      java.lang.IllegalArgumentException - If identifier is null.

    • reportUnhandledException

      public static void reportUnhandledException​(@NonNull java.lang.Throwable exception)
      Sends unhandled exception by Throwable object.
      Parameters:
      exception - Throwable object for the unhandled exception.
      Throws:
      java.lang.IllegalArgumentException - If exception is null.
      See Also:
      YandexMetricaConfig.Builder.withCrashReporting(boolean), reportError(String, Throwable)

    • reportNativeCrash

      @Deprecated public static void reportNativeCrash​(@NonNull java.lang.String nativeCrash)
      Deprecated.
      Will be removed in future versions. Sends native crash by String object.
      Parameters:
      nativeCrash - String object for the native crash. Contains a crash dump information.
      Throws:
      java.lang.IllegalArgumentException - If nativeCrash is null.
      See Also:
      YandexMetricaConfig.Builder.withNativeCrashReporting(boolean), reportUnhandledException(Throwable), reportError(String, Throwable)

    • reportEvent

      public static void reportEvent​(@NonNull java.lang.String eventName, @Nullable java.lang.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:
      java.lang.IllegalArgumentException - If eventName or jsonValue is null.
      See Also:
      reportEvent(String, java.util.Map), reportEvent(String), JSONObject.toString()

    • reportEvent

      public static void reportEvent​(@NonNull java.lang.String eventName, @Nullable java.util.Map<java.lang.String,​java.lang.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:
      java.lang.IllegalArgumentException - If eventName is null.
      See Also:
      reportEvent(String, String), reportEvent(String)

    • 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 java.lang.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 java.lang.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(boolean), setLocationTracking(Context, boolean)

    • 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:
      setLocation(android.location.Location)

    • setLocationTracking

      public static void setLocationTracking​(@NonNull android.content.Context context, boolean enabled)
      Sets whether AppMetrica should include location information within its reports.

      NOTE: Default value is false

      Parameters:
      context - Context object
      enabled - true to allow AppMetrica to record location information in reports, otherwise false.
      See Also:
      setLocation(android.location.Location)

    • setStatisticsSending

      public static void setStatisticsSending​(@NonNull android.content.Context context, boolean enabled)
      Enables/disables statistics 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:
      context - Context object
      enabled - true to allow AppMetrica sending statistics, 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 java.lang.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 java.lang.String getLibraryVersion()
      Returns:
      VERSION of library.
      See Also:
      getLibraryApiLevel()

    • getLibraryApiLevel

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

    • 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.

    • requestAppMetricaDeviceID

      public static void requestAppMetricaDeviceID​(@NonNull AppMetricaDeviceIDListener listener)
      Retrieves unique AppMetrica device identifier. It is used to identify a device in the statistics.

      NOTE: AppMetrica device ID is used in the Logs API and Post API as 'appmetrica_device_id'.

      Parameters:
      listener - The AppMetricaDeviceIDListener object

    • setUserProfileID

      public static void setUserProfileID​(@Nullable java.lang.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:
      ECommerceEvent

    • putErrorEnvironmentValue

      public static void putErrorEnvironmentValue​(@NonNull java.lang.String key, @Nullable java.lang.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 YandexMetricaPlugins getPluginExtension()

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

      Only one YandexMetricaPlugins 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, YandexMetricaConfig).
      Returns:
      plugin extension instance