> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/development-guide/android/android-deeplink/android-deeplink-delegate.md).

# Handle Links with HackleDelegate

{% hint style="info" %}
This feature is supported in Android SDK 4.4.0 and above.
{% endhint %}

When you register a `HackleDelegate`, the SDK passes links to the app instead of opening them.\
Use it when you want to handle links with your app's router or navigation logic.

## Push Links Tapped Before SDK Initialization

Add the following option to `AndroidManifest.xml` to defer handling of push click links until after the SDK is initialized.

{% hint style="warning" %}
By default, push links clicked before the SDK is initialized are not delivered to the delegate.\
To receive these links through the delegate as well, set the value to `true` and register the delegate at initialization with `delegate` in `HackleConfig`.
{% endhint %}

```xml
<meta-data
    android:name="io.hackle.android.defer_push_link_until_initialized"
    android:value="true" />
```

<table><thead><tr><th width="150">Value</th><th>Behavior</th></tr></thead><tbody><tr><td><code>false</code> (default)</td><td>The SDK opens push links clicked before initialization right away and does not pass them to the delegate.</td></tr><tr><td><code>true</code></td><td>Starts the launcher Activity, holds the link, and delivers it once after the SDK is initialized.<br>If a delegate is registered, the link goes to the delegate. Otherwise, it is handled with the default behavior.</td></tr></tbody></table>

## Implement HackleDelegate

`handleUrl` is called on the main thread when the SDK needs to open a link.\
Use `channel` to distinguish Push Message links from In-App Message links.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
import android.content.Context
import android.content.Intent
import io.hackle.android.HackleDelegate
import io.hackle.android.HackleUrlChannel
import io.hackle.android.HackleUrlContext

class AppHackleDelegate(
    private val context: Context
) : HackleDelegate {

    override fun handleUrl(context: HackleUrlContext) {
        val url = context.url
        when (context.channel) {
            HackleUrlChannel.PUSH -> {
                // The app may not be running, so start the launcher Activity and pass the link.
                val intent = Intent(this.context, MainActivity::class.java).apply {
                    data = url
                    addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
                }
                this.context.startActivity(intent)
            }
            HackleUrlChannel.IN_APP_MESSAGE -> {
                // The app is running, so handle the link with the app's router.
                AppRouter.route(url)
            }
        }
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
import android.content.Context;
import android.content.Intent;
import android.net.Uri;
import io.hackle.android.HackleDelegate;
import io.hackle.android.HackleUrlChannel;
import io.hackle.android.HackleUrlContext;

public class AppHackleDelegate implements HackleDelegate {

    private final Context appContext;

    public AppHackleDelegate(Context appContext) {
        this.appContext = appContext;
    }

    @Override
    public void handleUrl(HackleUrlContext context) {
        Uri url = context.getUrl();
        if (context.getChannel() == HackleUrlChannel.PUSH) {
            // The app may not be running, so start the launcher Activity and pass the link.
            Intent intent = new Intent(appContext, MainActivity.class);
            intent.setData(url);
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP);
            appContext.startActivity(intent);
        } else {
            // The app is running, so handle the link with the app's router.
            AppRouter.route(url);
        }
    }
}
```

{% endtab %}
{% endtabs %}

## Register a Delegate

* At initialization: register it with `delegate` in `HackleConfig`.
* After initialization: register it with `setDelegate`.
* To unregister: pass `null` to `setDelegate`.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
// Register at initialization
val config = HackleConfig.builder()
    .delegate(AppHackleDelegate(applicationContext))
    .build()

Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY, config) {
    // SDK initialization complete
}

// Register after initialization
Hackle.app.setDelegate(AppHackleDelegate(applicationContext))

// Unregister
Hackle.app.setDelegate(null)
```

{% endtab %}

{% tab title="Java" %}

```java
// Register at initialization
HackleConfig config = HackleConfig.builder()
    .delegate(new AppHackleDelegate(getApplicationContext()))
    .build();

HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY, config, () -> {
    // SDK initialization complete
});

// Register after initialization
HackleApp.getInstance().setDelegate(new AppHackleDelegate(getApplicationContext()));

// Unregister
HackleApp.getInstance().setDelegate(null);
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
If you call `Hackle.setDelegate` before the SDK is initialized, the call is ignored and only an error log is written.\
To receive links from before initialization, register the delegate with `delegate` in `HackleConfig`.
{% endhint %}

## HackleUrlContext

Properties of the `HackleUrlContext` passed to `handleUrl`.

<table><thead><tr><th width="150">Property</th><th width="220">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td><code>Uri</code></td><td>The link set in the Push Message or In-App Message.<br>http/https links are also delivered.</td></tr><tr><td><code>channel</code></td><td><code>HackleUrlChannel</code></td><td><p>Where the link came from.</p><ul><li>Push Message click: <code>PUSH</code></li><li>"Navigate to link" click action in an In-App Message: <code>IN_APP_MESSAGE</code></li></ul></td></tr></tbody></table>

## Before and After Registering a Delegate

<table><thead><tr><th width="200">Item</th><th>Without a delegate</th><th>With a delegate</th></tr></thead><tbody><tr><td>Push Message link</td><td>The SDK opens the link with an <code>ACTION_VIEW</code> Intent and starts the launcher Activity if no Activity can handle it.</td><td>The SDK calls <code>handleUrl(PUSH)</code> without opening the link or starting an Activity.</td></tr><tr><td>In-App Message link</td><td>The SDK opens the link with an <code>ACTION_VIEW</code> Intent from the current screen.</td><td>The SDK calls <code>handleUrl(IN_APP_MESSAGE)</code> without opening the link.<br>The same applies when the "Close message on click" option is used.</td></tr><tr><td>Push Message open app action</td><td>Starts the launcher Activity.</td><td>Starts the launcher Activity without going through the delegate.</td></tr><tr><td>Where the link is delivered</td><td><a href="https://docs.hackle.io/en/development-guide/android/android-deeplink/android-deeplink-os.md#handle-delivered-link">The Intent delivered to the Activity</a></td><td>The <code>HackleUrlContext</code> of <code>handleUrl</code></td></tr></tbody></table>

{% hint style="warning" %}
In apps that initialize the SDK in `Application.onCreate`, clicking a Push Message while the app is not running can call `handleUrl(PUSH)` when no Activity exists.\
In this case, the delegate must do the following.

* Bring the app to the foreground
* Prepare the screen that opens the link
* Hold the link until the screen is ready

A delegate that only navigates within an existing Activity cannot open the link in this case.\
As in the example above, start the launcher Activity with the link, then read the link in that Activity and navigate to the screen.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/en/development-guide/android/android-deeplink/android-deeplink-delegate.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
