react-native/website/versioned_docs/version-0.48/autogen_Linking.md

---
id: version-0.48-linking
title: Linking
category: APIs
permalink: docs/linking.html
original_id: linking
---
<div><div><span><div class="banner-crna-ejected">
  <h3>Projects with Native Code Only</h3>
  <p>
    This section only applies to projects made with <code>react-native init</code>
    or to those made with Create React Native App which have since ejected. For
    more information about ejecting, please see
    the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
    the Create React Native App repository.
  </p>
</div>

</span><p><code>Linking</code> gives you a general interface to interact with both incoming
and outgoing app links.</p><h3><a class="anchor" name="basic-usage"></a>Basic Usage <a class="hash-link" href="docs/linking.html#basic-usage">#</a></h3><h4><a class="anchor" name="handling-deep-links"></a>Handling deep links <a class="hash-link" href="docs/linking.html#handling-deep-links">#</a></h4><p>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</p><div class="prism language-javascript"><span class="token function">componentDidMount</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  Linking<span class="token punctuation">.</span><span class="token function">getInitialURL</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token punctuation">(</span>url<span class="token punctuation">)</span> <span class="token operator">=&gt;</span> <span class="token punctuation">{</span>
    <span class="token keyword">if</span> <span class="token punctuation">(</span>url<span class="token punctuation">)</span> <span class="token punctuation">{</span>
      console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Initial url is: '</span> <span class="token operator">+</span> url<span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token keyword">catch</span><span class="token punctuation">(</span>err <span class="token operator">=&gt;</span> console<span class="token punctuation">.</span><span class="token function">error</span><span class="token punctuation">(</span><span class="token string">'An error occurred'</span><span class="token punctuation">,</span> err<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>NOTE: For instructions on how to add support for deep linking on Android,
refer to <a href="http://developer.android.com/training/app-indexing/deep-linking.html#adding-filters" target="_blank">Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links</a>.</p><p>If you wish to receive the intent in an existing instance of MainActivity,
you may set the <code>launchMode</code> of MainActivity to <code>singleTask</code> in
<code>AndroidManifest.xml</code>. See <a href="http://developer.android.com/guide/topics/manifest/activity-element.html" target="_blank"><code>&lt;activity&gt;</code></a>
documentation for more information.</p><div class="prism language-javascript"><span class="token operator">&lt;</span>activity
  android<span class="token punctuation">:</span>name<span class="token operator">=</span><span class="token string">".MainActivity"</span>
  android<span class="token punctuation">:</span>launchMode<span class="token operator">=</span><span class="token string">"singleTask"</span><span class="token operator">&gt;</span></div><p>NOTE: On iOS, you'll need to link <code>RCTLinking</code> to your project by following
the steps described <a href="docs/linking-libraries-ios.html#manual-linking" target="_blank">here</a>.
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 <code>*AppDelegate.m</code>:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// iOS 9.x or newer
</span>#<span class="token keyword">import</span> <span class="token operator">&lt;</span>React<span class="token operator">/</span>RCTLinkingManager<span class="token punctuation">.</span>h<span class="token operator">&gt;</span>

<span class="token operator">-</span> <span class="token punctuation">(</span>BOOL<span class="token punctuation">)</span>application<span class="token punctuation">:</span><span class="token punctuation">(</span>UIApplication <span class="token operator">*</span><span class="token punctuation">)</span>application
   openURL<span class="token punctuation">:</span><span class="token punctuation">(</span>NSURL <span class="token operator">*</span><span class="token punctuation">)</span>url
   options<span class="token punctuation">:</span><span class="token punctuation">(</span>NSDictionary<span class="token operator">&lt;</span>UIApplicationOpenURLOptionsKey<span class="token punctuation">,</span>id<span class="token operator">&gt;</span> <span class="token operator">*</span><span class="token punctuation">)</span>options
<span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">[</span>RCTLinkingManager application<span class="token punctuation">:</span>app openURL<span class="token punctuation">:</span>url options<span class="token punctuation">:</span>options<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>If you're targeting iOS 8.x or older, you can use the following code instead:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// iOS 8.x or older
</span>#<span class="token keyword">import</span> <span class="token operator">&lt;</span>React<span class="token operator">/</span>RCTLinkingManager<span class="token punctuation">.</span>h<span class="token operator">&gt;</span>

<span class="token operator">-</span> <span class="token punctuation">(</span>BOOL<span class="token punctuation">)</span>application<span class="token punctuation">:</span><span class="token punctuation">(</span>UIApplication <span class="token operator">*</span><span class="token punctuation">)</span>application openURL<span class="token punctuation">:</span><span class="token punctuation">(</span>NSURL <span class="token operator">*</span><span class="token punctuation">)</span>url
  sourceApplication<span class="token punctuation">:</span><span class="token punctuation">(</span>NSString <span class="token operator">*</span><span class="token punctuation">)</span>sourceApplication annotation<span class="token punctuation">:</span><span class="token punctuation">(</span>id<span class="token punctuation">)</span>annotation
<span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">[</span>RCTLinkingManager application<span class="token punctuation">:</span>application openURL<span class="token punctuation">:</span>url
                      sourceApplication<span class="token punctuation">:</span>sourceApplication annotation<span class="token punctuation">:</span>annotation<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>// If your app is using <a href="https://developer.apple.com/library/prerelease/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html" target="_blank">Universal Links</a>,
you'll need to add the following code as well:</p><div class="prism language-javascript"><span class="token operator">-</span> <span class="token punctuation">(</span>BOOL<span class="token punctuation">)</span>application<span class="token punctuation">:</span><span class="token punctuation">(</span>UIApplication <span class="token operator">*</span><span class="token punctuation">)</span>application continueUserActivity<span class="token punctuation">:</span><span class="token punctuation">(</span>NSUserActivity <span class="token operator">*</span><span class="token punctuation">)</span>userActivity
 restorationHandler<span class="token punctuation">:</span><span class="token punctuation">(</span><span class="token keyword">void</span> <span class="token punctuation">(</span><span class="token operator">^</span><span class="token punctuation">)</span><span class="token punctuation">(</span>NSArray <span class="token operator">*</span> _Nullable<span class="token punctuation">)</span><span class="token punctuation">)</span>restorationHandler
<span class="token punctuation">{</span>
 <span class="token keyword">return</span> <span class="token punctuation">[</span>RCTLinkingManager application<span class="token punctuation">:</span>application
                  continueUserActivity<span class="token punctuation">:</span>userActivity
                    restorationHandler<span class="token punctuation">:</span>restorationHandler<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>And then on your React component you'll be able to listen to the events on
<code>Linking</code> as follows</p><div class="prism language-javascript"><span class="token function">componentDidMount</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  Linking<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">'url'</span><span class="token punctuation">,</span> <span class="token keyword">this</span><span class="token punctuation">.</span>_handleOpenURL<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token function">componentWillUnmount</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  Linking<span class="token punctuation">.</span><span class="token function">removeEventListener</span><span class="token punctuation">(</span><span class="token string">'url'</span><span class="token punctuation">,</span> <span class="token keyword">this</span><span class="token punctuation">.</span>_handleOpenURL<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token function">_handleOpenURL</span><span class="token punctuation">(</span>event<span class="token punctuation">)</span> <span class="token punctuation">{</span>
  console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>event<span class="token punctuation">.</span>url<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><h4><a class="anchor" name="opening-external-links"></a>Opening external links <a class="hash-link" href="docs/linking.html#opening-external-links">#</a></h4><p>To start the corresponding activity for a link (web URL, email, contact etc.), call</p><div class="prism language-javascript">Linking<span class="token punctuation">.</span><span class="token function">openURL</span><span class="token punctuation">(</span>url<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token keyword">catch</span><span class="token punctuation">(</span>err <span class="token operator">=&gt;</span> console<span class="token punctuation">.</span><span class="token function">error</span><span class="token punctuation">(</span><span class="token string">'An error occurred'</span><span class="token punctuation">,</span> err<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div><p>If you want to check if any installed app can handle a given URL beforehand you can call</p><div class="prism language-javascript">Linking<span class="token punctuation">.</span><span class="token function">canOpenURL</span><span class="token punctuation">(</span>url<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span>supported <span class="token operator">=&gt;</span> <span class="token punctuation">{</span>
  <span class="token keyword">if</span> <span class="token punctuation">(</span><span class="token operator">!</span>supported<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Can\'t handle url: '</span> <span class="token operator">+</span> url<span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span>
    <span class="token keyword">return</span> Linking<span class="token punctuation">.</span><span class="token function">openURL</span><span class="token punctuation">(</span>url<span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token keyword">catch</span><span class="token punctuation">(</span>err <span class="token operator">=&gt;</span> console<span class="token punctuation">.</span><span class="token function">error</span><span class="token punctuation">(</span><span class="token string">'An error occurred'</span><span class="token punctuation">,</span> err<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></div><span><h3><a class="anchor" name="methods"></a>Methods <a class="hash-link" href="docs/linking.html#methods">#</a></h3><div class="props"><div class="prop"><h4 class="methodTitle"><a class="anchor" name="constructor"></a>constructor<span class="methodType">()</span> <a class="hash-link" href="docs/linking.html#constructor">#</a></h4></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="addeventlistener"></a>addEventListener<span class="methodType">(type, handler)</span> <a class="hash-link" href="docs/linking.html#addeventlistener">#</a></h4><div><p>Add a handler to Linking changes by listening to the <code>url</code> event type
and providing the handler</p></div></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="removeeventlistener"></a>removeEventListener<span class="methodType">(type, handler)</span> <a class="hash-link" href="docs/linking.html#removeeventlistener">#</a></h4><div><p>Remove a handler by passing the <code>url</code> event type and the handler</p></div></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="openurl"></a>openURL<span class="methodType">(url)</span> <a class="hash-link" href="docs/linking.html#openurl">#</a></h4><div><p>Try to open the given <code>url</code> with any of the installed apps.</p><p>You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android
or "<a href="http://maps.apple.com/?ll=37.484847,-122.148386">http://maps.apple.com/?ll=37.484847,-122.148386</a>" on iOS), a contact,
or any other URL that can be opened with the installed apps.</p><p>The method returns a <code>Promise</code> 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.</p><p>NOTE: 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.</p><p>NOTE: For web URLs, the protocol ("http://", "https://") must be set accordingly!</p></div></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="canopenurl"></a>canOpenURL<span class="methodType">(url)</span> <a class="hash-link" href="docs/linking.html#canopenurl">#</a></h4><div><p>Determine whether or not an installed app can handle a given URL.</p><p>NOTE: For web URLs, the protocol ("http://", "https://") must be set accordingly!</p><p>NOTE: As of iOS 9, your app needs to provide the <code>LSApplicationQueriesSchemes</code> key
inside <code>Info.plist</code> or canOpenURL will always return false.</p><p>@param URL the URL to open</p></div></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="getinitialurl"></a>getInitialURL<span class="methodType">()</span> <a class="hash-link" href="docs/linking.html#getinitialurl">#</a></h4><div><p>If the app launch was triggered by an app link,
it will give the link url, otherwise it will give <code>null</code></p><p>NOTE: To support deep linking on Android, refer <a href="http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents">http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents</a></p></div></div></div></span></div>