• Article

Connect(); 2017

Volume 32 Number 13

Visual Studio - Introducing App Center

By Matt Gibbs; 2017

Get started for free with App Center

App Center is a collection of services that help you build better apps faster. It brings together the beta distribution and crash analytics features of HockeyApp and the Xamarin Test Cloud ability to run application tests on physical devices. It provides cloud build services so that you can have “continuous integration” running for every code committed to a branch. App Center also provides app usage analytics and the ability to segment users and send them push notifications. You can choose to use just one of the services as part of your app development lifecycle, or combine them into a complete DevOps process.

In this article, I show how to get started with the services of App Center to build, test, distribute, monitor and improve your apps. I’ll use an Android app as an example, but you should note that App Center currently supports multiple OSes and development platforms. The configuration details vary, but the key concepts are the same.

Create an App Center account. Browse to appcenter.ms and select the type of credentials to use. App Center currently supports authenticating with accounts from Microsoft, GitHub, Facebook and Google. Or you can create an account with an e-mail address and App Center password.

Create an App. Click on the New App button and select the Operating System and Platform. OS choices include iOS, Android and Windows. Currently supported development platforms are Xamarin, Java, Objective-C, Swift, React Native and Universal Windows Platform (UWP).

Build

If you’re the only dev working on a project, you may just build everything locally. When there is a team of developers working on a project, you might prefer centralized build support. Instead of maintaining your own lab infrastructure, connect App Center to your source code repository and have it do builds for you. Builds can be triggered manually, or you can use Continuous Integration to have App Center build every time new code is pushed to the branches you specify.

Connect to your repo. The navigation sidebar lists the App Center services. Click Build and select the service that hosts your source code. App Center currently supports Git repositories hosted on Visual Studio Team Services (VSTS), Bitbucket and GitHub. You’ll be prompted to authorize access for App Center. The permissions allow App Center to clone repos and configure webhooks for triggering builds automatically. Select the app repository.

Configure the build. App Center displays the branches of the repo. Select a branch to configure. App Center inspects the build files to determine what modules and build variants are available. Figure 1 shows the build configuration options. By default, a build is triggered whenever code is pushed to the branch.

Build Configuration
Figure 1 Build Configuration

You can trigger a build when saving the configuration to validate that things are set up correctly. The builds for a branch are listed, showing when the build was triggered, the commit messages, a build number and the build status. The status is first set to queued until assigned to a host, when it changes to building. The build will complete with a status of canceled, failed or succeeded.

While the build is running, you can monitor the build output in real time. After the build completes, you have the option to download the logs or the build application package. App Center builds can run unit tests and static code analysis (lint). The build will fail if the unit tests fail or linting reports errors.

Sign the build. Before a build can be installed and run on a device, it must be signed. You can have the keystore in the repo with passwords checked in to gradle files. I don’t like or recommend putting credentials in sources, so I uploaded the keystore and credentials separately.

Launch test. App Center build provides the option to test on a real device. This can be enabled without providing your own signing details. The test cloud infrastructure requires that the application have Internet permissions. If you haven’t already declared the permission, add the following line to your AndroidManifest.xml:

<uses-permission android:name=
    "android.permission.INTERNET" />

App Center will sign and deploy the app to a real device and perform a basic launch test to ensure that the application package can be installed and run.

Test

Test in the cloud, on real devices. Testing your app locally on an emu­lator is different than running it on a real device. App Center can deploy your tests, along with your application, to real devices. It captures screenshots at the test steps you define, and provides complete logs of the test run. This gives you access to thousands of device configurations (a specific device model with a specific version of the OS).

Define device sets. Devices in App Center are classified into three tiers according to their popularity. App Center maintains more of the tier 1 devices. Devices are moved from tier 1 to tier 2, and eventually to tier 3. When tests execute, wait times for lower-tier devices may be longer than wait times for tier 1.

Test runs are executed against a collection of devices. In the Test area, click on Device Sets to manage your Device Set definitions. Figure 2 shows the hundreds of Android device configurations available. You can search and filter by form factor, OS version, CPU, device tier, memory, manufacturer and name.

New Device Set
Figure 2 New Device Set

Write tests. The App Center recommendation is to use the testing framework native to the platform. Espresso is the recommended framework for Android. For detailed documentation of Espresso, see bit.ly/2mkW6WZ.

The application and tests need to be updated to run in App Center before you upload them. App Center provides a ReportHelper object that aids in navigating the test report. To make the ReportHelper available at compile time for Espresso tests, include the following dependency in the application gradle file:

dependencies {
  androidTestImplementation(‘com.xamarin.testcloud:espresso-support:1.1’)
}

Add the Test Cloud imports to your test classes:

import com.xamarin.testcloud.espresso.Factory;
import com.xamarin.testcloud.espresso.ReportHelper;

Instantiate the ReportHelper in each test class:

@Rule
public ReportHelper reportHelper = Factory.getReportHelper();

Use the ReportHelper to label the test steps. App Center will annotate the test report with the labels and capture a screenshot of the running app at that point in the test. Use the @After annotation to include a label at the end of the testing. If a test fails, the @After screenshot shows the final state. This can be extremely helpful in figuring out why a test run failed.

@After
public void TestComplete() {
  reportHelper.label(“Test Complete”);
}

Compile. To run the tests on devices in the cloud requires uploading the application package and the test package. Create them both with the following commands:

gradlew assembleDebug
gradlew assembleDebugAndroidTest

Install the CLI. To upload and initiate test runs requires the App Center CLI. To run the CLI, you need at least version 6.3 of Node.js (nodejs.org). Install the CLI using npm:

npm install -g appcenter-cli

Log in to App Center:

appcenter login

You will be redirected to the browser to complete the login and get an auth token for the CLI. The CLI is accessing the App Center REST API. The same auth token can be used to access the API directory.

Define a Test run. In the Test area, click on Test runs to see the history and status of tests. A test run is the combination of a test package run on a device collection. You specify a test series label for each test run so that results can be grouped. You can have test packages focused on different areas of functionality and reuse device collections with different test packages. Click on New Test run and create a new device collection, or select one you’ve already defined. Specify the test series label, system language of the devices and the test framework. App Center now displays instructions for using the CLI to upload the test files and initiate the test run. Copy the command from the portal and paste it into your shell. Customize the parameters for your local setup.

Here’s the command for uploading my locally built packages and running the tests against my latest-Android device set. The results are part of the main-activity test series:

appcenter test run espresso --app "mattgibbs/Hello-App-Center"
  --devices "mattgibbs/latest-android" 
  --app-path app\build\outputs\apk\debug\app-debug.apk 
  --test-series "main-activity" --locale "en_US" 
  --build-dir app\build\outputs\apk\androidTest\debug

The CLI performs the upload, then lists the devices to be used for the test run. As the tests are deployed to devices, it polls the API for the test run to show progress.

Get started for free with App Center

Distribute

App Center helps you distribute your app to testers and beta users before submitting it to an app store for public release. To install on iOS devices, you must first register the device with your Apple developer account and add it to a provisioning profile. When the app is signed based on that provisioning profile, it can be installed on those devices. Attempting to install it on another device will fail. App Center streamlines the process of gathering the necessary device identifiers from testers, performing the registration and signing. Android apps do not require the extra device registration step prior to signing.

Apps are shared with a distribution group. A Collaborators distribution group is automatically populated with all the users that have been added to the app as a Manager, Developer or Viewer. Distribution groups can also include testers invited by e-mail address. When you add a new tester, they’re sent an e-mail inviting them to test the app. Figure 3 shows the invitation that testers receive. By default, distribution groups require testers to log in to the App Center install site to view the list of apps that have been shared with them and see the download links. When you create a distribution group, you can choose to allow public access; the testers will not be required to log in.

Tester Invitation
Figure 3 Tester Invitation

Signed builds produced by App Center can be distributed directly to a distribution group. Select the build and click Distribute. You can select an existing distribution group. The release notes are pre-populated with the commit text from the build. You can update the release notes using markdown. Members of the distribution group are sent an e-mail announcing the release. The install site displays the release notes.

Crash Reporting

You can enable your app to send crash errors to App Center. The crashes are processed to identify groups of the same type of crash. The stacktrace helps you identify where in the source code the crash is occurring. The App Center SDK is modular, so that you can avoid adding overhead to your app for SDK functionality you aren’t using. The SDKs have been open sourced on github.com in the Microsoft organization. To integrate App Center into your app, update the dependencies section of the build.gradle file for your app to include the following:

def appCenterSdkVersion = '1.0.0'
compile "com.microsoft.appcenter:appcenter-crashes:${appCenterSdkVersion}"

Update the onCreate method of your MainActivity to call the start method of AppCenter. One of the arguments is the application key provided by App Center. You can see it in the Settings page for the app. Additionally, you pass references to the modules you want to use. In this example, I’m enabling Crash reporting and App Center Analytics:

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanseState);
  AppCenter.start(getApplication(), 
  appSecret:”your-app-key”, Analytics.class, Crash.class);
}

Crashes aren’t sent immediately when the crash happens. The data is collected and sent when the user next launches the app. This allows you to customize the SDK behavior if you want to present the user with more information about crash reporting and get user consent to send additional data. You don’t need to build special code to crash your app deliberately. The SDK provides a method for simulating a crash, making it easy to test the integration and see how the crash reporting works.

 

Crashes.generateTestCrash();

Figure 4 shows the Crashes area of App Center. The first chart shows how many users are experiencing crashes. The second chart shows the number of crashes received by App Center. Below the charts is a list of crash groups with the number of crashes, number of affected users, version and status. Each crash group is created with a status of open.

Crash Groups
Figure 4 Crash Groups

In the crash group details page, you can change the status to closed or ignored as you work to fix the top issues affecting users. The details page shows the stacktrace of the crash, along with distribution details of the most affected device and OS version. Individual crash reports are listed.

Click on a specific crash report to see more details. The app launch time, country, carrier, and system language setting are shown for each crash instance. If you’ve enabled the Analytics module, the details page will show all the telemetry events that occurred during the user session leading up to the crash.

You can have App Center send e-mail notifications whenever a new crash group is created. In the app settings area, you also have the option to provide a webhook URL that will be invoked for new crash groups or when new app versions are released. In the same way App Center can be connected to your repo service for build, it can also be connected to your issue tracker. When new crash groups are created, App Center will automatically create an issue for you. VSTS and GitHub are currently sup­ported. Additional integrations are coming soon.

Analytics

App Center analytics helps you understand your users. The single-­line integration provides information about how many users are using the app. When the app is installed, it’s assigned a unique identifier used for analytics. (Don’t be surprised during development if you uninstall and reinstall on the same device and see the count of active users increase. App updates continue using the same identifier.) Figure 5 shows the Analytics page for the fictitious Contoso Air app.

App Center Analytics
Figure 5 App Center Analytics

The App Center SDK is modular. To enable gathering and sending analytics data, add the module in the dependencies.

def appCenterSdkVersion = '1.0.0'
compile "com.microsoft.appcenter:appcenter-analytics:${appCenterSdkVersion}"

Override the onCreate method and start the App Center modules you’re using:

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanseState);
  AppCenter.start(getApplication(), 
  appSecret:”your-app-key”, Analytics.class, Crash.class);
}

App Center shows the distribution of sessions, devices, countries, languages and app version. It also provides the distribution of OS version. For Android, the API level is shown. Countries are identified by the carrier country provided by the platform. Language is based on the user’s system settings. You can filter by version and time range. App Center shows distributions for 7, 30, 60 and 90 days, along with trends against the previous time period. The API allows you to query for custom date ranges up to 90 days.

A session is started when the user first launches the app. When an app is resumed, if it was in the background for less than 20 seconds, it isn’t considered a new session. This avoids incorrectly treating every short interruption as the end of a session. The session duration is calculated by looking at all App Center telemetry coming from the app. They’re grouped into duration “buckets” to give you a sense of how long users are interacting with the app. If you don’t add any custom events for tracking, the sessions will all be in the 0-10 second bucket unless the app crashes.

Track Events. You can instrument your app with custom events to understand exactly how the app is being used. App Center will count up to 200 unique event names per day. Event names are limited to 256 characters in length:

Analytics.trackEvent("Login");

The event analytics provide details about the count of the event, the number of users with the event, the count per user and the count per session. It also provides the changes in counts over time. You can also associate name/value properties with an event. App Center analytics will provide the distribution of the top-10 values for each property name:

Map<String, String> properties = new HashMap();
properties.put("category", "image");
properties.put("filetype", "png");
Analytics.trackEvent("File upload", properties);

Export Data. App Center analytics will keep 90 days of data. If you want to do analytics over longer periods of time or do ad hoc and custom query processing, you can configure continuous export of the analytics data from App Center. The two options for export are Azure App Insights and Azure Blob Storage. When you setup an export to Azure App Insights, a schema for App Center data is configured. If you were previously using HockeyApp with App Insights, your existing queries can be reused. Exporting to Azure blob storage provides additional flexibility to import your data to an on-premises data warehouse or into other Big Data processing systems in Azure.

App Center is mission control for your apps. It brings together the key services you need to build better apps faster. You can have continuous integration for your app that includes running tests on real devices. You can distribute to beta users and leverage crash handling to identify and fix critical problems before releasing to the public. And you can instrument your app to get a deep understanding of how the app is used to better engage with the users.

App Center Release Automation

App Center can automate store releases. After an Android app has been published to the Google Play store for the first time, subsequent releases can be initiated from App Center. Publishing to Google Play requires a developer account. Register at bit.ly/2hx6pp4. Use the Google Play Console to first publish the app and to create an API project. You must have an API project for calling the publishing APIs.

App Center uses server-to-server authentication to publish to the store. On the API Access page of the Google Play Console, create a service account. Select Project Owner as the role with a new private JSON key type. The JSON file will be downloaded by the browser. Keep this file secure.

After the service count is created and the JSON private key generated, click Grant Access. The JSON key can now be used to authenticate as the service account with the project owner role.

In App Center, the Stores feature is in the Distribute area. When you create a connection to the Google Play store, App Center will prompt you to upload the JSON key that was generated for the service account and connect to the store. The connection will show alpha, beta and production tracks for publishing.

The next time you’re ready to publish through Google Play, navigate to the Stores area of App Center, and select the destination track. App Center will soon support the option to select a package built in App Center instead of uploading it. Production track releases require the application package version be greater than the currently published version. Also note that store releases must be release builds, and signed with a key store, as well as zipaligned.

The release initially shows a status of submitted. App Center delivers the package to Google Play and the status is updated to “published.” It can take up to 24 hours before the package is released and available for download. 

Get started for free with App Center

Matt Gibbs works as a group engineering manager at Microsoft, delivering services and SDKs for mobile app developers. In previous years, he worked on Azure SDKs, Xbox Live Services, ASP.NET, Windows Forms, IIS and “classic” Active Server Pages.

Thanks to the following Microsoft technical experts for reviewing this article: Scott Densmore and Thomas Dohmke

Discuss this article in the MSDN Magazine forum