Using Crashlytics With Xamarin Apps

Hello and welcome to my tutorial on integrating Fabric & Crashlytics into your cross platform Xamarin application. The process is not well explained online and I have just gone through the tripe of figuring it out myself so I figured it would be a useful thing to document!

This guide is going to be quite long so I have split the entries up into their own self contained sections. This is the master article that runs through everything, start to finish. If you just wanted to learn about a particular area, you can find links to each section (taken from this article) in the Table of Contents below.

Before you read any further, you must have an actively enrolled apple developer account to be able to release beta distributions of your app. There is absolutely no way around this if you want to distribute your app to a small amount of testers, the only alternative is to build the app manually to each device you wish to test.

Table of Contents:

iOS

Android

Links / References

I wrote this article to help collate all of the information in integrating Fabric/Crashlytics in Xamarin. I have used all of the following sources to help write this article.

Requirements

  • Xamarin App (PCL, Shared, Prism, Anything!

For iOS:

  • Apple Developer Account (Actively Enrolled)
  • A Mac (Or access to a mac)

For Android:

Android isn’t fussy and requires nothing more than what you need to create & write a xamarin app.

 

iOS – Provisioning Profiles

Creating an App Id

Since we are going to be distributing our app for development purposes (alpha release among a closed circle of testers) we will need to create a provisioning profile

Log into your Apple Developer account here, and go to your account. The first thing we need to do is create a new App Id for our app. Go to Certificates, Identifiers & Profiles and under Identifiers select App ID’s. On this screen you should see your existing App Id’s if you have any. Create a new one by hitting the + button.Screen Shot 2018-03-02 at 14.35.56.png

Now you should name your app, this name can be anything (but make it related to your app)

Screen Shot 2018-03-02 at 14.02.41.png

Now you need to give your app a Bundle ID. This ID MUST be unique as it is used by the app store. Apple recommend that you use the following format:

“com.company.appname”

If you haven’t created your app yet, you should copy this Bundle ID and copy it into your apps info.plist. If you app already exists you can try using the current Bundle ID, but it might be taken so make sure that the Bundle ID in your app matches what you put in your Developer Profile.

Screen Shot 2018-03-02 at 14.02.50.png

At the bottom of the page hit continue, you can ignore the app[ permissions for the time being.

On the next page you can review your app’s settings:Screen Shot 2018-03-02 at 14.03.12.png

Register the App Id and it should now be visible on the App Id’s page.

Screen Shot 2018-03-02 at 14.04.12.png

Now we have our app ID setup, lets create a provisioning profile for it!

Creating a Provisioning Profile

Go to Provisioning Profiles and select All. Here you should see all of the provisioning profiles associated with your developer account. Hit the + button to create a new profile.Screen Shot 2018-03-02 at 14.04.28.png

Create a new Development profile for iOS App Development.

Screen Shot 2018-03-02 at 14.04.40.png

On the next screen select the App ID that you just created:

Screen Shot 2018-03-02 at 14.04.57.png

On the next screen you should select the distribution certificates that you want to associate with this provisioning profile and continue.Screen Shot 2018-03-02 at 14.05.39.png

Now you will want to select the devices that you want to be able to access your app. Remember that your developer profile can only manage a small amount of devices (100 or so) so this should only be used for active alpha testers.

Screen Shot 2018-03-02 at 14.05.50.png

Continue and create your Provisioning Profile, you should now be able to see it back on the Provisioning Profile page.

Screen Shot 2018-03-02 at 15.00.52.png

Using your Provisioning Profiles

Before you complete this step you should DEFINITELY close Visual Studio, and should probably close Xcode.

Open up Xcode and go to Xcode -> Preferences -> Accounts.

Select the account that you just created your provisioning profile for and click the Download Manual Profiles button.Screen Shot 2018-03-02 at 15.06.35.png

All of your profiles will be downloaded and will now be accessible by Visual Studio for use in your Xamarin project!

iOS – Integrating Crashlytics

To do this step you MUST be using a Mac that has Xcode installed. Whilst Xamarin solves the cross platform/ multiple codebase problem. It doesn’t fix the problem of needing a mac in your dev environment. In this section we will be creating an Xcode project with the same bundle identifier as our Xamarin app. We will use this to trick fabric into setting up our project & linking to our app.

Xamarin Project Setup (optional)

Lets create our Xamarin project, if you already have a working app you can just ignore this step, just make sure the App Identifier in your info.plist is the same as what you made in your developer account.

Create a new Xamarin project, it can be a shared or pcl (or even prism) this bit doesn’t matter. Create the app with whatever name you want and copy across your bundle identifier.Screen Shot 2018-03-02 at 15.20.56.png

Once your project has been created you are ready to hop into Xcode and configure Fabric.

Creating an Xcode project with Fabric

Create a new Xcode project, you will need to do this even if you have a fully functioning Xamarin App. What we are going to do is create an app with the same Bundle ID as our Xamarin App and trick fabric.

In Xcode go to File -> New -> Project and create a Single View Application. Call the project something and fill in your details, however what you call it at this point is irrelevant. We will need to change the Bundle ID manually anyway so call it whatever you want.

Note, It’s probably a good idea to label your app as iOS so that you don’t get confused which app is which later!

Screen Shot 2018-03-02 at 15.23.32.png

After your project has been created you will be greeted with the info.plist, change the Bundle ID to what you used in your developer account.Screen Shot 2018-03-02 at 15.27.50.png

You don’t need to worry about code signing in this project, only the bundle id.

Now you will need to open up the Fabric Mac app and sign in.Screen Shot 2018-03-02 at 15.29.39.png

Once you are logged in you should go onto the main menu and click + New App.

Screen Shot 2018-03-02 at 15.31.06.png

Now we just follow the installation instructions given to use by Fabric and integrate crashlytics with the Xcode project app. First select the Xcode project that you just created (it should be the top hit on the fabric browser but you could use the finder to be safe). Select the project and hit next.Screen Shot 2018-03-02 at 15.36.55.png

Now Fabric will ask you what products you wish to install, select Crashlytics.

Screen Shot 2018-03-02 at 15.39.20.png

The first thing you will need to do is add a run script to your Xcode project.

Screen Shot 2018-03-02 at 15.41.12.png

Copy the command that Fabric gives you and navigate to your Xcode project. In your Xcode project file navigate to Build Phases.

Screen Shot 2018-03-02 at 15.42.43.png

Click on the + button (top left, beneath the app icon) and add a new Run Script Phase

Screen Shot 2018-03-02 at 15.42.52.png

Now open up the new run script and copy in the text that Fabric gave you.

Screen Shot 2018-03-02 at 15.43.02.png

Now build your project (⌘+B) and Fabric should notice and prompt you to install some frameworks. Drag the frameworks into your Xcode project and accept any dialogue boxes that appear.

Screen Shot 2018-03-02 at 15.46.52.png

Now the frameworks we need should have been installed into our Xcode project, you should now see them in the Navigation Window.

Screen Shot 2018-03-02 at 15.47.04.png

Now Fabric wants you to add some code to the app delegate, copy this across.Screen Shot 2018-03-02 at 15.49.37.png

Your App Delegate should look like this:

Screen Shot 2018-03-02 at 15.50.50.png

Click next on the Fabric app and now run your Xcode project (⌘+R).

Once your app is running the Fabric app should notice and it will notify you that you are done. At this point we are done with our Xcode project, we have successfully created the Xamarin iOS app in our Fabric account. Any iOS builds will be distributed via this project.

Linking your Xamarin project to Fabric

Open up your Xamarin project and go into the iOS folder (we only need to deal with this folder, not the pcl / shared / android / other folders). Once again CHECK that your Bundle ID is THE SAME as what you entered into your developer account. I cannot stress how important this is.

Once you are sure you have the right bundle id you should open the info.plist of your Xamarin app up in Xcode (which is probably the easiest way to edit this file).Screen Shot 2018-03-02 at 16.01.21.png

Copy Fabric API Key into your Xamarin Info.plist

Next open up the info.plist of the Xcode project that we just linked to Fabric. The script we ran on the Xcode project added a reference to our fabrics API key, so we need to add this to our Xamarin app. You can simply copy and paste the row across from the Xcode project to your Xamarin project. Make sure you save this file and close it.

Screen Shot 2018-06-26 at 12.14.47.png

Now we are ready to integrate Fabric & Crashlytics into our Xamarin.iOS project. On packages add the following Nuget packages: Fabric, Crashlytics.

Screen Shot 2018-03-02 at 16.06.44.png

Both packages are published by an author named “Michel Moreira”, make sure you get the latest versions of each. You only need to install there packages to the iOS project (which is handy).

Open up the AppDelegate.cs and add the following import statements:

using FabricSdk;
using CrashlyticsKit;

And inside the DidFinishLaunchingWithOptions method add the following code:

Crashlytics.Instance.Initialize();
FabricSdk.Fabric.Instance.Initialize();

Your app delegate should now look something like this (if you made a blank project)

Screen Shot 2018-03-02 at 16.17.09.png

Run your app on a simulator and you should notice logs published by Crashlytics, Congratulations you have now linked Crashlytics to your Xamarin.iOS app!

Screen Shot 2018-03-02 at 16.19.49.pngAt this point you no longer need the Xcode project you made however I wouldn’t recommend deleting it (just in case). I would find a place to archive it and put it up on the shelf.

iOS – Archiving & Distribution

Now we have Fabric and Crashlytics integrated with our app we are ready to distribute!

Firstly you should Clean your project and Rebuild All (in Visual Studio). Now you should double click on your iOS project and setup the code signing for your app.

Screen Shot 2018-03-02 at 16.26.08.png
This is a screenshot from another project as my visual studio couldn’t seem to find the developer account I used to make this tutorial

Next you should plug in an iOS device. To archive your code you need to have a physical iOS device present. Configure the build for release and select your devices as the target.

Screen Shot 2018-03-02 at 16.21.43.png

Now archive the project, Build -> Archive for Publishing

Screen Shot 2018-03-02 at 16.30.47.png

Your project will now be built and archived, this process might take a while so be patient! Once the build has been archived you should see a list of all of the archived builds in Visual Studio. The build should also be visible in Fabric (Navigate there manually if nothing pops up, see below).

Screen Shot 2018-03-02 at 16.32.32.png

You can now hit Distribute to release your app. Bear in mind that anyone you send the app too must be registered on your Developer Provisioning Profile, you can add people to this manually but will need to release a new build before they can access the app.

This concludes the iOS integration, you should now have access to Crashlytics in your Xamarin application and all of the goodness that comes with Fabric integration!

Android – Integrating Crashlytics

In this section we will be using Android Studio to generate the API keys for Fabric. Fortunately for this step you will be able to follow along if you are on PC. Similar to iOS we will be tricking Android Studio into distributing our app. The only difference is that you will need to hang onto this project as you will need to add a build file to your Xamarin project in order to distribute the app.

Installing Fabric For Android Studio

Open up Android Studio and check the top right, if you have fabric installed you should see the following icon.

Screen Shot 2018-06-26 at 12.28.42.png
Once Fabric is installed, it appears on the far left of this toolbar.

If you don’t see this icon, you will need to install Fabric.

Go to File -> Preferences -> Plugins

Search for “Fabric” and install the plugin, reload Android Studio and you are ready to go!

 

Creating An Android Studio Project

Create a new Android Studio project, ensure that the company domain & package name are equal to your Xamarin’s package name. Complete the creation wizard (any options past this screen are irrelevant).

Screen Shot 2018-06-26 at 12.18.56.png

Load up the Fabric plugin and Log In, Select your organisation and now you should be able to add Crashlytics directly to your app.

Screen Shot 2018-06-26 at 12.37.56.png

Click on Crashlytics and on the next page, Install.

Screen Shot 2018-06-26 at 12.39.00.png

Since there is an Android Studio integration, we can let the IDE do the work for us (in terms of installing Crashlytics). On the next page simply hit Apply.

Screen Shot 2018-06-26 at 12.40.11.png

Now you will need to Build & Run your app.

Screen Shot 2018-06-26 at 12.41.43.png

One it has ran on your device, it should say in the Fabric plugin that Crashlytics is installed.

Screen Shot 2018-06-26 at 12.42.35.png

Now we can install Fabric & Crashlytics in our Xamarin Android project!

Configure Android Manifest

Now that we have created our spoof project, we can add our Fabric API keys to our xamarin app. This bit is a bit more sketchy on Android. Before you begin, ensure that the spoof projects build & version numbers match those of your app.

Screen Shot 2018-06-26 at 14.47.33.png

Ensure you do this otherwise you may have difficulty identifying different app builds in Fabric.

In Android Studio, open up your AndroidManifest.xml file, it should look like this:

Screen Shot 2018-06-26 at 14.49.46.png

Copy the api key (Highlighted above) from the manifest and open up the AndroidManifest file in your xamarin project. You will need to use an external editor to do this (I’m using Visual Studio Code) since VSC (For mac at least) won’t let you edit the source. Add the API key to your android manifest:

Api Key

<meta-data android:name="io.fabric.ApiKey" android:value="YOUR_API_KEY_HERE" />

Complete Manifest

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.axemasta.axemastaxamfabricdemo">
    <uses-sdk android:minSdkVersion="15" />
    <uses-permission android:name="android.permission.INTERNET" />
    <application android:label="Xamarin Fabric Demo">
        <meta-data android:name="io.fabric.ApiKey" android:value="YOUR_API_KEY_HERE" />
    </application>
</manifest>

Save your changes and close any external editors.

NOTE:

You will need to give your app permission to use the internet (if you haven’t already).

Screen Shot 2018-06-26 at 15.07.54.png

Configure Xamarin Project

Since we are essentially tricking Android Studio into distributing our app, we will need to copy over a build script in order to be able for Android studio to accept our app’s APK distributable.

Crashlytics Build Properties

Ensure that your android app has built & ran at least once (it should have done if you have been following along). Navigate to the following directory:

$ProjectFolder -> app -> build -> intermediates -> assets -> debug

Inside should be a file called “crashlytics-build.properties”, you will need to add this file to your xamarin project.

Open the file and check that the version numbers are correct (you can edit the file if they aren’t, it worked for me). Copy the file into the Assets folder of your Xamarin.Droid project.

Screen Shot 2018-06-26 at 15.39.34.png

Right click the “crashlytics-build.properties” file and ensure that the build action is set to “AndroidAsset”

Screen Shot 2018-06-26 at 15.40.36.png

Crashlytics Build Number

Before we complete this step, check if you already have a Strings.xml file already located in your project. In file explorer / finder navigate to:

$XamarinProject -> Droid -> Resources -> Values

If there is a file named “Strings.xml”, ensure that this is added to your xamarin project, otherwise create this file. Inside this file you will want to add the following:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="com.crashlytics.android.build_id">APP_BUILD_NUMBER</string>
</resources>

If you don’t do this, Crashlytics will throw the following (incredibly helpful) error:

"This app relies on Crashlytics. 
Please sign up for access at https://fabric.io/sign_up, 
install an Android build tool and ask a team member to invite you to this app's organization."

 

Install Fabric & Crashlytics To Your App

Firstly you will need to install the Fabric & Crashlytics NuGet packages in your Project.Droid directory.

Screen Shot 2018-03-02 at 16.06.44.png

Both packages are published by an author named “Michel Moreira”, make sure you get the latest versions of each. You only need to install there packages to the Droid project (which is handy).

Open up the MainActivity.cs and import the following namespaces:

using FabricSdk;
using CrashlyticsKit;

And inside the OnCreate method add the following code:

Crashlytics.Instance.Initialize();
Fabric.Instance.Initialize(Android.App.Application.Context);

Your MainActivity.cs will now look something like this (assuming you haven’t dont anything else in the app)

Screen Shot 2018-06-26 at 14.18.31.png

Android Crash Testing

At this point it might be a good idea to check that Crashlytics has been installed correctly.

Add the following line to the OnCreate method, anywhere after you have initialised Fabric & Crashlytics.

Crashlytics.Instance.Crash();

Now run the app (Build as release), it should crash. Make sure you read the console output to verify that the crash was legitimately caused by crashlytics. You may see the following error:

[Fabric] java.lang.IllegalArgumentException: 
Fabric could not be initialized, 
API key missing from AndroidManifest.xml. 
Add the following tag to your Application element

If this is the case, ensure you have the correct API key in your android manifest / it is in the right place!

Once you are sure that Crashlytics is correctly installed, run the app (with the crash line in). You must be building this to release (Crashlytics is disabled in debug). After the app crashes, uncomment the line and re-run the app. Once the app has loaded login to Fabric, find your app and look at the Crashlytics tab, you should see a crash.

Screen Shot 2018-06-26 at 16.40.15.png

Crashlytics is now setup, it’s time to distribute our app!

 

Android – Archiving & Distribution

The big moment is here, Distribution!

Archiving

Firstly you should run your app (preferably on a physical device), make sure the build is set to release and that the app is tested and working.

Screen Shot 2018-06-26 at 16.43.11.png

Next in Visual Studio go to Build -> Archive For Publishing. Visual studio will then archive your app, eventually you will be taken to the archive screen.

Screen Shot 2018-06-26 at 16.43.37.png

On this page you will want to select, sign and distribute. Fortunately because we are on Android this process is really easy (compared to iOS). Select Ad-Hoc for distribution.

Screen Shot 2018-06-26 at 16.45.11.png

On the signing identity page, you will need to create a signing key for your app (unless you have already created one). Create a new key, select it and continue.

Screen Shot 2018-06-26 at 16.47.23.png

On this next page press publish and you will be asked where you want to save the app. Save it to a sensible place and then enter the password for the key you just created.

Screen Shot 2018-06-26 at 16.47.33.png

Your app has now been published and is ready to be distributed!

Distributing

Screen Shot 2018-06-26 at 16.51.54.png

In Android Studio load up the Fabric plugin, find your app and click on the archive button (shown above)

Screen Shot 2018-06-26 at 16.52.19.png

Drag the Signed APK for your app into the fabric window (mine’s called com.axemasta.axemastaxamfabricdemo-Signed.apk), it should be accepted and allow you to choose testers.

Screen Shot 2018-06-26 at 16.53.57.png

Now write your release notes and you are ready to go!

Screen Shot 2018-06-26 at 16.56.05.png

Hit distribute and your build will be uploaded and distributed!

You should now see all of your testers as you normally would using Fabric.

Screen Shot 2018-06-26 at 16.56.48.png

 

The End

If this article helped you, please let me know by commenting below.

You can find me on the following sites:

2 thoughts on “Using Crashlytics With Xamarin Apps

  1. I had a strong urge to reach out and tell you well done on this amazingly friendly tutorial! Loved the pictures and detailing of even the smallest steps. I wish they were all like this. I read tutorials all the time for work and this is the best one I’ve ever come across for any subject. Thank you for making my tasks today so much simpler.

    Like

    1. Hi Kendyl glad you liked the article. I’m going to be making a new article on using Microsoft app center. Fabric has been acquired by firebase and will now be integrated into that platform. Since their support for xamarin is non existant (officially) I have moved everything I use to Microsoft App Center. Since we’re using Xamarin it’s a 5 second job (literally) to set your app up to work with Xamarin! I’ll try and get it written ASAP!

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s