Provide a way to disable default behaviour for opening deeplinks when clicked on notification

[ParthGandhi]

Is your feature request related to a problem? Please describe.
Clevertap iOS SDK by default opens up the deeplink using UiApplication.open method. This is not ideal when using Universal Links; as this opens up the deeplink in external browser. This is not ideal when you want to implement custom logic for handling deeplinks.

Describe the solution you'd like
Provide an option to opt out of this default behaviour.

Describe alternatives you've considered
Documentation suggests using custom key-value pair for handling custom deeplinking logic. But this is not ideal as this needs a migration effort for existing campaigns. Adding custom key-value pairs is also prone to errors if wrong key name is used; and make the already provided deeplink parameter useless.

Additional context
Add any other context or screenshots about the feature request here.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• Provide a way to disable default behaviour for opening deeplinks when clicked on notification #477

Related Issues

• Deeplink In App Custom HTML Not Working Since 7.2.0 #490
• Dynamic Notification Icon clevertap-android-sdk#695
• CleverTap.CleverTapPushNotificationClicked fires immediately when app is open (foreground) (without any user action) clevertap-react-native#460
• Bug: Push notification callback on iOS not always triggerd when app is in background clevertap-cordova#253

👤 Suggested Assignees

• Shreyash-Credilio
• hanifsgy
• theapache64
• Steffi3rd
• malua

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[ParthGandhi]

@coderabbitai plan

[coderabbitai]

Coding Plan

Approach

Ticket Overview

Add a configuration flag to disable the CleverTap iOS SDK's default behavior of automatically opening deeplinks using UIApplication.open, allowing developers to implement custom deeplink handling logic without modifying existing campaigns.

Codebase Summary

The CleverTap iOS SDK has a well-established configuration system centered around CleverTapInstanceConfig, which uses boolean properties with NSCoding serialization for persistence. Deeplink opening occurs through multiple code paths: push notifications flow through _handlePushNotification:openDeepLinksInForeground: in CleverTap.m, while in-app notifications, app inbox, custom templates, and push primer features call either CTUIUtils.openURL:forModule: (static utility) or CleverTap.openURL:forModule: (instance method). The SDK already provides a CleverTapURLDelegate protocol with shouldHandleCleverTapURL:forChannel: that allows optional interception of URL opening on a per-channel basis.

Observations

The CleverTap iOS SDK has a well-established configuration system centered around CleverTapInstanceConfig, which uses boolean properties with NSCoding serialization for persistence. Deeplink opening occurs through multiple code paths: push notifications flow through _handlePushNotification:openDeepLinksInForeground: in CleverTap.m, while in-app notifications, app inbox, custom templates, and push primer features call either CTUIUtils.openURL:forModule: (static utility) or CleverTap.openURL:forModule: (instance method). The SDK already provides a CleverTapURLDelegate protocol with shouldHandleCleverTapURL:forChannel: that allows optional interception of URL opening on a per-channel basis.

Assumptions

Assumption 1: Scope of the disable flag

Options Considered:

• Apply only to push notifications (the specific issue mentioned in the ticket)
• Apply globally to all SDK deeplink opening (push notifications, in-app notifications, inbox, custom templates, push primer)

Chosen Option: Apply globally to all SDK deeplink opening

Rationale: The ticket mentions universal links opening in an external browser as the problem, which affects all channels, not just push notifications. A global flag provides consistent behavior and aligns with how developers typically want to handle deeplinks uniformly across all entry points. The naming convention disableAutomaticDeeplinkOpening (without channel-specific qualification) further supports global applicability.

Assumption 2: Relationship with existing CleverTapURLDelegate pattern

Options Considered:

• Replace the delegate pattern with the configuration flag
• Have the configuration flag completely override delegate behavior
• Have configuration flag and delegate work together (delegate checked first if present, then config flag)

Chosen Option: Have configuration flag and delegate work together (delegate checked first if present, then config flag)

Rationale: This preserves backward compatibility for existing apps using the delegate pattern while providing a simpler path for new integrations. When the flag is enabled (automatic opening disabled), the SDK still invokes delegate methods so apps receive notification data, but the SDK skips the default UIApplication.open call. This allows developers to use delegates for custom handling while the flag prevents the unwanted default behavior.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Configuration Infrastructure

Add the new configuration property to CleverTapInstanceConfig and ensure it's properly initialized, serialized, and accessible throughout the SDK.

Task 1: Add Configuration Property

Define the new boolean flag in the configuration interface and implementation.

• Add @property (nonatomic, assign) BOOL disableAutomaticDeeplinkOpening; to CleverTapInstanceConfig.h following the existing boolean property pattern (placed after other boolean flags like disableAppLaunchedEvent and enablePersonalization)
• Initialize the property to NO (default behavior preserves automatic opening) in CleverTapInstanceConfig.m's init methods and setupPlistData method with pattern _disableAutomaticDeeplinkOpening = isDefault ? plist.disableAutomaticDeeplinkOpening : NO;
• Add NSCoding serialization in encodeWithCoder: using [coder encodeBool:_disableAutomaticDeeplinkOpening forKey:@"disableAutomaticDeeplinkOpening"];
• Add NSCoding deserialization in initWithCoder: using _disableAutomaticDeeplinkOpening = [coder decodeBoolForKey:@"disableAutomaticDeeplinkOpening"];
• Add setter method following the instance-type guard pattern: check if (!_isDefaultInstance) before allowing modifications to ensure default instance config can only be set during initialization

Task 2: Add Plist Support

Enable plist-based configuration for the new flag.

• Add disableAutomaticDeeplinkOpening property to CTPreferences.h plist property declarations if needed for plist initialization support
• Follow existing pattern where configuration values can be set via Info.plist under the CleverTap configuration dictionary

🤖 Prompt for AI agents

This phase adds configuration infrastructure for the
disableAutomaticDeeplinkOpening flag to CleverTapInstanceConfig, enabling
developers to disable automatic deeplink opening across the SDK.

In CleverTapInstanceConfig.h:
- Add boolean property `disableAutomaticDeeplinkOpening` following existing
boolean property patterns

In CleverTapInstanceConfig.m:
- Initialize property to NO in init methods and setupPlistData
- Add NSCoding serialization in encodeWithCoder
- Add NSCoding deserialization in initWithCoder
- Implement setter with instance-type guard pattern

In CTPreferences.h:
- Add disableAutomaticDeeplinkOpening property declaration for plist support

Phase 2: Push Notification Deeplink Handling

Update the push notification flow to check the configuration flag before automatically opening deeplinks.

Update Push Notification Handling Logic

Modify the main push notification processing method to respect the configuration flag.

• In CleverTap.m's _handlePushNotification:openDeepLinksInForeground: method (around line 1359 where foreground checking occurs), add a configuration check before calling _checkAndFireDeepLinkForNotification:
• Add condition: if self.config.disableAutomaticDeeplinkOpening is YES, skip the deeplink opening logic but still invoke CleverTapPushNotificationDelegate.pushNotificationTappedWithCustomExtras: callback so apps receive notification data
• Ensure the URL delegate check (shouldHandleCleverTapURL:forChannel:CleverTapPushNotification) still executes first and takes precedence - if delegate returns YES (app is handling), skip SDK opening regardless of config flag
• Log a debug message when automatic opening is skipped due to the configuration flag to aid developers during implementation

🤖 Prompt for AI agents

This phase updates push notification deeplink handling to respect the
disableAutomaticDeeplinkOpening configuration flag.

In CleverTap.m:
- Locate _handlePushNotification:openDeepLinksInForeground: method
- Add configuration check before calling _checkAndFireDeepLinkForNotification:
- When flag is enabled, skip deeplink opening but still invoke
CleverTapPushNotificationDelegate.pushNotificationTappedWithCustomExtras:
- Ensure URL delegate check executes first and takes precedence
- Add debug logging when automatic opening is skipped

Phase 3: In-App Notification Deeplink Handling

Update in-app notification button actions to check the configuration flag before opening deeplinks.

Update In-App Display Manager

Modify the in-app notification CTA handling to respect the configuration flag.

• In CTInAppDisplayManager.m around lines 796-805 where CTUIUtils.openURL:forModule:@"InApp" is called, add a check for self.instance.config.disableAutomaticDeeplinkOpening
• The instance method in CTInAppDisplayManager has access to the CleverTap instance via self.instance, which provides access to config
• Before calling CTUIUtils.openURL:forModule:, check if automatic opening is disabled; if YES, skip the call but still invoke the URL delegate callback with CleverTapInAppNotification channel
• Maintain the existing pattern where URL delegate is checked first - if delegate returns YES, SDK respects that regardless of config flag
• Add debug logging when automatic opening is skipped

🤖 Prompt for AI agents

This phase updates in-app notification deeplink handling to respect the
disableAutomaticDeeplinkOpening configuration flag.

In CTInAppDisplayManager.m:
- Locate CTUIUtils.openURL:forModule:@"InApp" call
- Add check for self.instance.config.disableAutomaticDeeplinkOpening
- When flag is enabled, skip CTUIUtils.openURL call but still invoke URL
delegate callback with CleverTapInAppNotification channel
- Ensure URL delegate check executes first and takes precedence
- Add debug logging when automatic opening is skipped

Phase 4: App Inbox Deeplink Handling

Update app inbox message actions to check the configuration flag before opening deeplinks.

Task 1: Update Inbox URL Opening

Modify the inbox message CTA handling in the main CleverTap instance.

• In CleverTap.m around line 4004 where [self openURL:ctaURL forModule:@"Inbox message"] is called, add configuration flag check
• Before calling the instance openURL:forModule: method, check self.config.disableAutomaticDeeplinkOpening
• If disabled, skip the call but ensure URL delegate is invoked with CleverTapAppInbox channel so apps can implement custom handling
• Add debug logging for developer visibility

Task 2: Update Instance openURL Method

Add configuration check in the instance-level URL opening method.

• In CleverTap.m's instance method openURL:forModule: (lines 1629-1659), add early-return check for self.config.disableAutomaticDeeplinkOpening at the beginning of the method
• If flag is YES, log debug message and return without calling the UIApplication.open invocation
• This provides a centralized guard for any inbox-related or other calls that use the instance method path

🤖 Prompt for AI agents

This phase updates app inbox deeplink handling to respect the
disableAutomaticDeeplinkOpening configuration flag.

In CleverTap.m:
- Locate inbox message CTA handling where openURL:forModule:@"Inbox message" is
called
- Add configuration check before calling openURL:forModule:
- When flag is enabled, skip the call but invoke URL delegate with
CleverTapAppInbox channel
- Add debug logging

In CleverTap.m openURL:forModule: instance method:
- Add early-return check for self.config.disableAutomaticDeeplinkOpening at
method start
- When flag is enabled, log debug message and return without calling
UIApplication.open
- This provides centralized guard for inbox and other calls using instance
method path

Phase 5: Custom Template and Push Primer Deeplink Handling

Update remaining SDK features that automatically open deeplinks to respect the configuration flag.

Task 1: Update System Template Action Handler

Modify custom template URL handling to check the configuration flag.

• In CTSystemTemplateActionHandler.m around line 53 where CTUIUtils.openURL:forModule:@"OpenUrl System Template" is called, refactor to check configuration
• System template handler is a static utility that doesn't have direct config access, so pass the configuration decision from the calling context in CTInAppDisplayManager or create a method that accepts a shouldOpen parameter
• Alternative: Since system templates are invoked through in-app display manager context, ensure the check in CTInAppDisplayManager (Task 3.1) covers this code path by examining the call hierarchy

Task 2: Update Push Primer Manager

Modify push primer deeplink handling to respect the configuration flag.

• In CTPushPrimerManager.m around line 163 where CTUIUtils.openURL:forModule:@"PushPermission" is called, add configuration check
• CTPushPrimerManager likely has access to the CleverTap instance via a property or initialization parameter; use this to access config.disableAutomaticDeeplinkOpening
• If configuration flag is enabled (automatic opening disabled), skip the URL opening call
• Add debug logging to indicate automatic opening was skipped for push primer actions

🤖 Prompt for AI agents

This phase updates custom template and push primer deeplink handling to respect
the disableAutomaticDeeplinkOpening configuration flag.

In CTSystemTemplateActionHandler.m:
- Locate CTUIUtils.openURL:forModule:@"OpenUrl System Template" call
- Pass configuration decision from calling context in CTInAppDisplayManager or
add shouldOpen parameter
- Alternatively, verify that CTInAppDisplayManager check from Phase 3 covers
this code path

In CTPushPrimerManager.m:
- Locate CTUIUtils.openURL:forModule:@"PushPermission" call
- Add configuration check using config.disableAutomaticDeeplinkOpening
- When flag is enabled, skip URL opening call
- Add debug logging when automatic opening is skipped

Phase 6: Documentation and Developer Guidance

Ensure developers understand how to use the new flag with the existing delegate patterns for custom deeplink handling.

Task 1: Update Header Documentation

Add inline documentation for the new configuration property.

• In CleverTapInstanceConfig.h, add comprehensive documentation comment above the disableAutomaticDeeplinkOpening property explaining:
  • When set to YES, the SDK will not automatically call UIApplication.open for deeplinks from push notifications, in-app notifications, inbox, and other SDK features
  • Apps should implement CleverTapURLDelegate's shouldHandleCleverTapURL:forChannel: method to receive URLs and handle deeplink navigation with custom logic
  • Apps should implement CleverTapPushNotificationDelegate's pushNotificationTappedWithCustomExtras: to receive push notification data
  • This is useful when using Universal Links that require custom handling to prevent opening in external browser
  • Default value is NO (automatic opening enabled for backward compatibility)

Task 2: Add Usage Example Comments

Provide code example patterns in documentation.

• Add example code snippet in header comments showing:
  • How to set the flag: config.disableAutomaticDeeplinkOpening = YES;
  • How to implement CleverTapURLDelegate to receive URLs for custom handling
  • How URLs can be passed to app's own navigation/routing logic instead of UIApplication.open
  • Note that delegate methods are still called even when automatic opening is disabled, allowing apps to retrieve notification metadata

🤖 Prompt for AI agents

This phase adds comprehensive documentation for the
disableAutomaticDeeplinkOpening configuration flag to help developers understand
and use the feature.

In CleverTapInstanceConfig.h:
- Add documentation comment above disableAutomaticDeeplinkOpening property
- Explain that when set to YES, SDK won't automatically call UIApplication.open
- Document that apps should implement CleverTapURLDelegate and
CleverTapPushNotificationDelegate for custom handling
- Note usefulness for Universal Links requiring custom handling
- Specify default value is NO for backward compatibility
- Add code example showing how to set the flag and implement delegate methods
- Show how to pass URLs to custom navigation/routing logic

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase adds configuration infrastructure for the
disableAutomaticDeeplinkOpening flag to CleverTapInstanceConfig, enabling
developers to disable automatic deeplink opening across the SDK.

In CleverTapInstanceConfig.h:
- Add boolean property `disableAutomaticDeeplinkOpening` following existing
boolean property patterns

In CleverTapInstanceConfig.m:
- Initialize property to NO in init methods and setupPlistData
- Add NSCoding serialization in encodeWithCoder
- Add NSCoding deserialization in initWithCoder
- Implement setter with instance-type guard pattern

In CTPreferences.h:
- Add disableAutomaticDeeplinkOpening property declaration for plist support
===============================================================================

Task: 2

This phase updates push notification deeplink handling to respect the
disableAutomaticDeeplinkOpening configuration flag.

In CleverTap.m:
- Locate _handlePushNotification:openDeepLinksInForeground: method
- Add configuration check before calling _checkAndFireDeepLinkForNotification:
- When flag is enabled, skip deeplink opening but still invoke
CleverTapPushNotificationDelegate.pushNotificationTappedWithCustomExtras:
- Ensure URL delegate check executes first and takes precedence
- Add debug logging when automatic opening is skipped
===============================================================================

Task: 3

This phase updates in-app notification deeplink handling to respect the
disableAutomaticDeeplinkOpening configuration flag.

In CTInAppDisplayManager.m:
- Locate CTUIUtils.openURL:forModule:@"InApp" call
- Add check for self.instance.config.disableAutomaticDeeplinkOpening
- When flag is enabled, skip CTUIUtils.openURL call but still invoke URL
delegate callback with CleverTapInAppNotification channel
- Ensure URL delegate check executes first and takes precedence
- Add debug logging when automatic opening is skipped
===============================================================================

Task: 4

This phase updates app inbox deeplink handling to respect the
disableAutomaticDeeplinkOpening configuration flag.

In CleverTap.m:
- Locate inbox message CTA handling where openURL:forModule:@"Inbox message" is
called
- Add configuration check before calling openURL:forModule:
- When flag is enabled, skip the call but invoke URL delegate with
CleverTapAppInbox channel
- Add debug logging

In CleverTap.m openURL:forModule: instance method:
- Add early-return check for self.config.disableAutomaticDeeplinkOpening at
method start
- When flag is enabled, log debug message and return without calling
UIApplication.open
- This provides centralized guard for inbox and other calls using instance
method path
===============================================================================

Task: 5

This phase updates custom template and push primer deeplink handling to respect
the disableAutomaticDeeplinkOpening configuration flag.

In CTSystemTemplateActionHandler.m:
- Locate CTUIUtils.openURL:forModule:@"OpenUrl System Template" call
- Pass configuration decision from calling context in CTInAppDisplayManager or
add shouldOpen parameter
- Alternatively, verify that CTInAppDisplayManager check from Phase 3 covers
this code path

In CTPushPrimerManager.m:
- Locate CTUIUtils.openURL:forModule:@"PushPermission" call
- Add configuration check using config.disableAutomaticDeeplinkOpening
- When flag is enabled, skip URL opening call
- Add debug logging when automatic opening is skipped
===============================================================================

Task: 6

This phase adds comprehensive documentation for the
disableAutomaticDeeplinkOpening configuration flag to help developers understand
and use the feature.

In CleverTapInstanceConfig.h:
- Add documentation comment above disableAutomaticDeeplinkOpening property
- Explain that when set to YES, SDK won't automatically call UIApplication.open
- Document that apps should implement CleverTapURLDelegate and
CleverTapPushNotificationDelegate for custom handling
- Note usefulness for Universal Links requiring custom handling
- Specify default value is NO for backward compatibility
- Add code example showing how to set the flag and implement delegate methods
- Show how to pass URLs to custom navigation/routing logic

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[nishant-clevertap]

Hi @ParthGandhi
You can use this delegate method and add your custom logic:

clevertap-ios-sdk/CleverTapSDK/CleverTapURLDelegate.h

Line 23 in f8ace23

- (BOOL)shouldHandleCleverTapURL:(NSURL *_Nullable )url forChannel:(CleverTapChannel)channel;