Deep Linking & Deferred Deep Linking (DDL) Troubleshooting Guide - FAQ

Likely causes:

• The deep link handler isn't fully implemented in the app
• The app isn't reading the resolved deep link from the Singular SDK
• DDL prerequisites aren't fully met

What to check:

1. Test the deep link directly (without going through the Singular link).
2. Confirm your SingularLinkHandler is implemented and correctly reading:
   • getDeeplink()
   • isDeferred()
   • getPassthrough()
3. Verify DDL is enabled (should_index_ddl = true).

If the deep link works when tested directly but not through the Singular link, the issue is almost always in your app's navigation logic — not the link itself.

On iOS (Universal Links): This usually means the Universal Link configuration is incomplete. Check:

• Team ID and iOS App Scheme are correctly set in Singular
• Associated Domains are added in Xcode
• The AASA file exists and includes the correct link ID

Tip for dev/QA builds: If you're testing on a dev or QA build, your device may not have the latest AASA file yet. Try reinstalling the app after rebooting the device.

On Android: This usually points to misconfigured intent filters. Check:

• The App Links SHA256 fingerprint is set correctly (if using App Links)
• assetlinks.json is accessible under your Singular domain
• Intent filters match what's configured on the Singular Apps page

If everything above checks out and the issue continues, the problem is most likely in your deep link handler logic.

Typical error: "Safari cannot open the page because the address is invalid."

Why this happens:

• Safari has known limitations in handling certain Universal Links for new users
• _force_redirect=1 is present in the link

This is expected behavior, and the flow should continue as follows: the user sees the error → taps OK → is prompted to open the App Store.

Likely cause: The passthrough parameter (_p) isn't properly appended or URL-encoded.

Best practices:

• Always URL-encode JSON values before adding them to the link
• Read passthrough data from singularLinkParams.passthrough

Passthrough data is available for both deep links and deferred deep links, so if it's missing, the issue is almost always in encoding or retrieval.

Why this happens: Once a Singular link is created with a deep link, it will always try to open the app if it's installed. This is controlled at the OS level:

• iOS: governed by the AASA file
• Android: governed by SHA256 certificate association

There's no way to override this after the fact. If you want a link that always sends users to the store, it needs to be created without a deep link from the beginning.

Root cause: Apple's iCloud Private Relay is enabled on the device.

Why it breaks DDL: Private Relay changes the IP address between the click and the install, so the click IP and install IP don't match — which breaks probabilistic attribution.

Recommendation:

• Disable iCloud Private Relay while testing
• Test using Chrome or another non-Safari browser instead

Why this happens: The link is configured with a deep link, which always takes priority over a landing page when the app is installed.

Key rule: App + Deep Link will always win over a landing page. A social landing page will only appear if the app genuinely cannot be opened.

Likely cause: The tracking link you are using for testing is double URL-encoded, making it unresolvable by the device or Singular.

Why this happens: When a Singular Link containing deep link parameters (such as _dl or _p) is copied from certain environments (e.g., Slack, email clients, or messaging tools), the URL may be encoded a second time. For example:

• Correct (single-encoded): https://yourapp.sng.link/Xxxxx/yyyy?_dl=myapp%3A%2F%2Fstory&_p=%7B%22story_id%22%3A%22BananaStory%22%7D
• Invalid (double-encoded): https%3A%2F%2Fyourapp.sng.link%2FXxxxx%2Fyyyy%3F_dl%3Dmyapp%3A%2F%2Fstory%26_p%3D%7B%22story_id%22%3A%22BananaStory%22%7D

A double-encoded link will not redirect properly, and the resulting install or click may not appear in Singular's attribution logs.

What to check:

1. Always copy tracking links directly from the Singular Manage Links page — not from a Slack message or another tool that may have re-encoded the URL.
2. Verify that the link starts with https:// (not https%3A%2F%2F). If you see percent-encoded characters at the very start of the URL, the entire link has been double-encoded.
3. Use a URL decoder tool (e.g., urldecoder.org) to check if the link decodes to a valid Singular Link format.
4. Decode the link once and use the resulting URL for testing.

Issue: Users clicking a Singular link from the Samsung Internet browser may get redirected to the Google Play Store — even when the app is already installed and the link is configured correctly.

What we've observed:

• Google Chrome: the link opens the app as expected
• Samsung Internet: the same link redirects to the Play Store instead

This can happen whether the link is opened directly in Samsung Internet or embedded in a web page and clicked from there.

Root cause: Samsung Internet has a built-in privacy setting that blocks apps from being opened externally by default.

• When enabled: the browser blocks the deep link and falls back to the Play Store
• When disabled: the link opens the app correctly, matching Chrome's behavior

We've confirmed this is a browser setting issue, not a Singular configuration issue — Android App Links and SHA-256 fingerprints are correctly set up, and link behavior is consistent everywhere once this setting is turned off.

What this means for you: Some Samsung users may land on the Play Store even with the app installed, depending on their individual browser privacy settings. This can't be controlled programmatically on our end.

If you want to guide affected users: You can let them know that Samsung Internet may block app-opening links by default, and that enabling "Open external apps" (or similar) under Samsung Internet's Privacy settings will restore the expected in-app experience.

Why this happens: When users click a Singular Link from inside certain social media in-app browsers, the browser may block standard iOS Universal Links or Android App Links. As a result, the app may open successfully but the deep link is not passed to the app, causing users to land on the default home screen instead of the intended destination.

To address this, Singular provides the Social Landing Page, an intermediary landing page that helps preserve the deep link and reliably route users to the correct in-app destination.

Which platforms are supported?

The Social Landing Page supports:

• iOS
• Android (Facebook, Facebook Messenger, Facebook Messenger Lite, and Instagram in-app browsers)
• Partner Links, including:
  • Facebook Web
  • TikTok Ads Web
  • X (Twitter) Web
  • Snapchat Web

How do I enable the Social Landing Page?

When creating or editing a Singular Link, enable Landing Page under Social Link Settings.

This option is available for:

• Custom Source links
• Mobile Web-to-App links
• Partner links

When should I use the Social Landing Page?

Enable the Social Landing Page whenever you're running web-to-app campaigns through supported social platforms. It helps ensure users are directed to the intended in-app content rather than the app's home screen, improving the deep linking experience and reducing failed deep links caused by social media in-app browsers.