Deep Links in Android: Getting Started

Having URLs that redirect to specific parts of an app is useful in marketing and user engagement. Deep links let you redirect users to a specific destination inside your app which provides better user experience.

In this tutorial, you’ll build PromoApp, an app that lets users navigate to a specific page by clicking a link. During the process you’ll learn about:

• Deep link basics.
• Creating and testing deep links.
• Getting data from deep link URLs.
• Handling deep links when the user doesn’t have your app installed.

Getting Started

Download the materials using the Download Materials button at the top or bottom of this tutorial. Open Android Studio 4.1 or later, and import the starter project.

Now, build and run the project. You’ll see the following screen:

The screen shows a product with an image, name, brand and price. Since everybody loves promotions you’re going to use deep links to add functionality to apply discounts to the product.

First, take a moment to learn about deep links.

Understanding Deep Links

A deep link is a URL that navigates to a specific destination in your app. When you click a deep link, Android:

• Opens the user’s preferred app that can handle the link, if it’s available.
• If the preferred app isn’t available, it opens the only app that can handle the link.
• If multiple apps can handle the link, it opens a dialog that lets the user select from one of the apps that can open the link.

Now you know what a deep link is. Next, you’ll learn about the different parts of a deep link.

Building Blocks of a Deep Link

Consider the link https://www.raywenderlich.com/test/code=abcd. It has the following parts:

• https: Identifies the protocol used to access the resource on the internet.
• www.raywenderlich.com: The host, which is the name or address of the web server being accessed.
• /test: The path which specifies a particular page of content.
• code: The query parameter you can extract from intents in your destination. abcd is the value of the parameter.

Now that you understand the parts of a deep link, it’s time to create one for your app.

Understanding Intent Filters

To create a deep link to your app’s content you first have to create an intent filter. An intent filter specifies the types of intents the activity would like to receive. You define it in the manifest file.

An intent filter has the following elements:

Second, the DEFAULT category lets your app handle implicit intents. If it’s missing, the intent must specify the app component name for the activity to start.

• action: For Google Search to reach your intent, you have to specify an ACTION_VIEW action.
• data: Used to define URI format that resolves to the activity. You can have one or more in a single intent filter. The data tags have a scheme, host, path and query parameters to identify the deep link.
• category: You have to define some categories for your deep link to work. First, you specify the BROWSABLE category so your deep link can work in a browser. Without it, clicking the deep link on a browser won’t resolve to your app.

  Second, the DEFAULT category lets your app handle implicit intents. If it’s missing, the intent must specify the app component name for the activity to start.

With this understanding of intent filters, you’ll create your first deep link in the next section. :]

Creating a Deep Link

Open AndroidManifest.xml. Replace TODO Add Deep Link Intent Filter with:

<intent-filter android:label="@string/text_deep_link_title">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="www.raywenderlich.com"
    android:pathPrefix="/test" />
</intent-filter>

With this code, you define the action, category, data and pathPrefix elements for your intent filter. You also add a label to the intent filter which lets the Activity handle deep links with the URL https://www.raywenderlich.com.

Build and run. You won’t see any changes in the app but your app can handle deep links now.

Next, you’ll learn how to test your deep links.

Testing Your Deep Links

You’ll use the Android Debug Bridge, or ADB, shell commands to test the deep link flow. That is, you’ll check if the link navigates to the correct section of your app.

Open your terminal and paste in the following command:

adb shell am start -W -a android.intent.action.VIEW -d "https://www.raywenderlich.com/test?code=abcde"

This command starts the ADB shell with the VIEW action and specifies the deep link URL.

Run the command above. You’ll see the following dialog:

Once you select Claim Offer, the app opens the specific destination. It looks like this:

Great! You’ve made your first deep link. In the next section, you’ll see how you can get data from the incoming intent in your activity.

Getting Data From Incoming Intents

When you open the destination, you can now access data from the link because it’s available with the intent. You can get this data either in onCreate or onNewIntent.

First, navigate to PromoActivity.kt. Add the following method below onCreate:

private fun handleIntent(intent: Intent?) {
  val appLinkAction: String? = intent?.action
  val appLinkData: Uri? = intent?.data
  showDeepLinkOffer(appLinkAction, appLinkData)
}

In the code above, you get the appLinkAction and appLinkData from the intent. You then pass them to showDeepLinkOffer.

Now, you might see some warnings due to missing imports. At the top of the file, add:

import android.content.Intent
import android.net.Uri

Now, all the import errors are gone. But you still have an error on showDeepLinkOffer. To resolve this, add the following method below handleIntent:

private fun showDeepLinkOffer(appLinkAction: String?, appLinkData: Uri?) {
  // 1
  if (Intent.ACTION_VIEW == appLinkAction && appLinkData != null) {
    // 2
    val promotionCode = appLinkData.getQueryParameter("code")
    if (promotionCode.isNullOrBlank().not()) {
      activityPromoBinding.discountGroup.visibility = View.VISIBLE
      activityPromoBinding.tvPromoCode.text = promotionCode
      // 3
      activityPromoBinding.btnClaimOffer.setOnClickListener {
        activityPromoBinding.tvOfferClaimed.visibility = View.VISIBLE
      }
    } else {
      activityPromoBinding.discountGroup.visibility = View.GONE
    }
  }
}

Here’s a code breakdown:

1. You check if the action from the intent is ACTION_VIEW and also if the intent has data.
2. Then you check if the link has a query parameter code and set the visibility of the discount UI to visible. You also display your promotion code to a TextView.
3. Then you show a TextView with an offer claimed message when you click btnClaimOffer.

You’re one step away from claiming the discount. :] To claim your discount, add the following code to the end of onCreate:

handleIntent(intent)

Here, you call handleIntent(intent) and pass the intent from onCreate.

Build and run. The UI is still the same. Now, run the ADB command as before and select the PromoApp option.

You’ll see the following screen:

Tap CLAIM OFFER and boom! You claimed your offer as shown in the screenshot below:

You learned how to get data from incoming intents. In the next section, you’ll see how you can support other scheme types in your deep link.