API Linking e análise de URLs

React Native's built-in Linking module is the interface between your app and the operating system's URL handling system. It serves two purposes: outgoing — opening URLs in browsers, maps, email, phone, and other apps; and incoming — receiving URLs that were used to open your app.

For deep linking to work correctly you need to handle both the cold-start case (app launched by a URL) and the warm-start case (URL arrives while the app is already running). The Linking module provides different APIs for each scenario.

The recommended pattern handles both cold and warm starts in a single effect. Read getInitialURL() for the cold launch URL and add a listener for warm-start URLs. Both call the same handleURL function to keep routing logic in one place.

Place this effect in your root navigation component or a custom useDeepLink hook so it runs when navigation is available and is properly cleaned up when the component unmounts.

Modern React Native (with Hermes) supports the URL Web API. Construct a URL object from the deep link string to easily access protocol, hostname, pathname, and searchParams. This is far more robust than manual string splitting.

For the scheme myapp://settings/notifications?highlight=push, the hostname is settings, the pathname is /notifications, and searchParams provides the query parameters as a URLSearchParams object.

With the parsed URL parts, implement a routeDeepLink function that matches the screen name to a navigation action. Use a lookup object or switch statement to map URL screens to navigator screen names and param shapes.

Always guard against invalid or malformed URLs — if the screen is unknown, navigate to the home screen rather than throwing an error. Deep links from external sources should be treated as untrusted input.

A common bug: the deep link handler calls navigation.navigate() before the navigation container has mounted and initialized. The navigation ref may be null or the stack may not be set up yet, causing the navigate call to be silently ignored.

Use the onReady callback of NavigationContainer with a ref to detect when navigation is ready. Store pending deep link URLs and process them in onReady and after each navigation state change.

The Linking API works with both custom scheme URLs (myapp://) and HTTPS universal links (https://yoursite.com/path). For universal links the URL structure is cleaner — the hostname is your domain and the path is the content path — but they require web server configuration to work.

When testing HTTPS deep links locally, use custom scheme URLs in development and universal links in production. The same routeDeepLink function can handle both if you normalize the parsed result to a common structure.

Linking.openURL() opens any URL outside your app. Pass HTTPS URLs to open in the browser, tel: URLs to open the dialer, mailto: to open the email client, and third-party app schemes to open specific apps. It returns a Promise — always await and catch errors in case the URL is not supported.

For email links, encode the subject and body in the URL using standard mailto: formatting. On iOS the Phone app handles tel: links; on Android the default dialer handles them.

Before calling openURL, use Linking.canOpenURL() to verify the device can handle the scheme. On iOS 9+ you must whitelist external schemes in LSApplicationQueriesSchemes in Info.plist, or canOpenURL returns false even if the app is installed.

Expo managed workflow lets you add these whitelist entries via the ios.infoPlist key in app.json. Always provide a fallback (like an HTTPS URL) for when the native app is not installed.

Deep links from external sources should never be trusted blindly. A malicious link could pass arbitrary values as parameters and attempt navigation to unintended screens or inject data. Always sanitize and validate URL parameters before using them.

For IDs, verify they match expected format (UUID, integer). For screen names, use a whitelist lookup — never navigate to a screen name taken directly from the URL. Log and discard invalid URLs rather than crashing.

Marketing campaigns and notifications often need attribution — knowing which link drove which user behavior. Add UTM parameters or a custom source parameter to deep link URLs, extract them in the handler, and log them to your analytics system.

For example, myapp://product/42?source=email_campaign&campaign=summer_sale tells you the user came from an email campaign. Log this event to Amplitude, Firebase Analytics, or Mixpanel in the routeDeepLink function before navigating.

Deep links behave differently in development (Expo Go) and production builds. Always test deep linking in a production or release build installed on a real device or emulator. Expo Go has its own URL scheme (exp://) which conflicts with custom schemes.

Use TestFlight (iOS) or internal testing track (Android) for end-to-end deep link verification before releasing to the public. Document your URL scheme and all supported paths in a README for QA teams to test every route.

Test your understanding of React Native Mobile Development concepts from this lesson.

In this lesson you learned: the Linking API handles both outgoing URL opens and incoming deep link URLs via getInitialURL and addEventListener, the URL Web API parses deep link components like hostname, pathname, and searchParams cleanly, and deep link routes must be whitelisted and sanitized before navigating to prevent security issues. Next up we configure React Navigation's built-in deep linking support to automatically route URLs to screens.