Add info to deep link docs

content/en/docs/refguide/mobile/using-mobile-capabilities/deep-links.md

@@ -9,7 +9,9 @@ aliases:
 
 ## Introduction
 
-While URLs typically open websites, they can also open an installed app on your mobile device. With this tutorial you will learn how to connect the URL `app://myapp` to your Mendix native app installed on your Android or iOS device. It is also possible to pass additional data using paths, query parameters, and hashes. Passing additional data could look like this: `app://myapp/task/123?action=close#info`. 
+While URLs typically open websites, they can also open an installed app on your mobile device. Certain links can even open a specific page in an installed app on your mobile device. The technology that makes this possible is called deep linking. 
+
+With this tutorial you will learn how to connect the URL `app://myapp` to your Mendix native app installed on your Android or iOS device. It is also possible to pass additional data using paths, query parameters, and hashes. Passing additional data could look like this: `app://myapp/task/123?action=close#info`. 
 
 Deep links are always called or triggered within the schema that they define. For example, using `makeitnative://` instead of `http://` in the mobile browser would force the Make It Native app to open. 
 
@@ -29,6 +31,10 @@ For this tutorial, Mendix recommends running your app from source against a loca
 
 Please note that the Make It Native app has already the registered schema `makeitnative://` and can be used out of the box. To use the Make It Native app with that schema, see the [Using Deep Linking in Your App](#using-deep-linking) section below. If you want to change this schema, see [How to Create a Custom Developer App](/refguide/mobile/distributing-mobile-apps/building-native-apps/how-to-devapps/) to build your own custom developer app and then use the [Setting up App Deep Linking](#set-up) section below to change its schema.
 
+{{% alert color="info" %}}
+Mendix recommends testing deep links in a custom developer app or your own app build instead of the Make It Native app. When the Make It Native app receives a deep link, it reloads your app, which can show an error message in addition to the result of your deep link handling.
+{{% /alert %}}
+
 ## Prerequisites
 
 Before starting this guide, make sure you have completed the following prerequisites:
@@ -81,9 +87,9 @@ The Register Deep Link nanoflow action registers a callback nanoflow, which is c
 The name of the input parameter is case sensitive and can not be changed.
 {{% /alert %}}
 
-#### Parsing a URL To a Mendix Object
+#### Parsing a URL To a Mendix Object {#parsing-url}
 
-The Register Deep Link nanoflow action will create a new Mendix object, split a URL, and set all the object attributes with their values. For example, the URL https://john.doe:secret@www.example.com:123/forum/questions/?tag=networking&order=newest#top has the following attributes and values:
+The Parse URL to Object nanoflow action will create a new Mendix object, split a URL, and set all the object attributes with their values. For example, the URL https://john.doe:secret@www.example.com:123/forum/questions/?tag=networking&order=newest#top has the following attributes and values:
 
 | Attribute                                                   | Value                                                                                        |
 | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -123,34 +129,64 @@ Now that the **Native Deep Link** nanoflow actions are available in Studio Pro,
 
     This nanoflow will be called every time the app is opened using a URL.
 
-1. To parse the URL into an object, you will use a non-persistable entity named **DeepLinkParameter** from the **NativeMobileResources** module in the next step. For now, go to **NativeMobileResources** > **Domain Model** and examine this entity.
+1. To parse the URL into an object, you need a non-persistable entity to hold the URL parts. The Native Mobile Resources module does not include this entity, so you create it yourself:
+
+    1. In your module's domain model, add a non-persistable entity named *DeepLinkParameter*.
+    1. Add a string attribute for each URL part your implementation requires, using the attribute names from the table in [Parsing a URL To a Mendix Object](#parsing-url). For this tutorial, add at least *Href* and *Host*. The attribute names are not case sensitive.
 
-    If you use query strings or more, you can copy the **DeepLinkParameter** entity to your own module. The image below shows you an example. The attributes are all optional and you should only add the attributes your implementation requires. Besides the standard list of possible URL parts, you can also add the query string's keys (for example `?name=Jhon&title=sir`). The attributes are not case sensitive. You can add attributes for path segments of the URL which will be split into `Path0` , `Path1`, and more:
-
-    {{< figure src="/attachments/howto/mobile/native-mobile/implementation/native-deep-link/entity-parameter.png" alt="parameter entity" class="no-border" >}}
+        You can also add attributes for query string keys (for example `?name=Jhon&title=sir`) and for path segments, which are split into `Path0`, `Path1`, and more. The image below shows an example:
+
+        {{< figure src="/attachments/howto/mobile/native-mobile/implementation/native-deep-link/entity-parameter.png" alt="DeepLinkParameter entity with string attributes" class="no-border" >}}
+
+    1. If your app has security enabled, configure the entity's access rules so that your user roles can create the entity and read and write its attributes.
 
 Next you will implement the deep link handler nanoflow **DL_ShowUrlDetails** so that it can pass URL data:
 
 1. In **DL_ShowUrlDetails** drag a parameter into your nanoflow's white space.
 1. Double-click the parameter, give it the name *URL* (which is case sensitive) and the type **String**.
-1. Add a **Parse URL to Object** activity to your nanoflow. Double-click it and configure it like this:
+1. Add a **Parse URL to Object** activity to your nanoflow. Double-click it, set **Entity** to the **DeepLinkParameter** entity you created, and set **Object name** to *DeepLinkParameter*:
 
-    {{< figure src="/attachments/howto/mobile/native-mobile/implementation/native-deep-link/parse-url.png" alt="parse url" class="no-border" >}}
+    {{< figure src="/attachments/howto/mobile/native-mobile/implementation/native-deep-link/parse-url.png" alt="Parse URL to Object dialog" class="no-border" >}}
 
 1. Add a **Show message** activity to the right of your **Parse URL to Object** activity.
 1. Double-click the **Show message** activity.
 1. In **Template** write *Your deep link callback URL {1} host = {2}*.
-1. Click **Parameters** > **New**, write *$Parameter/Href*, and click **OK**.
-1. Click **Parameters** > **New**, write *$Parameter/Host*, and click **OK**.
+1. Click **Parameters** > **New**, write *$DeepLinkParameter/Href*, and click **OK**.
+1. Click **Parameters** > **New**, write *$DeepLinkParameter/Host*, and click **OK**.
 1. Right-click your **Parse URL to Object** activity, click **Set error handling**, and click **Custom without rollback**.
 1. Drop an **End event** below your **Parse URL to Object** activity. Drag a line from **Parse URL to Object** down to the end event, right click it, and click **Set as error handler**.
-1. Add a **Show message** activity to this line. Set it as type **Error**, and into template type *Failed to parse deep link data.*. Your finished nanoflow will look like this:
+1. Add a **Show message** activity to this line. Set it as type **Error**, and into template type *Failed to parse deep link data.* Your finished nanoflow will look like this:
 
     {{< figure src="/attachments/howto/mobile/native-mobile/implementation/native-deep-link/deep-link-nano-full.png" alt="full nanoflow" class="no-border" >}}
 
 ### Testing Deep Linking
 
-Add a few test link buttons, for example {app://myapp/task/123} or {makeitnative://task/123}, to your web page, then re-run your app. Open the your app in your device's browser by typing *{your local IP address}:8080* into the browser. With the app loaded, tap the links to test. You should be brought out of your browser and into your app's page!
+Add a few test links, for example `app://myapp/task/123` (or `makeitnative://task/123` for the Make It Native app), to a page in your app's responsive web navigation profile, then re-run your app. On your device, open the app in a browser by going to *{your local IP address}:8080*. Tap one of the links. Your device switches from the browser to your native app, and **DL_ShowUrlDetails** shows a message with the URL and its host.
+
+### Opening a Specific Page {#open-page}
+
+The message confirms that your app receives the URL. In most apps, you use the URL data to open a specific page instead. This example opens the details page of an invoice, based on an invoice number in the URL's query string, for example `app://myapp/invoice?number=INV-42`.
+
+This example assumes that your app has an *Invoice* entity with a string attribute *Number*, and an *Invoice_Details* page with an *Invoice* page parameter. Your **DeepLinkParameter** entity also needs the string attributes *Path0* and *Number*. Because native apps are [offline-first](/refguide/mobile/building-efficient-mobile-apps/offlinefirst-data/), the invoice must be synchronized to the device.
+
+The table below shows where the parts of these URLs end up in the **DeepLinkParameter** object:
+
+| URL                                 | Host    | Path0     | Path1 | Number   |
+| ----------------------------------- | ------- | --------- | ----- | -------- |
+| `app://myapp/task/123`              | `myapp` | `task`    | `123` |          |
+| `app://myapp/invoice?number=INV-42` | `myapp` | `invoice` |       | `INV-42` |
+
+The host is the same for every link to your app, so use **Path0** to decide which page to open, and use query parameters such as `number` to pass values.
+
+To open the invoice instead of showing a message, extend **DL_ShowUrlDetails**. After **Parse URL to Object**, the nanoflow needs to do the following:
+
+1. Check whether the link is meant for an invoice, which is the case when `$DeepLinkParameter/Path0` is `invoice`. Links meant for other pages then only open the app. For more information, see [Decision](/refguide/decision/).
+1. Retrieve the invoice whose *Number* matches `$DeepLinkParameter/Number` from the database. For more information, see [Retrieve Object(s)](/refguide/retrieve-objects/).
+1. Open *Invoice_Details* with the retrieved invoice, or show a message if no invoice was found. For more information, see [Show Page](/refguide/show-page/).
+
+If you test with the Make It Native app, a link such as `makeitnative://invoice?number=INV-42` has `invoice` as its host, so check `$DeepLinkParameter/Host` instead of `$DeepLinkParameter/Path0`.
+
+To test the example, add the link `app://myapp/invoice?number=INV-42` to your test page and tap it. Your app opens the details page of invoice INV-42.
 
 ## Read more