YMMYandexMetrica class

Methods of the class are used for configuring the library.

Instance methods

+activateWithConfiguration:

Initializes the library in an application with the extended startup configuration.

+activateReporterWithConfiguration:

Initializes a reporter with extended configuration.

+handleOpenURL:

Processes the URL that opened the application.

+initWebViewReporting:
Adds a JavaScript interface with the AppMetrica name in a window to the specified webview. This lets you send client events from JavaScript code.
+libraryVersion

Returns the current version of the AppMetrica library.

+pauseSession:

Pauses the user session.

-reporterForApiKey:

Creates a reporter for sending events to an additional API key.

+reportAdRevenue:onFailure: Sends information about advertising revenue to the AppMetrica server.
+reportECommerce:onFailure:

Sends a message about an E-commerce event.

+reportError:exception:onFailure:
Sends a custom error message.
Attention. Deprecated method. Use the +reportError:options:onFailure: or +reportError:onFailure: method instead.
+reportError:onFailure:

Sends a YMMErrorRepresentable message.

+reportError:options:onFailure:

Sends a YMMErrorRepresentable message.

+reportNSError:onFailure:

Sends an NSError message.

+reportNSError:options:onFailure:

Sends an NSError message.

+reportEvent:params:onFailure:

Sends an event message with additional parameters.

+reportEvent:onFailure

Sends an event message.

+reportReferralUrl: Sets referral URL for app installs. This method can be used to track some traffic sources.
+reportRevenue:onFailure: Sends information about the purchase to the AppMetrica server.
+reportUserProfile:onFailure: Sends information about the user profile update to the AppMetrica server.
+requestAppMetricaDeviceIDWithCompletionQueue: Requests the unique AppMetrica ID (deviceID).
+resumeSession: Resumes the session, or creates a new one if the session timeout has expired.
+sendEventsBuffer: Sends stored events from the buffer.
+setErrorEnvironmentValue:forKey:

Sets the key-value pair associated with crashes and errors.

+setLocation:

Sets custom location of the device.

+setLocationTracking:

Enables/disables sending location of the device .

+setStatisticsSending: Enables/disables sending statistics to the AppMetrica server.
+setUserProfileID: Sets the ID of the user profile. AppMetrica doesn't display predefined attributes in the web interface if ProfieId sending isn't configured.
+activateWithConfiguration:

Initializes the library in an application with the extended startup configuration.

+activateReporterWithConfiguration:

Initializes a reporter with extended configuration.

+handleOpenURL:

Processes the URL that opened the application.

+initWebViewReporting:
Adds a JavaScript interface with the AppMetrica name in a window to the specified webview. This lets you send client events from JavaScript code.
+libraryVersion

Returns the current version of the AppMetrica library.

+pauseSession:

Pauses the user session.

-reporterForApiKey:

Creates a reporter for sending events to an additional API key.

+reportAdRevenue:onFailure: Sends information about advertising revenue to the AppMetrica server.
+reportECommerce:onFailure:

Sends a message about an E-commerce event.

+reportError:exception:onFailure:
Sends a custom error message.
Attention. Deprecated method. Use the +reportError:options:onFailure: or +reportError:onFailure: method instead.
+reportError:onFailure:

Sends a YMMErrorRepresentable message.

+reportError:options:onFailure:

Sends a YMMErrorRepresentable message.

+reportNSError:onFailure:

Sends an NSError message.

+reportNSError:options:onFailure:

Sends an NSError message.

+reportEvent:params:onFailure:

Sends an event message with additional parameters.

+reportEvent:onFailure

Sends an event message.

+reportReferralUrl: Sets referral URL for app installs. This method can be used to track some traffic sources.
+reportRevenue:onFailure: Sends information about the purchase to the AppMetrica server.
+reportUserProfile:onFailure: Sends information about the user profile update to the AppMetrica server.
+requestAppMetricaDeviceIDWithCompletionQueue: Requests the unique AppMetrica ID (deviceID).
+resumeSession: Resumes the session, or creates a new one if the session timeout has expired.
+sendEventsBuffer: Sends stored events from the buffer.
+setErrorEnvironmentValue:forKey:

Sets the key-value pair associated with crashes and errors.

+setLocation:

Sets custom location of the device.

+setLocationTracking:

Enables/disables sending location of the device .

+setStatisticsSending: Enables/disables sending statistics to the AppMetrica server.
+setUserProfileID: Sets the ID of the user profile. AppMetrica doesn't display predefined attributes in the web interface if ProfieId sending isn't configured.

Method descriptions

+activateWithConfiguration:

+ (void)activateWithConfiguration:(YMMYandexMetricaConfiguration *)configuration

Initializes the library in an application with the extended startup configuration.

Parameters:
configuration

The instance of the YMMYandexMetricaConfiguration class which contains the extended startup configuration for the library.

configuration

The instance of the YMMYandexMetricaConfiguration class which contains the extended startup configuration for the library.

+activateReporterWithConfiguration:

+ (void)activateReporterWithConfiguration:(YMMReporterConfiguration *)configuration

Initializes a reporter with extended configuration.

The configuration of the reporter should be initialized before the first call to the reporter. Otherwise, the configuration of the reporter is ignored.

The reporter should be activated with the configuration using a different API key instead of the app's API key.

Parameters:
configuration

The instance of the YMMReporterConfiguration class which contains the extended configuration for the reporter.

configuration

The instance of the YMMReporterConfiguration class which contains the extended configuration for the reporter.

+handleOpenURL:

+ (BOOL)handleOpenURL:(NSURL *)url

Processes the URL that opened the application.

Used for tracking app openings via deeplink

Parameters:
url

URL that opened the application.

url

URL that opened the application.

Returns:

  • YES, if the deeplink is intended for AppMetrica.
  • NOif the deeplink is not intended for AppMetrica.

There are no such deeplink at the moment. The method always returns NO.

+initWebViewReporting:

+ (void)initWebViewReporting:(WKUserContentController *)userContentController
                   onFailure:(void (^)(NSError *))onFailure
Adds a JavaScript interface with the AppMetrica name in a window to the specified webview. This lets you send client events from JavaScript code.
Notes:
  • The method must be called from the main queue.
  • The method is not available on tvOS.
  • Call this method before loading any content. We recommend calling this method before creating a webview and before adding your scripts to WKUserContentController.
For more information, see Usage examples.
Parameters:
userContentController

The WKUserContentController object used for this WKWebView.

onFailure

A callback method to be called in the event of an error.

userContentController

The WKUserContentController object used for this WKWebView.

onFailure

A callback method to be called in the event of an error.

+libraryVersion:

+ (NSString *)libraryVersion

Returns the current version of the AppMetrica library.

Returns:

Library version.

+pauseSession:

+ (void)resumeSession

Pauses the user session.

Note. The session duration depends on specified timeout. If the time interval between pausing and resuming the session is less than the specified timeout, the current session will be resumed; otherwise, a new one will be created.

For more information about sessions, see Tracking user activity.

-reporterForApiKey:

- (nullable id<YMMYandexMetricaReporting>)reporterForApiKey:(NSString *)apiKey

Creates a reporter for sending events to an additional API key.

To initialize a reporter with the extended configuration, use the activateReporterWithConfiguration: method. The configuration of the reporter should be initialized before the first call to the reporter. Otherwise, the configuration of the reporter is ignored.

Parameters:
apiKey API key that differs from the main application API key.
apiKey API key that differs from the main application API key.

Returns:

The instance that implements the YMMYandexMetricaReporting protocol for a specified API key.

+reportAdRevenue:onFailure:

+ (void)reportAdRevenue:(YMMAdRevenueInfo *)adRevenue
              onFailure:(nullable void (^)(NSError *error))onFailure

Sends information about advertising revenue to the AppMetrica server.

Parameters:
adRevenue

The instance of the YMMAdRevenueInfo class which contains information about advertising revenue.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

adRevenue

The instance of the YMMAdRevenueInfo class which contains information about advertising revenue.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportECommerce:onFailure:

+ (void)reportECommerce:(YMMECommerce *)eCommerce
              onFailure:(nullable void (^)(NSError *error))onFailure

Sends a message about an E-commerce event.

Parameters:
eCommerce

The YMMECommerce class instance.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

eCommerce

The YMMECommerce class instance.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportError:exception:onFailure:

+ (void)reportError:(NSString *)message
          exception:(NSException *)exception
          onFailure:(void (^)(NSError *error))onFailure
Sends a custom error message.
Attention. Deprecated method. Use the +reportError:options:onFailure: or +reportError:onFailure: method instead.
Parameters:
message

Short name or description of the error.

exception

The instance of the NSException class.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

message

Short name or description of the error.

exception

The instance of the NSException class.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportError:onFailure:

+ (void)reportError:id<YMMErrorRepresentable>
          onFailure:(void (^)(NSError *error))onFailure

Sends a YMMErrorRepresentable message.

Note. For more information, see the YMMErrorRepresentable protocol description.
Parameters:
error

The error to send.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

error

The error to send.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportError:options:onFailure:

+ (void)reportError:(id<YMMErrorRepresentable>)error
            options:(YMMErrorReportingOptions)options
          onFailure:(void (^)(NSError *error))onFailure

Sends a YMMErrorRepresentable message.

Use this method to set the send parameters.

Note. For more information, see the YMMErrorRepresentable protocol description.
Parameters:
error

The error to send.

options

Parameters for sending an error.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

error

The error to send.

options

Parameters for sending an error.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportNSError:onFailure:

+ (void)reportNSError:(NSError *)error
            onFailure:(void (^)(NSError *error))onFailure

Sends an NSError message.

AppMetrica uses the domain and code to group errors.

Limits for an NSError:
  • 200 characters for the domain.
  • 50 key-value pairs for userInfo, 100 characters for the key, and 2000 characters for the value.
  • 10 nested errors that use NSUnderlyingErrorKey as a key in userInfo.
  • 200 stack frames in the YMMBacktraceErrorKey backtrace as a key in userInfo.
If the value exceeds the limit, AppMetrica truncates it.
Note. You can send your own error backtrace in NSError. For more information, see the YMMBacktraceErrorKey constant description.
Parameters:
error

The error to send.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

error

The error to send.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportNSError:options:onFailure:

+ (void)reportNSError:(NSError *)error
              options:(YMMErrorReportingOptions)options
            onFailure:(void (^)(NSError *error))onFailure

Sends an NSError message.

AppMetrica uses the domain and code to group errors.

Use this method to set the send parameters.

Limits for an NSError:
  • 200 characters for the domain.
  • 50 key-value pairs for userInfo, 100 characters for the key, and 2000 characters for the value.
  • 10 nested errors that use NSUnderlyingErrorKey as a key in userInfo.
  • 200 stack frames in the YMMBacktraceErrorKey backtrace as a key in userInfo.
If the value exceeds the limit, AppMetrica truncates it.
Note. You can send your own error backtrace in NSError. For more information, see the YMMBacktraceErrorKey constant description.
Parameters:
error

The error to send.

options

Parameters for sending an error.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

error

The error to send.

options

Parameters for sending an error.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportEvent:onFailure:

+ (void)reportEvent:(NSString *)message onFailure:(void (^)(NSError *error))onFailure

Sends an event message.

Parameters:
message

Short name or description of the event

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

message

Short name or description of the event

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportEvent:params:onFailure:

+ (void)reportEvent:(NSString *)message
         parameters:(NSDictionary *)params
          onFailure:(void (^)(NSError *error))onFailure

Sends an event message with additional parameters.

Parameters:
message

Short name or description of the event

params

Parameters as “key-value” pairs.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

message

Short name or description of the event

params

Parameters as “key-value” pairs.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportReferralUrl:

+ (void)reportReferralUrl:(NSURL *)url

Sets referral URL for app installs. This method can be used to track some traffic sources.

Parameters:
url Referral URL of the app install.
url Referral URL of the app install.

+reportRevenue:onFailure:

+ (void)reportRevenue:(YMMRevenueInfo *)revenueInfo
            onFailure:(nullable void (^)(NSError *error))onFailure

Sends information about the purchase to the AppMetrica server.

Parameters:
revenueInfo

The instance of the YMMRevenueInfo class which contains information about a purchase.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

revenueInfo

The instance of the YMMRevenueInfo class which contains information about a purchase.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+reportUserProfile:onFailure:

+ (void)reportUserProfile:(YMMUserProfile *)userProfile
                onFailure:(nullable void (^)(NSError *error))onFailure

Sends information about the user profile update to the AppMetrica server.

Parameters:
userProfile

The instance of the YMMUserProfileclass which contains information about the user profile.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

userProfile

The instance of the YMMUserProfileclass which contains information about the user profile.

onFailure

The block that is executed when an error occurs. The error is passed as a block argument.

+requestAppMetricaDeviceIDWithCompletionQueue:block:

+ (void)requestAppMetricaDeviceIDWithCompletionQueue:(nullable dispatch_queue_t)queue
                                     completionBlock:(YMMAppMetricaDeviceIDRetrievingBlock)block

Requests the unique AppMetrica ID (.

deviceID

).

In the Logs API and Post API deviceID referred to as appmetrica_device_id.

Parameters:
queue

The queue where the callback block will be called.

block

Callback block for receiving appmetrica_device_id. Includes an ID appMetricaDeviceID and error error, if the ID could not be obtained.

queue

The queue where the callback block will be called.

block

Callback block for receiving appmetrica_device_id. Includes an ID appMetricaDeviceID and error error, if the ID could not be obtained.

+resumeSession:

+ (void)resumeSession

Resumes the session, or creates a new one if the session timeout has expired.

Note. The session duration depends on specified timeout. If the time interval between pausing and resuming the session is less than the specified timeout, the current session will be resumed; otherwise, a new one will be created.

For more information about sessions, see Tracking user activity.

+sendEventsBuffer:

+ (void)sendEventsBuffer

Sends stored events from the buffer.

AppMetrica SDK does not send an event immediately after it occurred. The library stores event data in the buffer. Method

sendEventsBuffer()

sends data from the buffer and flushes it. Use the method to force sending stored events after passing important checkpoints of user scenarios.

Attention.

Frequent use of the method can lead to increased outgoing internet traffic and energy consumption.

+setErrorEnvironmentValue:forKey:

+ (void)setErrorEnvironmentValue:(nullable NSString *)value forKey:(NSString *)key;

Sets the key-value pair associated with crashes and errors.

Note. AppMetrica uses these values as additional information for further unhandled exceptions. If you pass the nil value, AppMetrica deletes the previous pair.
Parameters:
value

Value

key

Key

value

Value

key

Key

+setLocation:

+ (void)setLocation:(CLLocation *)location

Sets custom location of the device.

Parameters:
location Information about the location of the device.
location Information about the location of the device.

+setLocationTracking:

+ (void)setLocationTracking:(BOOL)enabled

Enables/disables sending location of the device .

Parameters:
enabled

A flag indicating if sending information about the device location is enabled. The default value is YES.

Possible values:
  • YES — Sending information about the device location is enabled.
  • NO — Sending information about the location of the device is turned off.
enabled

A flag indicating if sending information about the device location is enabled. The default value is YES.

Possible values:
  • YES — Sending information about the device location is enabled.
  • NO — Sending information about the location of the device is turned off.

+setStatisticsSending:

+ (void)setStatisticsSending:(BOOL)enabled

Enables/disables sending statistics to the AppMetrica server.

For more information about using the method, see Disable and enable sending statistics.

Note.

Disabling sending also turns off sending data from all reporters that initialized with the other API key.

Parameters:
enabled

A flag indicating that sending statistics is enabled.

The default value is YES.

Possible values:

  • YES — Sending statistics is enabled.
  • NO — Sending statistics is disabled.
enabled

A flag indicating that sending statistics is enabled.

The default value is YES.

Possible values:

  • YES — Sending statistics is enabled.
  • NO — Sending statistics is disabled.

+setUserProfileID:

+ (void)setUserProfileID:(nullable NSString *)userProfileID

Sets the ID of the user profile. If the

ProfileId

isn't sent, predefined attributes aren't displayed in the web interface.

Parameters:
userProfileID User profile ID.
userProfileID User profile ID.