Migrating to version 6.0.0
When you migrate your app from com.yandex.android:mobmetricalib
to io.appmetrica.analytics:analytics
, the main IDs and data will be preserved. That means the transition to the new version should not result in issues or anomalies in the reports.
Running two versions of AppMetrica SDK in parallel
We renamed the group and main artifacts. As a result, you can use two versions of AppMetrica SDK in your app in parallel: com.yandex.android:mobmetricalib
and io.appmetrica.analytics:analytics
. This might occur in some cases.
1. The app dependencies will include dependencies for both versions of AppMetrica SDK.
Alert
We strongly advise against running com.yandex.android:mobmetricalib
and io.appmetrica.analytics:analytics
with the same API_KEY
in the app code. In other words, you can't use the same API_KEY
to enable both YandexMetrica
and AppMetrica
at the same time. While that won't cause crashes or failures in the app, it will distort and disrupt the statistics. When migrating to io.appmetrica.analytics:analytics
, make sure the app doesn't have any dependencies for com.yandex.android:mobmetricalib
. Also check that the app code doesn't include class imports from the com.yandex.metrica
package.
2. One of the app dependencies will transitively pull the AppMetrica SDK dependency.
If the application and libraries use different API_KEYs, this situation is acceptable but not desirable. The statistics should be collected normally, though minor deviations are possible. In that case, the app size might increase slightly since the AppMetrica app will include two SDKs instead of one.
AppMetrica SDK and AppMetrica Push SDK compatibility
When updating AppMetrica SDK to version 6.0.0, we recommend using AppMetrica Push SDK 2.3.3, which supports both com.yandex.android:mobmetricalib
and io.appmetrica.analytics:analytics
.
Migration guide
The guide contains examples demonstrating the differences between SDK versions 5.3.0
and 6.0.0
. This section only covers methods that do not have backward compatibility.
To migrate to the new version, follow these steps:
- Change the dependency from
com.yandex.android:mobmetricalib:5.3.0
toio.appmetrica.analytics:analytics:6.0.0
. - In the project code, replace the classes and methods that have been simply renamed or only changed their package. The changes you need to make are listed in the section on class renaming.
- Temporarily comment out the code with the other errors to ensure that the project can be built.
- To ensure you only run the new AppMetrica version, follow the instructions in the section.
- If you use the plugin from
com.yandex.android:appmetrica-build-plugin
, update it to the version listed in the section. - Change any exclude rules there are. The required changes are indicated in the dependency renaming section.
- Edit the code you commented out by following the other paragraphs in this guide. If you have any questions, contact support.
Renamed classes
- Replaced the
com.yandex.metrica
package withio.appmetrica.analytics
. - Replaced the
com.google.protobuf.nano.ym
package in theanalytics-proto
project withio.appmetrica.analytics.protobuf.nano
. - Renamed the
YandexMetrica
class asAppMetrica
.- Removed
reportNativeCrash
. - Removed
requestAppMetricaDeviceID
. UserequestStartupParams
instead. - Renamed
setStatisticsSending
assetDataSendingEnabled
. - Removed
setLocationTracking(Context, boolean)
. UsesetLocationTracking(boolean)
instead.
- Removed
- Renamed the
YandexMetricaConfig
class asAppMetricaConfig
.- Renamed
Builder#withStatisticsSending
asBuilder#withDataSendingEnabled
.
- Renamed
- Renamed the
YandexMetricaDefaultValues
class asAppMetricaDefaultValues
. - Renamed the
MetricaService
class asAppMetricaService
. - Renamed the
IMetricaService
class asIAppMetricaService
. - Renamed the
YandexMetricaPlugins
class asAppMetricaPlugins
. IReporter
interface- Renamed
setStatisticsSending
assetDataSendingEnabled
.
- Renamed
ReporterConfig
interface- Renamed
Builder#withStatisticsSending
asBuilder#withDataSendingEnabled
.
- Renamed
Renamed dependencies
- Renamed the
com.yandex.android:mobmetricalib-ndk-crashes
module asio.appmetrica.analytics:analytics-ndk-crashes
. Only version 3.0.0 and later is supported. - Renamed the
module com.yandex.android:mobmetricalib-identifiers
module asio.appmetrica.analytics:analytics-identifiers
.
How to make sure you're only running the new version
Because the library name was changed, there is a chance that both the old and the new AppMetricas will be used in parallel. That could lead to abnormal behavior. To avoid such situations, make sure the old AppMetrica is not used in the app.
To check that the com.yandex.android:mobmetricalib
dependency is not used, run this command:
./gradlew :app:dependencies
The command will display the dependencies for all your app build variants. After that, look up where com.yandex.android:mobmetricalib
is used and replace it with the new dependency.
If you did everything correctly, the following command call will return an empty response:
./gradlew app:dependencies | grep com.yandex.android:mobmetricalib
Compatibility with the crash plugin versions
Warning
The artifact name changed in the plugin.
To ensure proper desymbolization of crashes, use a crash plugin version io.appmetrica.analytics:gradle:0.8.2
or later.
Dependency exclusion
Integrating a library for getting advertising IDs
AppMetrica SDK uses io.appmetrica.analytics:analytics-identifiers
, a separate library, to obtain ad IDs. This library contains a dependency on com.google.android.gms:play-services-ads-identifier:18.0.1
, which is used to get the GAID. The io.appmetrica.analytics:analytics-identifiers
library version should correspond to the io.appmetrica.analytics:analytics
library version.
This dependency is added by default.
If you don't want to obtain advertising IDs (for example, for children's apps), exclude the library in the project's build.gradle
file:
configurations.configureEach {
exclude(group = "io.appmetrica.analytics", module = "analytics-identifiers")
}
configurations.configureEach {
exclude group: 'io.appmetrica.analytics', module: 'analytics-identifiers'
}
Integrating the location library
AppMetrica SDK uses io.appmetrica.analytics:analytics-location
, a separate library, to obtain locations. It contains a dependency on com.google.android.gms:play-services-location:19.0.1
used to get locations. The io.appmetrica.analytics:analytics-location
library version should correspond to the io.appmetrica.analytics:analytics
library version.
This dependency is added by default.
If you don't want to get locations, exclude the library in the project's build.gradle
file:
configurations.configureEach {
exclude(group = "io.appmetrica.analytics", module = "analytics-location")
}
configurations.configureEach {
exclude group: 'io.appmetrica.analytics', module: 'analytics-location'
}
Migrating the requestAppMetricaDeviceID method
Removed the YandexMetrica.requestAppMetricaDeviceID
method. Use the AppMetrica.requestStartupParams
method instead.
Warning
Make sure to request the StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH
key rather than StartupParamsCallback.APPMETRICA_DEVICE_ID
since the StartupParamsCallback.APPMETRICA_DEVICE_ID
key will return a different ID.
val startupParamsCallback = object : StartupParamsCallback {
override fun onReceive(
result: StartupParamsCallback.Result?,
) {
val deviceIdHash = result?.deviceIdHash
// ...
}
override fun onRequestError(
reason: StartupParamsCallback.Reason,
result: StartupParamsCallback.Result?,
) {
// ...
}
}
AppMetrica.requestStartupParams(
this,
startupParamsCallback,
listOf(StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH)
)
StartupParamsCallback startupParamsCallback = new StartupParamsCallback() {
@Override
public void onReceive(@Nullable Result result) {
if (result != null) {
String deviceId = result.deviceId;
String deviceIdHash = result.deviceIdHash;
String uuid = result.uuid;
}
}
@Override
public void onRequestError(@NonNull Reason reason, @Nullable Result result) {
// ...
}
};
AppMetrica.requestStartupParams(
this,
startupParamsCallback,
Arrays.asList(StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH)
);
Removal of the deprecated Revenue#newBuilder(double, Currency) method
- Removed the previously
@deprecated
Revenue#newBuilder(double, Currency)
method. UseRevenue#newBuilder(int, Currency)
instead, whereint
implies the use ofrevenueMicros
. - Renamed the
Revenue#newBuilderWithMicros(int, Currency)
method asRevenue#newBuilder(int, Currency)
.
If you didn't find the answer you were looking for, you can use the feedback form to submit your question. Please describe the problem in as much detail as possible. Attach a screenshot if possible.