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:
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.
- Fabric Xamarin SDK on Github
- Mike Irving’s Xamarin Android Fabric Blog
- Fabric NuGet Package
- Crashlytics NuGet Package
- Apple Developer Portal
- MichelMoreira’s Xamarin Forum Post
- Xamarin App (PCL, Shared, Prism, Anything!
- Apple Developer Account (Actively Enrolled)
- A Mac (Or access to a mac)
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.
Now you should name your app, this name can be anything (but make it related to your app)
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:
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.
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:
Register the App Id and it should now be visible on the App Id’s page.
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.
Create a new Development profile for iOS App Development.
On the next screen select the App ID that you just created:
On the next screen you should select the distribution certificates that you want to associate with this provisioning profile and continue.
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.
Continue and create your Provisioning Profile, you should now be able to see it back on the Provisioning Profile page.
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.
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.
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!
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.
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.
Once you are logged in you should go onto the main menu and click + New App.
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.
Now Fabric will ask you what products you wish to install, select Crashlytics.
The first thing you will need to do is add a run script to your Xcode project.
Copy the command that Fabric gives you and navigate to your Xcode project. In your Xcode project file navigate to Build Phases.
Click on the + button (top left, beneath the app icon) and add a new Run Script Phase
Now open up the new run script and copy in the text that Fabric gave you.
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.
Now the frameworks we need should have been installed into our Xcode project, you should now see them in the Navigation Window.
Now Fabric wants you to add some code to the app delegate, copy this across.
Your App Delegate should look like this:
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).
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.
Now we are ready to integrate Fabric & Crashlytics into our Xamarin.iOS project. On packages add the following Nuget packages: Fabric, Crashlytics.
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:
Your app delegate should now look something like this (if you made a blank project)
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!
At 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.
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.
Now archive the project, Build -> Archive for Publishing
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).
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.
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).
Load up the Fabric plugin and Log In, Select your organisation and now you should be able to add Crashlytics directly to your app.
Click on Crashlytics and on the next page, Install.
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.
Now you will need to Build & Run your app.
One it has ran on your device, it should say in the Fabric plugin that Crashlytics is installed.
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.
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:
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:
<meta-data android:name="io.fabric.ApiKey" android:value="YOUR_API_KEY_HERE" />
<?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.
You will need to give your app permission to use the internet (if you haven’t already).
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.
Right click the “crashlytics-build.properties” file and ensure that the build action is set to “AndroidAsset”
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.
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:
Your MainActivity.cs will now look something like this (assuming you haven’t dont anything else in the app)
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.
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.
Crashlytics is now setup, it’s time to distribute our app!
Android – Archiving & Distribution
The big moment is here, Distribution!
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.
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.
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.
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.
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.
Your app has now been published and is ready to be distributed!
In Android Studio load up the Fabric plugin, find your app and click on the archive button (shown above)
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.
Now write your release notes and you are ready to go!
Hit distribute and your build will be uploaded and distributed!
You should now see all of your testers as you normally would using Fabric.
If this article helped you, please let me know by commenting below.
You can find me on the following sites: