Migrating to version 5.0.0

If dependencies are set via Xcode

1. Delete the metrika-sdk-ios dependency.

   

2. In the Xcode Project Navigator window, select your project (if Workspace is used). In the top menu, click File and select Add Package Dependencies....

   

3. Specify the repository URL https://github.com/appmetrica/appmetrica-sdk-ios.

   

4. Leave only the required modules (to disable a module, select None in Add to Target):

   

   • AppMetricaCore: The mandatory main SDK module. It must be connected for working with AppMetrica.
   • AppMetricaAdSupport: The module is used to collect IDs, including IDFA.
   • AppMetricaCrashes: The module is intended for detecting crashes and sending errors.
   • AppMetricaWebKit: The module enables you to send events from JavaScript code in WebView.

When using the Package.swift manifest

1. Delete the .package dependency with YandexMobileMetrica from the file Package.swift in your project together with all references to the dependencies in the targets: section within your project.

2. Insert the following code to add the new appmetrica-sdk-ios dependency:

   dependencies: [
     .package(
       name: "AppMetrica",
       url: "https://github.com/appmetrica/appmetrica-sdk-ios",
       .upToNextMinor(from: "5.0.0")
     ),
   ],
   

3. Add the required modules to your project's targets.

   • AppMetricaCore: The mandatory main SDK module. It must be connected for working with AppMetrica.
   • AppMetricaAdSupport: The module is used to collect IDs, including IDFA.
   • AppMetricaCrashes: The module is intended for detecting crashes and sending errors.
   • AppMetricaWebKit: The module enables you to send events from JavaScript code in WebView.

   .target(
       name: "MyTargetName",
       dependencies: [
         .product(name: "AppMetricaCore", package: "AppMetrica"),
         .product(name: "AppMetricaCrashes", package: "AppMetrica"),
         .product(name: "AppMetricaWebKit", package: "AppMetrica"),
         // .product(name: "AppMetricaAdSupport", package: "AppMetrica"), // This module is disabled
       ]
   ),
   

If dependencies are set via Xcode

Open the project in Xcode. Make sure that Package Dependencies don't contain YandexMobileMetrica.

When using the Package.swift manifest

If your project uses the Package.swift manifest to manage dependencies, execute the swift package show-dependencies command in the terminal in your project's directory. This will output a list of all project dependencies, including transitive ones.

.
└── yandex-ads-sdk-ios<https://github.com/yandexmobile/yandex-ads-sdk-ios.git@6.4.0>
  ├── metrica-sdk-ios<https://github.com/yandexmobile/metrica-sdk-ios@4.5.2>
  └── divkit-ios<https://github.com/divkit/divkit-ios@28.13.0>
      └── vgsl<https://github.com/yandex/vgsl.git@2.4.1>

You can also check the Package.resolved file for the YandexMobileMetrica dependency.

{
  "object": {
    "pins": [
      //...
      {
        "package": "YandexMobileMetrica",
        "repositoryURL": "https://github.com/yandexmobile/metrica-sdk-ios",
        "state": {
          "branch": null,
          "revision": "13d8b11181a33938ef42759d49466a621df5e7db",
          "version": "4.5.2"
        }
      },
      //...
    ]
  },
  // ...
}

#import <YandexMobileMetrica/YandexMobileMetrica.h>

Replace with:

#import <AppMetricaCore/AppMetricaCore.h>
#import <AppMetricaCrashes/AppMetricaCrashes.h> // if you need to work with errors/crashes
#import <AppMetricaWebKit/AppMetricaWebKit.h> // if you need to set up event sending from WebView

Changed the YMM prefix to AMA.

• Renamed the YMMYandexMetrica interface to AMAAppMetrica.
  • Renamed the -getPluginExtension: method to -pluginExtension: and moved it to the AMAAppMetricaCrashes class.
  • Renamed the +handleOpenURL: method to +trackOpeningURL:.
  • Renamed the +initWebViewReporting:onFailure: method to +setupWebViewReporting:onFailure:. For more information, see Sending an event from the WebView's JavaScript code.
  • Removed the +libraryVersion: method, use the libraryVersion property.
  • Removed the +reportError:exception:onFailure: method, see Working with crashes and errors.
  • Moved the +reportError:onFailure: method to the AppMetricaCrashes class and the AppMetricaCrashes module, see Working with crashes and errors.
  • Moved the +reportError:options:onFailure: method to the AppMetricaCrashes class and the AppMetricaCrashes module, see Working with crashes and errors.
  • Renamed the +reportEvent:params:onFailure: method to +reportEvent:parameters:onFailure:
  • Moved the +reportNSError:onFailure: method to the AppMetricaCrashes class and the AppMetricaCrashes module, see Working with crashes and errors.
  • Moved the +reportNSError:options:onFailure: method to the AppMetricaCrashes class and the AppMetricaCrashes module, see Working with crashes and errors.
  • Removed the +reportReferralUrl: method.
  • Renamed the +reporterForApiKey: method to +reporterForAPIKey:.
  • Removed the +requestAppMetricaDeviceIDWithCompletionQueue: method, use +requestStartupIdentifiersWithKeys:completionQueue:completionBlock:.
  • Removed the +setErrorEnvironmentValue:forKey: method, use [[AMAAppMetricaCrashes crashes] setErrorEnvironmentValue:value forKey:key].
  • Removed the +setLocation: method, use the customLocation property.
  • Removed the +setLocationTracking: method, use the locationTrackingEnabled property.
  • Renamed the +setStatisticsSending: method as +setDataSendingEnabled:.
  • Removed the +setUserProfileID: method, use the userProfileID property.
• Renamed the YMMYandexMetricaConfiguration interface to AMAAppMetricaConfiguration.
  • Renamed the -initWithApiKey: constructor as -initWithAPIKey:.
  • Renamed the apiKey property to APIKey.
  • Removed the appForKids property, see Using the SDK for children's apps.
  • Removed the crashReporting property, see Working with crashes and errors.
  • Renamed the location property to customLocation.
  • Renamed the logs property as logsEnabled.
  • Renamed the statisticsSending property to dataSendingEnabled.
• Renamed the YMMYandexMetricaPreloadInfo interface to AMAAppMetricaPreloadInfo.

Reporter

• Renamed the YMMMutableReporterConfiguration interface to AMAMutableReporterConfiguration.
  • Renamed the logs property to logsEnabled.
  • Renamed the statisticsSending property to dataSendingEnabled.
• Renamed the YMMPluginErrorDetails interface to AMAPluginErrorDetails.
• Renamed the YMMReporterConfiguration interface to AMAReporterConfiguration.
  • Renamed the -initWithApiKey: constructor to -initWithAPIKey:.
  • Renamed the apiKey property to APIKey.
  • Renamed the logs property to logsEnabled.
  • Renamed the statisticsSending property to dataSendingEnabled.
• Added the AMAAppMetricaCrashesConfiguration interface.
• Renamed the YMMStackTraceElement interface to AMAStackTraceElement.
• Renamed the YMMYandexMetricaPlugins interface to AMAAppMetricaPlugins.
  • Renamed the getPluginExtension method to pluginExtension.
• Added the AMAAppMetricaCrashes interface.
  • Added the -clearErrorEnvironment: method.
  • Added the -enableANRMonitoring: method.
  • Added the -enableANRMonitoringWithWatchdogInterval:pingInterval: method.
  • Added the -requestCrashReportingStateWithCompletionQueue:completionBlock: method.
  • Added the -setErrorEnvironmentValue:forKey: method.
• Renamed the YMMYandexMetricaPluginReporting protocol to AMAAppMetricaPluginReporting.
  • Renamed the getPluginExtension method to pluginExtension.
• Renamed the YMMYandexMetricaReporting protocol to AMAAppMetricaReporting.
  • Moved the +reportError:onFailure: method to the AMAAppMetricaCrashReporting protocol, the AppMetricaCrashes class, and the AppMetricaCrashes module, see Working with crashes and errors.
  • Moved the +reportError:options:onFailure: method to the AMAAppMetricaCrashReporting protocol, the AppMetricaCrashes class, and the AppMetricaCrashes module, see Working with crashes and errors.
  • Renamed the +reportEvent:params:onFailure: method to +reportEvent:parameters:onFailure:.
  • Moved the +reportNSError:onFailure: method to the AMAAppMetricaCrashReporting protocol, the AppMetricaCrashes class, and the AppMetricaCrashes module, see Working with crashes and errors.
  • Moved the +reportNSError:options:onFailure: method to the AMAAppMetricaCrashReporting protocol, the AppMetricaCrashes class, and the AppMetricaCrashes module, see Working with crashes and errors.
  • Renamed the +setStatisticsSending: method to +setDataSendingEnabled:.
• Renamed the kYMMPlatformNative constant to kAMAPlatformNative.
• Renamed the kYMMPlatformFlutter constant to kAMAPlatformFlutter.
• Added the kAMACrashReportingStateCrashedLastLaunchKey constant starting from version 5.4.0.
• Added the kAMACrashReportingStateEnabledKey constant starting from version 5.4.0.

User attributes

• Renamed the YMMMutableUserProfile interface to AMAMutableUserProfile.
• Renamed the YMMProfileAttribute interface to AMAProfileAttribute.
• Renamed the YMMUserProfile interface to AMAUserProfile.
• Renamed the YMMGenderType enumeration to AMAGenderType.
• Renamed the YMMBirthDateAttribute protocol to AMABirthDateAttribute.
• Renamed the YMMCustomBoolAttribute protocol to AMACustomBoolAttribute.
• Renamed the YMMCustomCounterAttribute protocol to AMACustomCounterAttribute.
• Renamed the YMMCustomNumberAttribute protocol to AMACustomNumberAttribute.
• Renamed the YMMCustomStringAttribute protocol to AMACustomStringAttribute.
• Renamed the YMMGenderAttribute protocol to AMAGenderAttribute.
• Renamed the YMMNameAttribute protocol to AMANameAttribute.
• Renamed the YMMNotificationsEnabledAttribute protocol to AMANotificationsEnabledAttribute.

Errors

• Renamed the YMMError interface to AMAError.
• Renamed the YMMBacktraceErrorKey constant to AMABacktraceErrorKey.
• Renamed the YMMErrorReportingOptions enumeration to AMAErrorReportingOptions.
• Renamed the YMMErrorRepresentable protocol to AMAErrorRepresentable.

AdRevenue

• Renamed the YMMAdRevenueInfo interface to AMAAdRevenueInfo.
• Renamed the YMMMutableAdRevenueInfo interface to AMAMutableAdRevenueInfo.
• Renamed the YMMAdType enumeration to AMAAdType.

ECommerce

• Renamed the YMMECommerceAmount interface to AMAECommerceAmount.
• Renamed the YMMECommerceCartItem interface to AMAECommerceCartItem.
• Renamed the YMMECommerceOrder interface to AMAECommerceOrder.
• Renamed the YMMECommercePrice interface to AMAECommercePrice.
• Renamed the YMMECommerceProduct interface to AMAECommerceProduct.
• Renamed the YMMECommerceReferrer interface to AMAECommerceReferrer.
• Renamed the YMMECommerceScreen interface to AMAECommerceScreen.
• Renamed the YMMECommerce interface to AMAECommerce.

Revenue

• Renamed the YMMMutableRevenueInfo interface to AMAMutableRevenueInfo.
• Renamed the YMMRevenueInfo interface to AMARevenueInfo.
  • Removed the -initWithPrice:currency: constructor, use -initWithPriceDecimal:currency:.
  • Removed the -initWithPrice:currency:quantity:productID:transactionID:receiptData:payload: constructor, use -initWithPriceDecimal:currency:quantity:productID:transactionID:receiptData:payload:.

Add the import to all files where you use crash or error API resources:

#import <AppMetricaCrashes/AppMetricaCrashes.h>

The crash sending logic is defined with the AMAAppMetricaCrashesConfiguration class:

AMAAppMetricaCrashesConfiguration *configuration = [[AMAAppMetricaCrashesConfiguration alloc] init];
configuration.autoCrashTracking = YES; // If this parameter is enabled, crashes are automatically sent to AppMetrca
configuration.probablyUnhandledCrashReporting = YES; // Use this parameter to enable or disable tracking of implicit failures, such as OOM crashes
configuration.ignoredCrashSignals = @[]; // This setting enables you to specify an array of UNIX signals from sys/signal.h that will be ignored by the failure tracking system
configuration.applicationNotRespondingDetection = YES; // This setting includes detecting situations when the main app thread stops responding (ANR)
configuration.applicationNotRespondingWatchdogInterval = 4.0; // Sets the time interval that the watchdog will wait before reporting the "Application Not Responding" status (ANR)
configuration.applicationNotRespondingPingInterval = 0.1; // Sets the frequency at which watchdog will check the "Application Not Responding" status (ANR)
[[AMAAppMetricaCrashes crashes] setConfiguration:configuration];

To send errors, use methods of the AppMetricaCrashes class. Their signature matches that of similar methods from YMMYandexMetrica, so all you need to do is replace YMMYandexMetrica with [AMAAppMetricaCrashes crashes].

[[AMAAppMetricaCrashes crashes] reportError:error onFailure:nil];
[[AMAAppMetricaCrashes crashes] reportError:error options:options onFailure:nil];
[[AMAAppMetricaCrashes crashes] reportNSError:error onFailure:nil];
[[AMAAppMetricaCrashes crashes] reportNSError:error options:options onFailure:nil];

Add the following string in each file where the WebView setting is used:

#import <AppMetricaWebKit/AppMetricaWebKit.h>

You need to replace the WKUserContentController instance with the instance of the AMAJSController wrapping. Replace:

WKUserContentController *userController = [[WKUserContentController alloc] init];
[YMMYandexMetrica initWebViewReporting:userController onFailure:nil];

with

WKUserContentController *userController = [[WKUserContentController alloc] init];
[AMAAppMetrica setupWebViewReporting:[[AMAJSController alloc] initWithUserContentController:userController] onFailure:nil];

If dependencies are set via Xcode

Exclude AppMetricaAdSupport from Frameworks, Libraries, and Embedded Content for your target.

When using the Package.swift manifest

Disable the AppMetricaAdSupport module:

 .target(
    name: "MyTargetName",
    dependencies: [
       .product(name: "AppMetricaCore", package: "AppMetrica"),
       .product(name: "AppMetricaCrashes", package: "AppMetrica"),
       .product(name: "AppMetricaWebKit", package: "AppMetrica"),
       // .product(name: "AppMetricaAdSupport", package: "AppMetrica"), // This module is disabled
    ]
 ),