--- id: linking title: Linking --- `Linking` gives you a general interface to interact with both incoming and outgoing app links. ### Basic Usage #### Handling deep links If your app was launched from an external url registered to your app you can access and handle it from any component you want with ``` componentDidMount() { Linking.getInitialURL().then((url) => { if (url) { console.log('Initial url is: ' + url); } }).catch(err => console.error('An error occurred', err)); } ``` NOTE: For instructions on how to add support for deep linking on Android, refer to [Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links](http://developer.android.com/training/app-indexing/deep-linking.html#adding-filters). If you wish to receive the intent in an existing instance of MainActivity, you may set the `launchMode` of MainActivity to `singleTask` in `AndroidManifest.xml`. See [``](http://developer.android.com/guide/topics/manifest/activity-element.html) documentation for more information. ``` ``` NOTE: On iOS, you'll need to link `RCTLinking` to your project by following the steps described [here](docs/linking-libraries-ios.html#manual-linking). If you also want to listen to incoming app links during your app's execution, you'll need to add the following lines to your `*AppDelegate.m`: ``` // iOS 9.x or newer #import - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary *)options { return [RCTLinkingManager application:application openURL:url options:options]; } ``` If you're targeting iOS 8.x or older, you can use the following code instead: ``` // iOS 8.x or older #import - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { return [RCTLinkingManager application:application openURL:url sourceApplication:sourceApplication annotation:annotation]; } ``` // If your app is using [Universal Links](https://developer.apple.com/library/prerelease/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html), you'll need to add the following code as well: ``` - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler { return [RCTLinkingManager application:application continueUserActivity:userActivity restorationHandler:restorationHandler]; } ``` And then on your React component you'll be able to listen to the events on `Linking` as follows ``` componentDidMount() { Linking.addEventListener('url', this._handleOpenURL); }, componentWillUnmount() { Linking.removeEventListener('url', this._handleOpenURL); }, _handleOpenURL(event) { console.log(event.url); } ``` #### Opening external links To start the corresponding activity for a link (web URL, email, contact etc.), call ``` Linking.openURL(url).catch(err => console.error('An error occurred', err)); ``` If you want to check if any installed app can handle a given URL beforehand you can call ``` Linking.canOpenURL(url).then(supported => { if (!supported) { console.log('Can\'t handle url: ' + url); } else { return Linking.openURL(url); } }).catch(err => console.error('An error occurred', err)); ``` ### Methods - [`constructor`](docs/linking.html#constructor) - [`addEventListener`](docs/linking.html#addeventlistener) - [`removeEventListener`](docs/linking.html#removeeventlistener) - [`openURL`](docs/linking.html#openurl) - [`canOpenURL`](docs/linking.html#canopenurl) - [`getInitialURL`](docs/linking.html#getinitialurl) --- # Reference ## Methods ### `constructor()` ```javascript constructor() ``` --- ### `addEventListener()` ```javascript addEventListener(type, handler) ``` Add a handler to Linking changes by listening to the `url` event type and providing the handler --- ### `removeEventListener()` ```javascript removeEventListener(type, handler) ``` Remove a handler by passing the `url` event type and the handler --- ### `openURL()` ```javascript openURL(url) ``` Try to open the given `url` with any of the installed apps. You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps. The method returns a `Promise` object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected. > This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first. > For web URLs, the protocol ("http://", "https://") must be set accordingly! --- ### `canOpenURL()` ```javascript canOpenURL(url) ``` Determine whether or not an installed app can handle a given URL. > For web URLs, the protocol ("http://", "https://") must be set accordingly! > As of iOS 9, your app needs to provide the `LSApplicationQueriesSchemes` key inside `Info.plist` or canOpenURL will always return false. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | | url | string | Yes | The URL to open | --- ### `getInitialURL()` ```javascript getInitialURL() ``` If the app launch was triggered by an app link, it will give the link url, otherwise it will give `null` > To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents