# Migrating from v1

Batch SDK v2 is a major release, which introduces breaking changes from 1.x. This guide describes how to update your application when using a previous version.

### Upgrading the SDK version

To upgrade from v1 to v2, you need to change the SDK version in your `build.gralde`:

{% tabs %}
{% tab title="Kotlin" %}

```kts
implementation("com.batch.android:batch-sdk:2.0.0")
```

{% endtab %}

{% tab title="Groovy" %}

```groovy
implementation 'com.batch.android:batch-sdk:2.0.0'
```

{% endtab %}
{% endtabs %}

⚠️ Batch SDK 2.0 now requires a `minSdk` level of 21 or higher. If your application support lower Android versions, you will have to update it:

{% tabs %}
{% tab title="Kotlin" %}

```kts
android {
  ...
  defaultConfig {
    ...
    minSdk = 21
  }
}
```

{% endtab %}

{% tab title="Groovy" %}

```groovy
android {
    ...
    defaultConfig {
        ...
        minSdkVersion 21
    }
}
```

{% endtab %}
{% endtabs %}

### Core migration

#### Starting the SDK

This version introduced a new way of starting the SDK. Since `Batch.setConfig` has been removed, you will have to replace it with :

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
 Batch.start("YOUR_API_KEY")
```

{% endtab %}

{% tab title="Java" %}

```java
 Batch.start("YOUR_API_KEY");
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
You still need to start the SDK in your Application subclass and register an activity lifecycle callback.
{% endhint %}

#### Push Providers

This version also removed support for old push providers (Google Cloud Messaging and FCM Instance ID). Batch now only support for FCM's Token APIs. Overriding the Sender ID is no longer possible in any way.

You have to use `firebase-messaging` 22.0.0 or higher. We highly recommend to use the latest version when possible.

Add the following to your `build.gradle` if not already present:

{% tabs %}
{% tab title="Kotlin" %}

```kts
implementation("com.google.firebase:firebase-messaging:22.0.0")
```

{% endtab %}

{% tab title="Groovy" %}

```groovy
implementation 'com.google.firebase:firebase-messaging:22.0.0'
```

{% endtab %}
{% endtabs %}

#### Android Advertising Identifier

Android Batch SDK 1.21 had removed automatic collection of AAID (Android Advertising Identifier). This version has totally drop the support of the AAID and you can no longer set an advertising id to Batch since all related APIs have been removed.

#### Advanced Information

The Batch SDK V1 allowed you to disable advanced information generally with `setCanUseAdvancedDeviceInformation(false)`. This has been removed and replaced with a more fine-tuning control of what you want to enable with:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.updateAutomaticDataCollection {
  it.apply {
    setGeoIPEnabled(true) // Enable GeoIP resolution on server side
    setDeviceBrandEnabled(true) // Enable automatic collection of the device brand information
    setDeviceModelEnabled(true) // Enable automatic collection of the device model information
  }
}
```

{% endtab %}

{% tab title="Java" %}

```java
Batch.updateAutomaticDataCollection(config -> {
    config.setGeoIPEnabled(true) // Enable GeoIP resolution on server side
          .setDeviceBrandEnabled(true) // Enable automatic collection of the device brand information
          .setDeviceModelEnabled(true); // Enable automatic collection of the device model information
});
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
All data configurable with this API are now disabled by default and should be enabled if you want to use it.
{% endhint %}

For more information, please visit our [automatic data collection guide](/developer/sdk/android/data-privacy/data-collection.md).

#### Deprecated APIs

All deprecated APIs in the SDK v1 have been removed and some others have been renamed/reworked. To see in details the differences, please visit our [changelog](https://doc.batch.com/developer/sdk/android/advanced/pages/gh7o4aUsZ7i8Rlo8hq5K#id-2.0.0).

### Project migration

This version follows Batch's pivot to being an omnichannel platform. It allows you to collect data for your **Projects** and **Profiles**. If you are not familiar with these two concepts, please see [this guide](https://doc.batch.com/getting-started/features/customer-engagement-platform/profiles/overview) beforehand.

#### Profile Attributes

First of all, most of the user-related write APIs have been removed. Reading methods are still usable since we do not provide yet a way to get synced data for a Profile, but keep in mind that the data returned is only about your installation and not your Profile.

To interacts with our user-centered model, you should now use the `Batch.Profile` module. Let's see a migration example.

If you were previously doing something like that:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.User.editor().apply {
  setIdentifier("john.doe")
  setLanguage("en")
  setRegion("US")
  setEmail("john.doe@batch.com")
  setEmailMarketingSubscriptionState(BatchEmailSubscriptionState.SUBSCRIBED)
  setAttribute("age", 26)
  removeAttribute("firstname")
  addTag("actions", "has_bought")
  removeTag("actions", "has_bought")
  clearTagCollection("actions")
  save()
}
```

{% endtab %}

{% tab title="Java" %}

```java
Batch.User.editor()
  .setIdentifier("john.doe")
  .setLanguage("en")
  .setRegion("US")
  .setEmail("john.doe@batch.com")
  .setEmailMarketingSubscriptionState(BatchEmailSubscriptionState.SUBSCRIBED)
  .setAttribute("age", 26)
  .removeAttribute("firstname")
  .addTag("actions", "has_bought")
  .removeTag("actions", "has_bought")
  .clearTagCollection("actions")
  .save()
}
```

{% endtab %}
{% endtabs %}

You should now do:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.Profile.identify("john.doe")
Batch.Profile.editor().apply {
  setLanguage("en")
  setRegion("US")
  setEmailAddress("john.doe@batch.com")
  setEmailMarketingSubscription(BatchEmailSubscriptionState.SUBSCRIBED)
  setAttribute("age", 26)
  removeAttribute("firstname")
  addToArray("actions", "has_bought") // or addToArray("actions", listOf("has_bought"))
  removeFromArray("actions", "has_bought") // or removeFromArray("actions", listOf("has_bought"))
  removeAttribute("actions")
  save()
}
```

{% endtab %}

{% tab title="Java" %}

```java
Batch.Profile.identify("john.doe")
Batch.Profile.editor()
  .setLanguage("en")
  .setRegion("US")
  .setEmailAddress("john.doe@batch.com")
  .setEmailMarketingSubscription(BatchEmailSubscriptionState.SUBSCRIBED)
  .setAttribute("age", 26)
  .removeAttribute("firstname")
  .addToArray("actions", "has_bought") // or addToArray("actions", Arrays.asList("has_bought"))
  .removeFromArray("actions", "has_bought") // or removeFromArray("actions", Arrays.asList("has_bought"))
  .removeAttribute("actions")
  .save()
}
```

{% endtab %}
{% endtabs %}

For more information, please see the following sections :

* [Custom user id](/developer/sdk/android/profile-data/custom-user-id.md)
* [Custom region/language](/developer/sdk/android/profile-data/custom-locale.md)
* [Custom user attributes](/developer/sdk/android/profile-data/attributes.md)
* [Email subscription](/developer/sdk/android/profile-data/email-subscription.md)

#### Profile Data migration

To make it easier to collect data to a Profile, Batch has added two automatic ways to migrate old installation's data on a Profile. So the first time a user will launch your application running on v2 :

* He will be automatically identified (logged-in) if he had a Batch `custom_user_id` set on the local storage.
* Its natives (language/region) and customs data will be automatically migrate to a Profile if your app is attached to a Project.

These migrations are enabled by default, but you may want to disable them, to do so add the following before starting the SDK:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
class YourApp : Application() {
  
  override fun onCreate() {
    super.onCreate()
    // Disable profile's migration
    Batch.disableMigration(
      EnumSet.of( 
        // Whether Batch should automatically identify logged-in user when running the SDK for the first time.
        // This mean user with a custom_user_id will be automatically attached a to a Profile and could be targeted within a Project scope.
        BatchMigration.CUSTOM_ID,  
        // Whether Batch should automatically attach current installation's data (language/region/customDataAttributes...)
        // to the User's Profile when running the SDK for the first time.
        BatchMigration.CUSTOM_DATA
      )
    )
    // Then start the sdk
    Batch.start("YOUR_API_KEY")
    registerActivityLifecycleCallbacks(BatchActivityLifecycleHelper())
  }
}
```

{% endtab %}

{% tab title="Java" %}

```java
public class YourApp extends Application {
  
  @Override
  public void onCreate() {
    super.onCreate();
    // Disable profile's migration
    Batch.disableMigration(
      EnumSet.of(
        // Whether Batch should automatically identify logged-in user when running the SDK for the first time.
        // This mean user with a custom_user_id will be automatically attached a to a Profile and could be targeted within a Project scope.
        BatchMigration.CUSTOM_ID,
        // Whether Batch should automatically attach current installation's data (language/region/customDataAttributes...)
        // to the User's Profile when running the SDK for the first time.
        BatchMigration.CUSTOM_DATA
      )
    );
    
    // Then start the sdk
    Batch.start("YOUR_API_KEY");
    registerActivityLifecycleCallbacks(new BatchActivityLifecycleHelper());
  }
}
```

{% endtab %}
{% endtabs %}

For more information, please visit our [profile data migration guide](/developer/sdk/android/profile-data/data-migration.md)

#### Event data

Android Batch SDK v2 introduced two new types of attribute that can be attached to an event : **Array** and **Object**.

What's changed:

* `BatchEventData` has be renamed into `BatchEventAttributes`
* `addTag` API is no longer available and has been replaced by `putStringList` with the `$tags` reserved key.
* Optional `label` parameter is no longer available and has been replaced by a `$label` reserved key under `BatchEventAttributes`.

{% hint style="info" %}
Limits are unchanged and still 200 chars max for $label and 10 items max for $tags .
{% endhint %}

So if you were previously doing something like:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.User.trackEvent("read_article", "sports", BatchEventData().apply {
    addTag("squash")
    addTag("daily_digest")

    put("premium", true)
    put("id", "123456")
})
```

{% endtab %}

{% tab title="Java" %}

```java
BatchEventData data = new BatchEventData();
data.addTag("squash");
data.addTag("daily_digest");

data.put("premium", true);
data.put("id", "123456");
Batch.User.trackEvent("read_article", "sports", data);
```

{% endtab %}
{% endtabs %}

You should now do:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.Profile.trackEvent("read_article", BatchEventAttributes().apply {
  put("premium", true)
  put("id", "123456")
  put("\$label", "sports")
  putStringList("\$tags", listOf("squash", "daily_digest"))
})
```

{% endtab %}

{% tab title="Java" %}

```java
  BatchEventAttributes attributes = new BatchEventAttributes();
  attributes.put("premium", true)
            .put("id", "123456")
            .put("$label", "sports")
            .putStringList("$tags", Arrays.asList("squash", "daily_digest"));
  Batch.Profile.trackEvent("read_article", attributes);
```

{% endtab %}
{% endtabs %}

For more information, please visit our [custom event guide](/developer/sdk/android/profile-data/events.md).

To see in details what's precisely changed since V1 please consult our [changelog](https://doc.batch.com/developer/sdk/android/advanced/pages/gh7o4aUsZ7i8Rlo8hq5K#id-2.0.0) or visit the [APIs Reference](https://batchlabs.github.io/Batch-Android-SDK/).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.batch.com/developer/sdk/android/advanced/2x-migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.