YMMYandexMetrica class

Methods of the class are used for configuring the library.

Instance methods

activate(with:)

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

activateReporter(with:)

Initializes a reporter with extended configuration.

handleOpen(_:)

Processes the URL that opened the application.

initWebViewReporting(_: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.
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.

report(eCommerce:onFailure:)

Sends a message about an E-commerce event.

reportError(_:exception:onFailure:)

Sends a custom error message.

report(error:onFailure:)

Sends a YMMErrorRepresentable message.

report(error:options:onFailure:)

Sends a YMMErrorRepresentable message.

report(nserror:onFailure:)

Sends an NSError message.

report(nserror:options:onFailure:)

Sends an NSError message.

reportEvent(_:onFailure:)

Sends an event message.

reportEvent(_:parameters:onFailure:)

Sends an event message with additional parameters.

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.

report(adRevenue:onFailure:)

Sends information about advertising revenue to the AppMetrica server.

report(_:onFailure:)

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

requestAppMetricaDeviceID(withCompletionQueue:completionBlock:)

Requests the unique AppMetrica ID (deviceID).

requestAppMetricaDeviceID(withCompletionQueue:) 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.
activate(with:)

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

activateReporter(with:)

Initializes a reporter with extended configuration.

handleOpen(_:)

Processes the URL that opened the application.

initWebViewReporting(_: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.
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.

report(eCommerce:onFailure:)

Sends a message about an E-commerce event.

reportError(_:exception:onFailure:)

Sends a custom error message.

report(error:onFailure:)

Sends a YMMErrorRepresentable message.

report(error:options:onFailure:)

Sends a YMMErrorRepresentable message.

report(nserror:onFailure:)

Sends an NSError message.

report(nserror:options:onFailure:)

Sends an NSError message.

reportEvent(_:onFailure:)

Sends an event message.

reportEvent(_:parameters:onFailure:)

Sends an event message with additional parameters.

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.

report(adRevenue:onFailure:)

Sends information about advertising revenue to the AppMetrica server.

report(_:onFailure:)

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

requestAppMetricaDeviceID(withCompletionQueue:completionBlock:)

Requests the unique AppMetrica ID (deviceID).

requestAppMetricaDeviceID(withCompletionQueue:) 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

activate(with:)

class func activate(with configuration: YMMYandexMetricaConfiguration)

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.

activateReporter(with:)

class func activateReporter(with configuration: YMMReporterConfiguration)

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.

handleOpen(_:)

class func handleOpen(_ url: URL) -> Bool

Processes the URL that opened the application.

Used for tracking app openings via deeplink.

Parameters:
url

The URL that opened the application.

url

The URL that opened the application.

Returns:

  • true, if the deeplink is intended for AppMetrica.
  • false, if the deeplink is not intended for AppMetrica.

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

initWebViewReporting(_:onFailure:)

class func initWebViewReporting(_ userContentController: WKUserContentController, onFailure: ((Error) -> Void)? = nil)
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()

open class func libraryVersion() -> String

Returns the current version of the AppMetrica library.

Returns:

Library version.

pauseSession()

class func pauseSession()

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(_:)

class func reporterForApiKey(_ apiKey: String) -> YMMYandexMetricaReporting?

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

To initialize a reporter with the extended configuration, use the activateReporter(with:) 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.

report(eCommerce:onFailure:)

class func report(eCommerce: YMMECommerce, onFailure: ((Error) -> Void)? = nil)

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:)

class func reportError(_ message: String, exception: NSException?, onFailure: ((Error) -> Void)? = nil)

Sends a custom error message.

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.

report(error:onFailure:)

class func report(error: YMMErrorRepresentable, onFailure: ((Error) -> Void)? = nil)

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.

report(error:options:onFailure:)

class func report(error: YMMErrorRepresentable, options: YMMErrorReportingOptions = [], onFailure: ((Error) -> Void)? = nil)

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.

report(nserror:onFailure:)

class func report(nserror error: Error, onFailure: ((Error) -> Void)? = nil)

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.

report(nserror:options:onFailure:)

class func report(nserror error: Error, options: YMMErrorReportingOptions = [], onFailure: ((Error) -> Void)? = nil)

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:)

class func reportEvent(_ message: String, onFailure: ((Error) -> Void)? = nil)

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(_:parameters:onFailure:)

class func reportEvent(_ message: String, parameters params: [AnyHashable : Any]?, onFailure: ((Error) -> Void)? = nil)

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(_:)

class func reportReferralUrl(_ url: NSURL)

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:)

class func reportRevenue(_ revenueInfo: YMMRevenueInfo, onFailure: ((NSError) -> Void)?)

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.

report(adRevenue:onFailure:)

class func report(_ adRevenue: YMMAdRevenueInfo, onFailure: ((NSError) -> Void)?)

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.

reportUserProfile(_:onFailure:)

class func reportUserProfile(_ userProfile: YMMUserProfile, onFailure: ((NSError) -> Void)?)

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:)

class func requestAppMetricaDeviceIDWithCompletionQueue(_ queue: dispatch_queue_t?, completionBlock block: YMMAppMetricaDeviceIDRetrievingBlock)

Requests the unique AppMetrica ID (deviceID).

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

requestAppMetricaDeviceID(withCompletionQueue:)

class func requestAppMetricaDeviceID(withCompletionQueue queue: DispatchQueue?) async throws -> String

Requests the unique AppMetrica ID (deviceID).

The unique appmetrica identifier deviceID is available in AppMetricaDeviceIDListener.onLoaded(String deviceID) , if there are no errors. If an error occurs, the error value is stored in AppMetricaDeviceIDListener.onError(Error error, String referrer).
Note. In the Logs API and Post API deviceID referred to as appmetrica_device_id.
Parameters:
queue

Queue for sending deviceID.

queue

Queue for sending deviceID.

Returns:

deviceID.

resumeSession()

class func 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()

class func 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. The sendEventsBuffer() method 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:)

class func setErrorEnvironmentValue(_ value: String?, forKey key: String)

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(_:)

class func setLocation(_ location: CLLocation?)

Sets custom location of the device.

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

setLocationTracking(_:)

class func setLocationTracking(_ enabled: Bool)

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

Possible values:
  • true — Sending information about the device location is enabled.
  • false — Sending information about the location of the device is disabled.
enabled

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

Possible values:
  • true — Sending information about the device location is enabled.
  • false — Sending information about the location of the device is disabled.

setStatisticsSending(_:)

class func setStatisticsSending(_ enabled: Bool)

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

Possible values:

  • true — Sending statistics is enabled.
  • false — Sending statistics is disabled.
enabled A flag indicating that sending statistics is enabled. The default value is true.

Possible values:

  • true — Sending statistics is enabled.
  • false — Sending statistics is disabled.

setUserProfileID(_:)

class func setUserProfileID(_ userProfileID: String?)

Sets the ID of the user profile. AppMetrica doesn't display predefined attributes in the web interface if ProfieId sending isn't configured.

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