Hello All,
I was recently tasked with implementing Firebase Dynamic Links into my company's Xamarin Forms App. They are used to advertise your app. I combed online as much as I could looking for a guide/example/github that explained this or already implemented it. Without finding anything specific, I combined the resources I could find to accomplish this task. I will try my best to document and explain how I got this working, hopefully helping you out or at least pointing you in the right direction.
I currently have only done it in the Android project of my app, so most of this will apply directly to android. I will work on finishing and documenting the iOS implementation in the future.
Disclaimer: I'm not an expert, any or all of this could be wrong. It's just what worked for me and my basic understanding. Please let me know if there are any errors and let's improve our collective intelligence of the Xamarin Community
If you don't already know what Dynamic Links are, watch the 2 min video, it's a great overview. https://firebase.google.com/docs/dynamic-links/
The Setup
Setup is broken up into 2 parts.
Part 1 - Configure the Dynamic Links in the Firebase Console (Easy)
Part 2 - Configure your app to be able to receive and process the Deep Links (Not as Easy)
Part 1 - Configure the Dynamic Links in the Firebase Console (Easy)
1- Setup a free firebase account at https://firebase.google.com/
2- Create a project.
3- Create a new dynamic link, the tab is at the bottom of the 'Grow' section.
It will generate a static domain name for you based off of your project name. Ex. 'https://myproject.page.link'
Short Link url is what users will click on to navigate to your appstore or launch your app.
Deep Link url is what actually gets sent into your app for you to work with. Ex 'https://myproject.com/MainPage'
iOS behavior. Currently set mine to open the link in a url browser, as my app is not connected to it yet.
Android behavior Very Important but not as hard as my explanation makes it look.
Here is where you register your app with firebase. The package name should be easy, use the same one as defined in your
apps Android properties. Ex 'com.mycompany.appname'
Adding the signing certs SHA-1 and SHA-256 are required for Dynamic Links, which is what we are doing here.
Microsoft has a great guide on this, better than I can explain. here
Download the google-services.json file - You will need it later. Also, you will need the one that has incorporated the SHA cert details in it.
Ignore the instructions for adding the firebase SDK, we will add these to our project later using Nuget packages.
When this is all done your app should be selectable in a dropdown for the android behavior.
Finally, add any extra tags to your dynamic link url if you want, its optional.
And that's it! Now you should have a working short link. When used on an android device it should already be able to determine if the app is already installed or not, and then either direct the user to the play store or open the app. However, it won't do anything with that deep link url that you set. That brings us to the next part.
Part 2 - Configure your app to be able to receive and process the Deep Links (Not as Easy)
1- Versions, might be important.
2- Nuget Packages - Hopefully this goes smoother for you than it did for me.
3- The Code
3a- Intent Filters
3b- Handling the Deep Link
1- Versions.
I was having a lot of issues trying to get dynamic/deep linking to work. So I went back and updated everything to the newest versions available at the time.
Visual Studio Professional 2017 - 15.7.5
.NET Framework 4.7.03056
Xamarin 4.10.10.2
Xamarin.Android SDK 8.3.3.2
Android SDK Manager - Got the latest. Android 8.1 API 27 and Android 8.0 API 26 (Targeting 8.1 might be required)
Android Properties -
-Application - Compile using Android Version(Target Framework): Android 8.1 Oreo
-Android Manifest: Target Android Version: Use Compile SDK Version(haven't tried targetting 8.1 directly, might work). My min target is still Android 4.4 API 19 Kit Kat
2- Nuget Packages. These are just for the Android project. MyApp.Android
You shouldn't have to add anything into the .NET Standard Project, just make sure the Xamarin.Forms Versions match
Below is what I did
Update:
Xamarin.Forms - updated to 3.0.0.482510
Install:
This is where it immediately got annoying for me. Issues here are what lead me to go back and update my Android API Levels to the most recent, 8.1
Xamarin.Firebase.Dynamic.Links by Xamarin Inc v60.1142.1 is what you want to install.
The other dependencies should automatically install. In my case, they did not.
Dependency MonoAndroid,Version=v8.0 is important here. That should be the SDK API version that your app is set to compile against.
However, the other dependencies like Xamarin.GooglePlayServices.Basement (= 60.1142.1) have nested dependencies of their own that require MonoAndroid,Version=v8.1
So if you run into issues installing the Dynamic Links Package, thats where I would recommend looking first.
For my purposes, the nested dependencies were not automatically getting installed, so I went down through each of them and their lists and did them all manually. Even the ones that said not to do manually. It's only 20 or so, but my guess would be if I had my project SDK's set to 8.1 before all of this that it would have gone smoothly.
The CODE
Intent Filters
These are defined in your AndroidManifest.xml file
What do they do? They listen for instructions while your app starts.
When an app start matches a pre-defined filter(short link), they it stores your intended action or data on the Intent Class. That is where we pull the deep link from.
For us, this is what let's the android app receive and begin to process the deep link url that you set all the way back in Part 1.
The firebase dynamic link docs have a good breakdown and example of what to do. here
The android developer docs have a good example and breakdown of this also. here
NOTE Focus on whats between the activity tags. I've just included the other tags to show general structure, in case you haven't edited these before.
That is about the minimum of what you need.
The highlighted line should match the Short Dynamic Link you setup in the established in the Firebase Console.
I'd recommend using a Wildcard like I did in the path prefix.
That way you can make new Dynamic Links and your app can handle them without having to release new versions.
Handling the Deep Link
At this point if your app is launched by the short link, you should be able to catch the deep link during the android startup process and handle it how you want.
All I will cover here is a basic example of how to get the Deep Link as a string.
I pass mine to the main app project (.NET Standard Library) using a simple dependency service.
You can use it however you want though, there's actions it can take in either the App or the App.Android project.
The important thing is getting the deep link.
The firebase docs have good examples, but written in java or whatever language native android uses. here
I'll be showing mostly the same, just in C# examples
Get The Intent.
What is the intent you want to get? The deep link you are sending into your app Ex. "https://mycoolapp.com/mainpage"
You want to get it in the MainActivity. Below is an extremely simplified example, but it's just about that easy. Now you should be able to do what you want with that link inside of your app.
TIPS
Be careful if you have something that interrupts your startup procedures.
My Application uses a splash screen. Part of that is a line of code that creates a new Intent, overwriting the one sent in from the dynamic link
So I have my DeepLinkHandler fire off before that operation, and store the deep link in a static string.
Once it's in a static string I can use a dependency service from the Main App(.NET Standard Library) to call the GetDynamicLinkString method and return the deep link as a string.
How to Test Using an Emulator and Debugger
I have a simple settings page on my app. I added a field that would print the deep link, if it has one.
Fire off the emulator like normal using the debugger. The deep link field should be empty.
With the emulator still running, minimize the app.
Open a browser and enter in the short link url.
This should re-launch your app, but this time the deep link field has the url that you set on the firebase console.
Hope this is able to save someone some headaches.
-Tim