> 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/ios/ios-deeplink/ios-deeplink-delegate.md).

# Handle Links with HackleDelegate

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

When you register a `HackleDelegate`, the SDK passes links to the app without opening them.\
You can handle links according to your app's flow, such as navigating only after checking whether the user is logged in.

## Push Links Tapped Before SDK Initialization

Add the option below to `Info.plist` to defer push click link handling until after SDK initialization.

{% hint style="warning" %}
By default, push links tapped before SDK initialization are not delivered to the delegate.\
To receive these links in the delegate as well, set the value to boolean `YES` and register the delegate at initialization with `delegate` of `HackleConfigBuilder`.
{% endhint %}

```xml
<key>HackleDeferPushLinkUntilInitialized</key>
<true/>
```

<table><thead><tr><th width="220">Value</th><th>Behavior</th></tr></thead><tbody><tr><td>Key absent or <code>NO</code> (default)</td><td>The SDK opens push links tapped before SDK initialization right away and does not deliver them to the delegate.</td></tr><tr><td><code>YES</code></td><td>The link is held and delivered once after SDK initialization.<br>If a delegate is registered, the link goes to the delegate. Otherwise, the default behavior applies.</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="Swift" %}

```swift
import Hackle

class AppRouter: HackleDelegate {

    @MainActor
    func handleURL(_ context: HackleURLContext) {
        switch context.channel {
        case .push:
            print("push link: \(context.url)")
        case .inAppMessage:
            print("in-app message link: \(context.url)")
        }
        // Handle context.url with your app's router.
    }
}
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
@import Hackle;

@interface AppRouter : NSObject <HackleDelegate>
@end

@implementation AppRouter

- (void)handleURL:(HackleURLContext *)context {
    switch (context.channel) {
        case HackleURLChannelPush:
            NSLog(@"push link: %@", context.url);
            break;
        case HackleURLChannelInAppMessage:
            NSLog(@"in-app message link: %@", context.url);
            break;
    }
    // Handle context.url with your app's router.
}

@end
```

{% endtab %}
{% endtabs %}

## Register a Delegate

* At initialization: Register with `delegate` of `HackleConfigBuilder`.
* After initialization: Register with `Hackle.setDelegate`.
* Unregister: Pass `nil` to `Hackle.setDelegate`.

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

```swift
// Register at initialization
let config = HackleConfigBuilder()
    .delegate(AppRouter())
    .build()

Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY, config: config) {
    // SDK ready to use.
}

// Register after initialization
Hackle.setDelegate(AppRouter())

// Unregister
Hackle.setDelegate(nil)
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
// Register at initialization
HackleConfigBuilder *builder = [[HackleConfigBuilder alloc] init];
[builder delegate:[[AppRouter alloc] init]];
HackleConfig *config = [builder build];

[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:config completion:^{
    // SDK ready to use.
}];

// Register after initialization
[Hackle setDelegate:[[AppRouter alloc] init]];

// Unregister
[Hackle setDelegate:nil];
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Calling `Hackle.setDelegate` before SDK initialization is ignored.\
To receive links from before initialization, register with `delegate` of `HackleConfigBuilder`.
{% endhint %}

## HackleURLContext

Properties of the `HackleURLContext` passed to `handleURL`.

<table><thead><tr><th width="160">Property</th><th width="220">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td><code>URL</code></td><td>The link set in the Push Message or In-App Message</td></tr><tr><td><code>channel</code></td><td><code>HackleURLChannel</code></td><td><p>The channel through which the link was delivered.</p><ul><li>Push Message: <code>.push</code> (ObjC: <code>HackleURLChannelPush</code>)</li><li>In-App Message: <code>.inAppMessage</code> (ObjC: <code>HackleURLChannelInAppMessage</code>)</li></ul></td></tr></tbody></table>

## Before and After Registering a Delegate

<table><thead><tr><th width="160">Category</th><th>Without delegate</th><th>With delegate</th></tr></thead><tbody><tr><td>Handles links</td><td>SDK</td><td>App</td></tr><tr><td>Deep Link</td><td>SDK opens it with <code>UIApplication.open</code></td><td>Delivered to <code>handleURL</code></td></tr><tr><td>http/https links</td><td>Delivered as a Universal Link if it matches Associated Domains. Otherwise, opened with <code>UIApplication.open</code></td><td>Delivered to <code>handleURL</code></td></tr><tr><td>Where the link is delivered</td><td><a href="https://docs.hackle.io/en/development-guide/ios/ios-deeplink/ios-deeplink-os.md#handle-delivered-link">Methods through which the OS delivers links to the app</a></td><td><code>handleURL</code></td></tr></tbody></table>


---

# 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/ios/ios-deeplink/ios-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.
