Get Started with Android

The App Center SDK uses a modular architecture so you can use any or all of the services.

You can find information about data collected by App Center on Data Collected by App Center SDKs, General Data Protection Regulation, and FAQ pages.

Let's get started with setting up App Center Android SDK in your app to use App Center Analytics and App Center Crashes. To add App Center Distribute to you app, have a look at the documentation for App Center Distribute.

1. Prerequisites

Before you begin, make sure that the following prerequisites are met:

• Your Android project is set up in Android Studio.
• You're targeting devices running Android Version 5.0 (API level 21) or later.

2. Create your app in the App Center Portal to obtain the App Secret

If you've already created your app in the App Center portal, you can skip this step.

1. Head over to appcenter.ms.
2. Sign up or log in and click the Add new button in the upper-right corner of the page, and select Add new app from the dropdown menu.
3. Enter a name and an optional description for your app.
4. Select Android as the OS and Java as a platform.
5. Click the Add new app button.

Once you've created an app, you can obtain its App Secret on the Getting Started page under 2. Start the SDK. Or, you can click Settings, and at the top right hand corner, click on the triple vertical dots and select Copy app secret to get your App Secret.

3. Add the App Center SDK modules

1. Open the project's app level build.gradle file (app/build.gradle) and add the following lines after apply plugin. Include the dependencies that you want in your project. Each SDK module needs to be added as a separate dependency in this section. If you want to use App Center Analytics and Crashes, add the following lines:

dependencies {
    def appCenterSdkVersion = '5.0.4'
    implementation "com.microsoft.appcenter:appcenter-analytics:${appCenterSdkVersion}"
    implementation "com.microsoft.appcenter:appcenter-crashes:${appCenterSdkVersion}"
}

2. Make sure to trigger a Gradle sync in Android Studio.

Now that you've integrated the SDK in your application, it's time to start the SDK and make use of App Center.

4. Start the SDK

4.1 Add the start() method

To use App Center, you must opt in to the module(s) that you want to use. By default no modules are started and you must explicitly call each of them when starting the SDK.
Insert the following line inside your app's main activity class' onCreate-callback to use App Center Analytics and App Center Crashes:

AppCenter.start(getApplication(), "{Your App Secret}", Analytics.class, Crashes.class);

AppCenter.start(application, "{Your App Secret}", Analytics::class.java, Crashes::class.java)

If you need to start App Center services separately, you should:

1. Configure or start it with the App Secret.
2. If the code can be called multiple times, check if the App Center is already configured.
3. Start the required service(s) without the App Secret.

AppCenter.configure(application, "{Your App Secret}");
if (AppCenter.isConfigured()) {
    AppCenter.start(Analytics.class);
    AppCenter.start(Crashes.class);
}

AppCenter.configure(application, "{Your App Secret}");
if (AppCenter.isConfigured()) {
    AppCenter.start(Analytics::class.java);
    AppCenter.start(Crashes::class.java);
}

If you have more than one entry point to your application (for example, a deep link activity, a service or a broadcast receiver), call start in the application custom class or in each entry point. In the latter case, check if App Center is already configured before the start call:

if (!AppCenter.isConfigured())) {
  AppCenter.start(getApplication(), "{Your App Secret}", Analytics.class, Crashes.class);
}

if (!AppCenter.isConfigured()) {
  AppCenter.start(application, "{Your App Secret}", Analytics::class.java, Crashes::class.java)
}

4.2 Replace the placeholder with your App Secret

Make sure to replace {Your App Secret} text with the actual value for your application. The App Secret can be found on the Getting Started page or Settings page on the App Center portal.

The Getting Started page contains the above code sample with your App Secret in it, you can just copy-paste the whole sample.

The example above shows how to use the start() method and include both App Center Analytics and App Center Crashes.

If you don't want to use one of the two services, remove the corresponding parameter from the method call above.

Unless you explicitly specify each module as parameters in the start method, you can't use that App Center service. In addition, the start() API can be used only once in the lifecycle of your app – all other calls will log a warning to the console and only the modules included in the first call will be available.

For example - If you just want to onboard to App Center Analytics, you should modify the start() API call as follows:

AppCenter.start(getApplication(), "{Your App Secret}", Analytics.class);

AppCenter.start(application, "{Your App Secret}", Analytics::class.java)

Android Studio automatically suggests the required import statements once you insert the start() method, but if you see an error that the class names aren't recognized, add the following lines to the import statements in your activity class:

import com.microsoft.appcenter.AppCenter;
import com.microsoft.appcenter.analytics.Analytics;
import com.microsoft.appcenter.crashes.Crashes;

import com.microsoft.appcenter.AppCenter
import com.microsoft.appcenter.analytics.Analytics
import com.microsoft.appcenter.crashes.Crashes

You're all set to visualize Analytics and Crashes data on the portal that the SDK collects automatically.

Look at the documentation for App Center Analytics and App Center Crashes to learn how to customize and use more advanced functionalities of both services.

To learn how to get started with in-app updates, read the documentation of App Center Distribute.

5. Backup rules (Android only)

If you use auto-backup to avoid getting incorrect information about devices, follow the next steps:

5.1. For Android 11 (API level 30) or lower.

1. Create appcenter_backup_rule.xml file in the res/xml folder.

2. Open the project’s AndroidManifest.xml file. Add the android:fullBackupContent attribute to the <application> element. It should point to the appcenter_backup_rule.xml resource file.

android:fullBackupContent="@xml/appcenter_backup_rule"

3. Add the following backup rules to the appcenter_backup_rule.xml file:

<full-backup-content xmlns:tools="http://schemas.android.com/tools">
      <exclude domain="sharedpref" path="AppCenter.xml"/>
      <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
      <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
      <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
      <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
  </full-backup-content>

5.2. For Android 12 (API level 31) or higher.

1. Create appcenter_backup_rule.xml file in the res/xml folder.

2. Open the project’s AndroidManifest.xml file. Add the android:dataExtractionRules attribute to the <application> element. It should point to the appcenter_backup_rule.xml resource file.

android:dataExtractionRules="@xml/appcenter_backup_rule"

3. Add the following backup rules to the appcenter_backup_rule.xml file:

<data-extraction-rules xmlns:tools="http://schemas.android.com/tools">
    <cloud-backup>
        <exclude domain="sharedpref" path="AppCenter.xml"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
        <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
        <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
    </cloud-backup>
    <device-transfer>
        <exclude domain="sharedpref" path="AppCenter.xml"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
        <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
        <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
        <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
    </device-transfer>
</data-extraction-rules>