DeepLinkDispatch

Configurable path segment placeholders (e.g., <some_id>) allow you to change URL path elements at runtime without changing the library code. This is useful for libraries used across multiple apps with different URI structures.

Usage:

1. Define the placeholder in the URI: foo://cereal.com/<type_of_cereal>/nutritional_info.
2. Provide a mapping in the DeepLinkDelegate constructor using a Map.

Important:

• You must provide a mapping for every placeholder used, or the app will crash at runtime.
• To match an empty segment (effectively removing it), map the placeholder to an empty string "". Note that an empty placeholder cannot be the last element in the URL.

@DeepLink("foo://cereal.com/<type_of_cereal>/nutritional_info")
public static Intent intentForNutritionalDeepLinkMethod(Context context) {
  return new Intent(context, MainActivity.class)
      .setAction(ACTION_DEEP_LINK_METHOD);
}

// At runtime:
Map configurablePlaceholdersMap = new HashMap();
configurablePlaceholdersMap.put("type_of_cereal", "/obamaos");

DeepLinkDelegate deepLinkDelegate = 
    new DeepLinkDelegate(new AppDeepLinkModuleRegistry(), new LibraryDeepLinkModuleRegistry(), configurablePlaceholdersMap);

DeepLinkDispatch can automatically generate intent-filter entries in your AndroidManifest.xml using ksp.

Requirements:

1. Must use ksp.
2. Deep links must be in a module that is not an application module (i.e., not using com.android.application).
3. You must specify activityClassFqn in the @DeepLink or @DeepLinkSpec annotation to reference the target Activity.

Setup:

1. Add the gradle plugin to your root build.gradle:

buildscript {
    dependencies {
        classpath "com.airbnb:deeplinkdispatch-gradle-plugin:$VERSION"
    }
}

2. Apply the plugin in your module's build.gradle (must be applied after Kotlin and Android plugins):

apply plugin: 'com.airbnb.deeplinkdispatch.manifest-generation'

@DeepLink("http{scheme(|s)}://example.{domain(com|de|ro)}/deepLink/{id}", "{scheme(foo|bar)}://{host(example|another-example)}.{domain(com|de|ro)}/anotherDeepLink", activityClassFqn = "com.example.MainActivity")
class MainActivity : Activity {
  @Override fun onCreate(savedInstanceState: Bundle) {
    super.onCreate(savedInstanceState)
    val intent : Intent = getIntent()
    if (intent.getBooleanExtra(DeepLink.IS_DEEP_LINK, false)) {
      val parameters : Bundle = intent.getExtras()
      val idString : String = parameters.getString("id")
      // Do something with idString
    }
  }
}

You can test deep link dispatching using the Android Debug Bridge (adb). It is recommended to run adb shell first and then execute the am start command from within the shell to ensure URIs are parsed correctly.

Standard Deep Link

To fire a standard deep link (e.g., annotated with @DeepLink("dld://example.com/deepLink")): am start -W -a android.intent.action.VIEW -d "dld://example.com/deepLink" <YOUR_PACKAGE_NAME>

Deep Link with Path Parameters

To fire a deep link associated with a method that includes path parameters (e.g., annotated with @DeepLink("dld://methodDeepLink/{param1}")): am start -W -a android.intent.action.VIEW -d "dld://methodDeepLink/abc123" <YOUR_PACKAGE_NAME>

Deep Link with Multiple Path Parameters

To fire a deep link with multiple path segments (e.g., annotated with @DeepLink("http://example.com/deepLink/{id}/{name}")): am start -W -a android.intent.action.VIEW -d "http://example.com/deepLink/123abc/myname" <YOUR_PACKAGE_NAME>

You can register a BroadcastReceiver to listen for incoming deep links. DeepLinkDispatch uses LocalBroadcastManager to broadcast an Intent with the following extras:

• DeepLinkHandler.EXTRA_URI: The URI of the deep link.
• DeepLinkHandler.EXTRA_SUCCESSFUL: Whether the deep link was fired successfully.
• DeepLinkHandler.EXTRA_ERROR_MESSAGE: The error message if the dispatch failed.

public class DeepLinkReceiver extends BroadcastReceiver {
  @Override public void onReceive(Context context, Intent intent) {
    String deepLinkUri = intent.getStringExtra(DeepLinkHandler.EXTRA_URI);
    if (intent.getBooleanExtra(DeepLinkHandler.EXTRA_SUCCESSFUL, false)) {
      Log.i("TAG", "Success deep linking: " + deepLinkUri);
    } else {
      String errorMessage = intent.getStringExtra(DeepLinkHandler.EXTRA_ERROR_MESSAGE);
      Log.e("TAG", "Error deep linking: " + deepLinkUri + " with error message " + errorMessage);
    }
  }
}

// Register in Application class:
LocalBroadcastManager.getInstance(this).registerReceiver(new DeepLinkReceiver(), new IntentFilter(DeepLinkHandler.ACTION));