|
|
@@ -0,0 +1,899 @@
|
|
|
1
|
+# Cordova Universal Links Plugin
|
|
|
2
|
+This Cordova plugin adds support for opening an application from the browser when user clicks on the link. Better known as:
|
|
|
3
|
+- [Universal Links on iOS](https://developer.apple.com/library/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html)
|
|
|
4
|
+- [Deep Linking on Android](https://developer.android.com/training/app-indexing/deep-linking.html)
|
|
|
5
|
+
|
|
|
6
|
+Basically, you can have a single link that will either open your app or your website, if the app isn't installed.
|
|
|
7
|
+
|
|
|
8
|
+Integration process is simple:
|
|
|
9
|
+
|
|
|
10
|
+1. Add the plugin to your project (see [Installation](#installation)).
|
|
|
11
|
+2. Define supported hosts and paths in Cordova's `config.xml` (see [Cordova config preferences](#cordova-config-preferences)).
|
|
|
12
|
+3. Write some JavaScript code to listen for application launch by the links (see [Application launch handling](#application-launch-handling)).
|
|
|
13
|
+4. Build project from the CLI.
|
|
|
14
|
+5. Activate support for UL on your website (see [Android web integration](#android-web-integration) and [iOS web integration](#ios-web-integration)).
|
|
|
15
|
+6. Test it (see [Test UL for Android locally](#testing-ul-for-android-locally) and [Testing iOS application](#testing-ios-application)).
|
|
|
16
|
+
|
|
|
17
|
+It is important not only to redirect users to your app from the web, but also provide them with the information they were looking for. For example, if someone clicks on `http://mysite.com/news` and get redirected in the app - they are probably hoping to see the `news` page in it. The plugin will help developers with that. In `config.xml` you can specify an event name that is dispatched when user opens the app from the certain link. This way, the appropriate method of your web project will be called, and you can show to user the requested content.
|
|
|
18
|
+
|
|
|
19
|
+**Note:** At the moment the plugin doesn't support custom url schemes, but they can be added later.
|
|
|
20
|
+
|
|
|
21
|
+## Supported Platforms
|
|
|
22
|
+- Android 4.0.0 or above.
|
|
|
23
|
+- iOS 9.0 or above. Xcode 7 is required. To build plugin with Xcode 6 - [read the instructions](#how-to-build-plugin-in-xcode-6) below.
|
|
|
24
|
+
|
|
|
25
|
+**iOS Note:** you can use this plugin in iOS 8 applications. It will not crash the app, but it also is not gonna handle the links, because this is iOS 9 feature.
|
|
|
26
|
+
|
|
|
27
|
+## Documentation
|
|
|
28
|
+- [Installation](#installation)
|
|
|
29
|
+- [Migrating from previous versions](#migrating-from-previous-versions)
|
|
|
30
|
+- [How to build plugin in Xcode 6](#how-to-build-plugin-in-xcode-6)
|
|
|
31
|
+- [Cordova config preferences](#cordova-config-preferences)
|
|
|
32
|
+- [Application launch handling](#application-launch-handling)
|
|
|
33
|
+- [Android web integration](#android-web-integration)
|
|
|
34
|
+ - [Modify web pages](#modify-web-pages)
|
|
|
35
|
+ - [Verify your website on Webmaster Tools](#verify-your-website-on-webmaster-tools)
|
|
|
36
|
+ - [Connect your app in the Google Play console](#connect-your-app-in-the-google-play-console)
|
|
|
37
|
+ - [Digital Asset Links support](#digital-asset-links-support)
|
|
|
38
|
+- [Testing UL for Android locally](#testing-ul-for-android-locally)
|
|
|
39
|
+- [iOS web integration](#ios-web-integration)
|
|
|
40
|
+ - [Activate UL support in member center](#activate-ul-support-in-member-center)
|
|
|
41
|
+ - [Configure apple-app-site-association file for website](#configure-apple-app-site-association-file-for-website)
|
|
|
42
|
+- [Testing iOS application](#testing-ios-application)
|
|
|
43
|
+- [Useful notes on Universal Links for iOS](#useful-notes-on-universal-links-for-ios)
|
|
|
44
|
+ - [They don't work everywhere](#they-dont-work-everywhere)
|
|
|
45
|
+ - [How links handled in Safari](#how-links-handled-in-safari)
|
|
|
46
|
+- [Additional documentation links](#additional-documentation-links)
|
|
|
47
|
+
|
|
|
48
|
+### Installation
|
|
|
49
|
+This requires cordova 5.0+ (current stable 1.2.1)
|
|
|
50
|
+
|
|
|
51
|
+```sh
|
|
|
52
|
+cordova plugin add cordova-mirtech-plugin-universal-links
|
|
|
53
|
+```
|
|
|
54
|
+
|
|
|
55
|
+It is also possible to install via repo url directly (**unstable**)
|
|
|
56
|
+
|
|
|
57
|
+```sh
|
|
|
58
|
+cordova plugin add https://github.com/martindrapeau/cordova-universal-links-plugin.git
|
|
|
59
|
+```
|
|
|
60
|
+
|
|
|
61
|
+### Migrating from previous versions
|
|
|
62
|
+
|
|
|
63
|
+##### From v1.0.x to v1.1.x
|
|
|
64
|
+
|
|
|
65
|
+In v1.0.x to capture universal links events you had to subscribe on them like so:
|
|
|
66
|
+```js
|
|
|
67
|
+document.addEventListener('eventName', didLaunchAppFromLink, false);
|
|
|
68
|
+
|
|
|
69
|
+function didLaunchAppFromLink(event) {
|
|
|
70
|
+ var urlData = event.detail;
|
|
|
71
|
+ console.log('Did launch application from the link: ' + urlData.url);
|
|
|
72
|
+ // do some work
|
|
|
73
|
+}
|
|
|
74
|
+```
|
|
|
75
|
+And there were some problems with the timing: event could be fired long before you were subscribing to it.
|
|
|
76
|
+
|
|
|
77
|
+From v1.1.0 it changes to the familiar Cordova style:
|
|
|
78
|
+```js
|
|
|
79
|
+var app = {
|
|
|
80
|
+ // Application Constructor
|
|
|
81
|
+ initialize: function() {
|
|
|
82
|
+ this.bindEvents();
|
|
|
83
|
+ },
|
|
|
84
|
+
|
|
|
85
|
+ // Bind Event Listeners
|
|
|
86
|
+ bindEvents: function() {
|
|
|
87
|
+ document.addEventListener('deviceready', this.onDeviceReady, false);
|
|
|
88
|
+ },
|
|
|
89
|
+
|
|
|
90
|
+ // deviceready Event Handler
|
|
|
91
|
+ onDeviceReady: function() {
|
|
|
92
|
+ universalLinks.subscribe('eventName', app.didLaunchAppFromLink);
|
|
|
93
|
+ },
|
|
|
94
|
+
|
|
|
95
|
+ didLaunchAppFromLink: function(eventData) {
|
|
|
96
|
+ alert('Did launch application from the link: ' + eventData.url);
|
|
|
97
|
+ }
|
|
|
98
|
+};
|
|
|
99
|
+
|
|
|
100
|
+app.initialize();
|
|
|
101
|
+```
|
|
|
102
|
+
|
|
|
103
|
+As you can see, now you subscribe to event via `universalLinks` module when `deviceready` is fired. Actually, you can subscribe to it in any place of your application: plugin stores the event internally and dispatches it when there is a subscriber for it.
|
|
|
104
|
+
|
|
|
105
|
+Also, in v1.0.x `ul_didLaunchAppFromLink` was used as a default event name. From v1.1.0 you can just do like that:
|
|
|
106
|
+```js
|
|
|
107
|
+universalLinks.subscribe(null, callbackFunction);
|
|
|
108
|
+```
|
|
|
109
|
+If you didn't specify event name for the `path` or `host` - in the JS code just pass `null` as event name. But just for readability you might want to specify it `config.xml`.
|
|
|
110
|
+
|
|
|
111
|
+### How to build plugin in Xcode 6
|
|
|
112
|
+
|
|
|
113
|
+If you are still using Xcode 6 and there is no way for you to upgrade right now to Xcode 7 - follow the instructions below in order to use this plugin.
|
|
|
114
|
+
|
|
|
115
|
+1. Clone the `xcode6-support` branch of the plugin from the GitHub:
|
|
|
116
|
+
|
|
|
117
|
+ ```sh
|
|
|
118
|
+ mkdir /Workspace/Mobile/CordovaPlugins
|
|
|
119
|
+ cd /Workspace/Mobile/CordovaPlugins
|
|
|
120
|
+ git clone -b xcode6-support https://github.com/martindrapeau/cordova-universal-links-plugin.git
|
|
|
121
|
+ ```
|
|
|
122
|
+
|
|
|
123
|
+2. Go to your applications project and add plugin from the cloned source:
|
|
|
124
|
+
|
|
|
125
|
+ ```sh
|
|
|
126
|
+ cd /Workspace/Mobile/CoolApp
|
|
|
127
|
+ cordova plugin add /Workspace/Mobile/CordovaPlugins/cordova-mirtech-plugin-universal-links/
|
|
|
128
|
+ ```
|
|
|
129
|
+
|
|
|
130
|
+Now you can build your project in Xcode 6.
|
|
|
131
|
+
|
|
|
132
|
+### Cordova config preferences
|
|
|
133
|
+
|
|
|
134
|
+Cordova uses `config.xml` file to set different project preferences: name, description, starting page and so on. Using this config file you can also set options for the plugin.
|
|
|
135
|
+
|
|
|
136
|
+Those preferences are specified inside the `<universal-links>` block. For example:
|
|
|
137
|
+
|
|
|
138
|
+```xml
|
|
|
139
|
+<universal-links>
|
|
|
140
|
+ <host name="example.com">
|
|
|
141
|
+ <path url="/some/path" />
|
|
|
142
|
+ </host>
|
|
|
143
|
+</universal-links>
|
|
|
144
|
+```
|
|
|
145
|
+
|
|
|
146
|
+In it you define hosts and paths that application should handle. You can have as many hosts and paths as you like.
|
|
|
147
|
+
|
|
|
148
|
+#### host
|
|
|
149
|
+`<host />` tag lets you describe hosts, that your application supports. It can have three attributes:
|
|
|
150
|
+- `name` - hostname. **This is a required attribute.**
|
|
|
151
|
+- `scheme` - supported url scheme. Should be either `http` or `https`. If not set - `http` is used.
|
|
|
152
|
+- `event` - name of the event, that is used to match application launch from this host to a callback on the JS side. If not set - pass `null` as event name when you are subscribing in JS code.
|
|
|
153
|
+
|
|
|
154
|
+For example,
|
|
|
155
|
+
|
|
|
156
|
+```xml
|
|
|
157
|
+<universal-links>
|
|
|
158
|
+ <host name="example.com" scheme="https" event="ul_myExampleEvent" />
|
|
|
159
|
+</universal-links>
|
|
|
160
|
+```
|
|
|
161
|
+
|
|
|
162
|
+defines, that when user clicks on any `https://example.com` link - callback, that was set for `ul_myExampleEvent` gets called. More details regarding event handling can be found [below](#application-launch-handling).
|
|
|
163
|
+
|
|
|
164
|
+You can also use wildcards for domains. For example,
|
|
|
165
|
+
|
|
|
166
|
+```xml
|
|
|
167
|
+<universal-links>
|
|
|
168
|
+ <host name="*.users.example.com" scheme="https" event="wildcardusers" />
|
|
|
169
|
+ <host name="*.example.com" scheme="https" event="wildcardmatch" />
|
|
|
170
|
+</universal-links>
|
|
|
171
|
+```
|
|
|
172
|
+
|
|
|
173
|
+Please note, that iOS will look for the `apple-app-site-association` on `https://users.example.com/apple-app-site-association` and `https://example.com/apple-app-site-association` respectively.
|
|
|
174
|
+
|
|
|
175
|
+Android will try to access the [app links file](https://developer.android.com/training/app-links/index.html#web-assoc) at `https://*.users.example.com/.well-known/assetlinks.json` and `https://*.example.com/.well-known/assetlinks.json` respectively.
|
|
|
176
|
+
|
|
|
177
|
+#### path
|
|
|
178
|
+In `<path />` tag you define which paths for the given host you want to support. If no `<path />` is set - then we want to handle all of them. If paths are defined - then application will process only those links.
|
|
|
179
|
+
|
|
|
180
|
+Supported attributes are:
|
|
|
181
|
+- `url` - path component of the url; should be relative to the host name. **This is a required attribute.**
|
|
|
182
|
+- `event` - name of the event, that is used to match application launch from the given hostname and path to a callback on the JS side. If not set - pass `null` as event name when you are subscribing in JS code.
|
|
|
183
|
+
|
|
|
184
|
+For example,
|
|
|
185
|
+
|
|
|
186
|
+```xml
|
|
|
187
|
+<universal-links>
|
|
|
188
|
+ <host name="example.com">
|
|
|
189
|
+ <path url="/some/path" />
|
|
|
190
|
+ </host>
|
|
|
191
|
+</universal-links>
|
|
|
192
|
+```
|
|
|
193
|
+
|
|
|
194
|
+defines, that when user clicks on `http://example.com/some/path` - application will be launched, and default callback gets called. All other links from that host will be ignored.
|
|
|
195
|
+
|
|
|
196
|
+Query parameters are not used for link matching. For example, `http://example.com/some/path?foo=bar#some_tag` will work the same way as `http://example.com/some/path` does.
|
|
|
197
|
+
|
|
|
198
|
+In order to support all links inside `/some/path/` you can use `*` like so:
|
|
|
199
|
+
|
|
|
200
|
+```xml
|
|
|
201
|
+<universal-links>
|
|
|
202
|
+ <host name="example.com">
|
|
|
203
|
+ <path url="/some/path/*" />
|
|
|
204
|
+ </host>
|
|
|
205
|
+</universal-links>
|
|
|
206
|
+```
|
|
|
207
|
+
|
|
|
208
|
+`*` can be used only for paths, but you can place it anywhere. For example,
|
|
|
209
|
+
|
|
|
210
|
+```xml
|
|
|
211
|
+<universal-links>
|
|
|
212
|
+ <host name="example.com">
|
|
|
213
|
+ <path url="*mypath*" />
|
|
|
214
|
+ </host>
|
|
|
215
|
+</universal-links>
|
|
|
216
|
+```
|
|
|
217
|
+
|
|
|
218
|
+states, that application can handle any link from `http://example.com` which has `mypath` string in his path component: `http://example.com/some/long/mypath/test.html`, `http://example.com/testmypath.html` and so on.
|
|
|
219
|
+
|
|
|
220
|
+**Note:** Following configuration
|
|
|
221
|
+
|
|
|
222
|
+```xml
|
|
|
223
|
+<universal-links>
|
|
|
224
|
+ <host name="example.com" />
|
|
|
225
|
+</universal-links>
|
|
|
226
|
+```
|
|
|
227
|
+
|
|
|
228
|
+is the same as:
|
|
|
229
|
+
|
|
|
230
|
+```xml
|
|
|
231
|
+<universal-links>
|
|
|
232
|
+ <host name="example.com">
|
|
|
233
|
+ <path url="*" />
|
|
|
234
|
+ </host>
|
|
|
235
|
+</universal-links>
|
|
|
236
|
+```
|
|
|
237
|
+
|
|
|
238
|
+#### ios-team-id
|
|
|
239
|
+
|
|
|
240
|
+As described in `Step 2` of [Configure apple-app-site-association file for website](#configure-apple-app-site-association-file-for-website) section: when application is build from the CLI - plugin generates `apple-app-site-association` files for each host, defined in `config.xml`. In them there's an `appID` property that holds your iOS Team ID and Bundle ID:
|
|
|
241
|
+
|
|
|
242
|
+```json
|
|
|
243
|
+{
|
|
|
244
|
+ "applinks": {
|
|
|
245
|
+ "apps": [],
|
|
|
246
|
+ "details": [
|
|
|
247
|
+ {
|
|
|
248
|
+ "appID": "<TEAM_ID_FROM_MEMBER_CENTER>.<BUNDLE_ID>",
|
|
|
249
|
+ "paths": [
|
|
|
250
|
+ "/some/path/*"
|
|
|
251
|
+ ]
|
|
|
252
|
+ }
|
|
|
253
|
+ ]
|
|
|
254
|
+ }
|
|
|
255
|
+}
|
|
|
256
|
+```
|
|
|
257
|
+
|
|
|
258
|
+- `<BUNDLE_ID>` is replaced with the id, that is defined in the `widget` of your `config.xml`. For example:
|
|
|
259
|
+
|
|
|
260
|
+ ```xml
|
|
|
261
|
+ <widget id="com.example.ul" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
|
|
|
262
|
+ ```
|
|
|
263
|
+
|
|
|
264
|
+- `<TEAM_ID_FROM_MEMBER_CENTER>` - that property is defined in the member center of your iOS account. So, you can either put it in the generated `apple-app-site-association` file manually, or use `<ios-team-id>` preference in `config.xml` like so:
|
|
|
265
|
+
|
|
|
266
|
+ ```xml
|
|
|
267
|
+ <universal-links>
|
|
|
268
|
+ <ios-team-id value="<TEAM_ID_FROM_MEMBER_CENTER>" />
|
|
|
269
|
+ </universal-links>
|
|
|
270
|
+ ```
|
|
|
271
|
+
|
|
|
272
|
+For example, following `config.xml`
|
|
|
273
|
+```xml
|
|
|
274
|
+<widget id="com.example.ul" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
|
|
|
275
|
+
|
|
|
276
|
+<!-- some other cordova preferences -->
|
|
|
277
|
+
|
|
|
278
|
+<universal-links>
|
|
|
279
|
+ <ios-team-id value="1Q2WER3TY" />
|
|
|
280
|
+ <host name="mysite.com" >
|
|
|
281
|
+ <path url="/some/path/*" />
|
|
|
282
|
+ </host>
|
|
|
283
|
+</universal-links>
|
|
|
284
|
+</widget>
|
|
|
285
|
+```
|
|
|
286
|
+
|
|
|
287
|
+will result into
|
|
|
288
|
+```json
|
|
|
289
|
+{
|
|
|
290
|
+ "applinks": {
|
|
|
291
|
+ "apps": [],
|
|
|
292
|
+ "details": [
|
|
|
293
|
+ {
|
|
|
294
|
+ "appID": "1Q2WER3TY.com.example.ul",
|
|
|
295
|
+ "paths": [
|
|
|
296
|
+ "/some/path/*"
|
|
|
297
|
+ ]
|
|
|
298
|
+ }
|
|
|
299
|
+ ]
|
|
|
300
|
+ }
|
|
|
301
|
+}
|
|
|
302
|
+```
|
|
|
303
|
+
|
|
|
304
|
+This is iOS-only preference, Android doesn't need it.
|
|
|
305
|
+
|
|
|
306
|
+#### Prevent Android from creating multiple app instances
|
|
|
307
|
+
|
|
|
308
|
+When clicking on a universal link from another App (typically from an email client), Android will likely create a new instance of your app, even if it is already loaded in memory. It may even create a new instance with each click, resulting in many instances of your app in the task switcher. See details in [issue #37](https://github.com/martindrapeau/cordova-universal-links-plugin/issues/37).
|
|
|
309
|
+
|
|
|
310
|
+To force Android opening always the same app instance, a known workaround is to change the [activity launch mode](https://developer.android.com/guide/topics/manifest/activity-element.html#lmode) to `singleInstance`. To do so, you can use the following preference in Cordova `config.xml` file:
|
|
|
311
|
+```xml
|
|
|
312
|
+<preference name="AndroidLaunchMode" value="singleInstance" />
|
|
|
313
|
+```
|
|
|
314
|
+
|
|
|
315
|
+### Application launch handling
|
|
|
316
|
+
|
|
|
317
|
+As mentioned - it is not enough just to redirect a user into your app, you will also need to display the correct content. In order to solve that - plugin provides JavaScript module: `universalLinks`. To get notified on application launch do the following:
|
|
|
318
|
+```js
|
|
|
319
|
+universalLinks.subscribe('eventName', function (eventData) {
|
|
|
320
|
+ // do some work
|
|
|
321
|
+ console.log('Did launch application from the link: ' + eventData.url);
|
|
|
322
|
+});
|
|
|
323
|
+```
|
|
|
324
|
+
|
|
|
325
|
+If you didn't specify event name for path and host in `config.xml` - just pass `null` as a first parameter:
|
|
|
326
|
+```js
|
|
|
327
|
+universalLinks.subscribe(null, function (eventData) {
|
|
|
328
|
+ // do some work
|
|
|
329
|
+ console.log('Did launch application from the link: ' + eventData.url);
|
|
|
330
|
+});
|
|
|
331
|
+```
|
|
|
332
|
+
|
|
|
333
|
+`eventData` holds information about the launching url. For example, for `http://myhost.com/news/ul-plugin-released.html?foo=bar#cordova-news` it will be:
|
|
|
334
|
+
|
|
|
335
|
+```json
|
|
|
336
|
+{
|
|
|
337
|
+ "url": "http://myhost.com/news/ul-plugin-released.html?foo=bar#cordova-news",
|
|
|
338
|
+ "scheme": "http",
|
|
|
339
|
+ "host": "myhost.com",
|
|
|
340
|
+ "path": "/news/ul-plugin-released.html",
|
|
|
341
|
+ "params": {
|
|
|
342
|
+ "foo": "bar"
|
|
|
343
|
+ },
|
|
|
344
|
+ "hash": "cordova-news"
|
|
|
345
|
+}
|
|
|
346
|
+```
|
|
|
347
|
+
|
|
|
348
|
+- `url` - original launch url;
|
|
|
349
|
+- `scheme` - url scheme;
|
|
|
350
|
+- `host` - hostname from the url;
|
|
|
351
|
+- `path` - path component of the url;
|
|
|
352
|
+- `params` - dictionary with query parameters; the ones that after `?` character;
|
|
|
353
|
+- `hash` - content after `#` character.
|
|
|
354
|
+
|
|
|
355
|
+If you want - you can also unsubscribe from the events later on:
|
|
|
356
|
+```js
|
|
|
357
|
+universalLinks.unsubscribe('eventName');
|
|
|
358
|
+```
|
|
|
359
|
+
|
|
|
360
|
+Now it's time for some examples. In here we are gonna use Android, because it is easier to test (see [testing for Android](#testing-ul-for-android-locally) section). JavaScript side is platform independent, so all the example code below will also work for iOS.
|
|
|
361
|
+
|
|
|
362
|
+1. Create new Cordova application and add Android platform.
|
|
|
363
|
+
|
|
|
364
|
+ ```sh
|
|
|
365
|
+ cordova create TestAndroidApp com.example.ul TestAndroidApp
|
|
|
366
|
+ cd ./TestAndroidApp
|
|
|
367
|
+ cordova platform add android
|
|
|
368
|
+ ```
|
|
|
369
|
+
|
|
|
370
|
+2. Add UL plugin:
|
|
|
371
|
+
|
|
|
372
|
+ ```sh
|
|
|
373
|
+ cordova plugin add cordova-mirtech-plugin-universal-links
|
|
|
374
|
+ ```
|
|
|
375
|
+
|
|
|
376
|
+3. Add `<universal-links>` preference into `config.xml`:
|
|
|
377
|
+
|
|
|
378
|
+ ```xml
|
|
|
379
|
+ <!-- some other data from config.xml -->
|
|
|
380
|
+ <universal-links>
|
|
|
381
|
+ <host name="myhost.com">
|
|
|
382
|
+ <path url="/news/" event="openNewsListPage" />
|
|
|
383
|
+ <path url="/news/*" event="openNewsDetailedPage" />
|
|
|
384
|
+ </host>
|
|
|
385
|
+ </universal-links>
|
|
|
386
|
+ ```
|
|
|
387
|
+
|
|
|
388
|
+ As you can see - we want our application to be launched, when user goes to the `news` section of our website. And for that - we are gonna dispatch different events to understand, what has happened.
|
|
|
389
|
+
|
|
|
390
|
+4. Subscribe to `openNewsListPage` and `openNewsDetailedPage` events. For that - open `www/js/index.js` and make it look like that:
|
|
|
391
|
+
|
|
|
392
|
+ ```js
|
|
|
393
|
+ var app = {
|
|
|
394
|
+ // Application Constructor
|
|
|
395
|
+ initialize: function() {
|
|
|
396
|
+ this.bindEvents();
|
|
|
397
|
+ },
|
|
|
398
|
+
|
|
|
399
|
+ // Bind Event Listeners
|
|
|
400
|
+ bindEvents: function() {
|
|
|
401
|
+ document.addEventListener('deviceready', this.onDeviceReady, false);
|
|
|
402
|
+ },
|
|
|
403
|
+
|
|
|
404
|
+ // deviceready Event Handler
|
|
|
405
|
+ onDeviceReady: function() {
|
|
|
406
|
+ console.log('Device is ready for work');
|
|
|
407
|
+ universalLinks.subscribe('openNewsListPage', app.onNewsListPageRequested);
|
|
|
408
|
+ universalLinks.subscribe('openNewsDetailedPage', app.onNewsDetailedPageRequested);
|
|
|
409
|
+ },
|
|
|
410
|
+
|
|
|
411
|
+ // openNewsListPage Event Handler
|
|
|
412
|
+ onNewsListPageRequested: function(eventData) {
|
|
|
413
|
+ console.log('Showing list of awesome news.');
|
|
|
414
|
+
|
|
|
415
|
+ // do some work to show list of news
|
|
|
416
|
+ },
|
|
|
417
|
+
|
|
|
418
|
+ // openNewsDetailedPage Event Handler
|
|
|
419
|
+ onNewsDetailedPageRequested: function(eventData) {
|
|
|
420
|
+ console.log('Showing to user details page: ' + eventData.path);
|
|
|
421
|
+
|
|
|
422
|
+ // do some work to show detailed page
|
|
|
423
|
+ }
|
|
|
424
|
+ };
|
|
|
425
|
+
|
|
|
426
|
+ app.initialize();
|
|
|
427
|
+ ```
|
|
|
428
|
+
|
|
|
429
|
+ Now, if the user clicks on `http://myhost.com/news/` link - method `onNewsListPageRequested` will be called, and for every link like `http://myhost.com/news/*` - `onNewsDetailedPageRequested`. Basically, we created a mapping between the links and JavaScript methods.
|
|
|
430
|
+
|
|
|
431
|
+5. Build and run your application:
|
|
|
432
|
+
|
|
|
433
|
+ ```sh
|
|
|
434
|
+ cordova run android
|
|
|
435
|
+ ```
|
|
|
436
|
+
|
|
|
437
|
+6. Close your app.
|
|
|
438
|
+
|
|
|
439
|
+7. Execute in the terminal:
|
|
|
440
|
+
|
|
|
441
|
+ ```sh
|
|
|
442
|
+ adb shell am start -W -a android.intent.action.VIEW -d "http://myhost.com/news/" com.example.ul
|
|
|
443
|
+ ```
|
|
|
444
|
+
|
|
|
445
|
+ As a result, your application will be launched, and in JavaScript console you will see message:
|
|
|
446
|
+
|
|
|
447
|
+ ```
|
|
|
448
|
+ Showing to user list of awesome news.
|
|
|
449
|
+ ```
|
|
|
450
|
+
|
|
|
451
|
+ Repeat operation, but this time with the command:
|
|
|
452
|
+
|
|
|
453
|
+ ```sh
|
|
|
454
|
+ adb shell am start -W -a android.intent.action.VIEW -d "http://myhost.com/news/ul-plugin-released.html" com.example.ul
|
|
|
455
|
+ ```
|
|
|
456
|
+
|
|
|
457
|
+ Application will be launched and you will see in JS console:
|
|
|
458
|
+
|
|
|
459
|
+ ```
|
|
|
460
|
+ Showing to user details page: /news/ul-plugin-released.html
|
|
|
461
|
+ ```
|
|
|
462
|
+
|
|
|
463
|
+Now, let's say, you want your app to handle all links from `myhost.com`, but you need to keep the mapping for the paths. For that you just need to modify your `config.xml` and add default event handler on JavaScript side:
|
|
|
464
|
+
|
|
|
465
|
+1. Open `config.xml` and change `<universal-links>` block like so:
|
|
|
466
|
+
|
|
|
467
|
+ ```xml
|
|
|
468
|
+ <universal-links>
|
|
|
469
|
+ <host name="myhost.com">
|
|
|
470
|
+ <path url="/news/" event="openNewsListPage" />
|
|
|
471
|
+ <path url="/news/*" event="openNewsDetailedPage" />
|
|
|
472
|
+ <path url="*" event="launchedAppFromLink" />
|
|
|
473
|
+ </host>
|
|
|
474
|
+ </universal-links>
|
|
|
475
|
+ ```
|
|
|
476
|
+
|
|
|
477
|
+ As you can see - we added `*` as `path`. This way we declared, that application should be launched from any `http://myhost.com` link.
|
|
|
478
|
+
|
|
|
479
|
+2. Add handling for default UL event in the `www/js/index.js`:
|
|
|
480
|
+
|
|
|
481
|
+ ```js
|
|
|
482
|
+ var app = {
|
|
|
483
|
+ // Application Constructor
|
|
|
484
|
+ initialize: function() {
|
|
|
485
|
+ this.bindEvents();
|
|
|
486
|
+ },
|
|
|
487
|
+
|
|
|
488
|
+ // Bind Event Listeners
|
|
|
489
|
+ bindEvents: function() {
|
|
|
490
|
+ document.addEventListener('deviceready', this.onDeviceReady, false);
|
|
|
491
|
+ },
|
|
|
492
|
+
|
|
|
493
|
+ // deviceready Event Handler
|
|
|
494
|
+ onDeviceReady: function() {
|
|
|
495
|
+ console.log('Handle deviceready event if you need');
|
|
|
496
|
+ universalLinks.subscribe('openNewsListPage', app.onNewsListPageRequested);
|
|
|
497
|
+ universalLinks.subscribe('openNewsDetailedPage', app.onNewsDetailedPageRequested);
|
|
|
498
|
+ universalLinks.subscribe('launchedAppFromLink', app.onApplicationDidLaunchFromLink);
|
|
|
499
|
+ },
|
|
|
500
|
+
|
|
|
501
|
+ // openNewsListPage Event Handler
|
|
|
502
|
+ onNewsListPageRequested: function(eventData) {
|
|
|
503
|
+ console.log('Showing to user list of awesome news');
|
|
|
504
|
+
|
|
|
505
|
+ // do some work to show list of news
|
|
|
506
|
+ },
|
|
|
507
|
+
|
|
|
508
|
+ // openNewsDetailedPage Event Handler
|
|
|
509
|
+ onNewsDetailedPageRequested: function(eventData) {
|
|
|
510
|
+ console.log('Showing to user details page for some news');
|
|
|
511
|
+
|
|
|
512
|
+ // do some work to show detailed page
|
|
|
513
|
+ },
|
|
|
514
|
+
|
|
|
515
|
+ // launchedAppFromLink Event Handler
|
|
|
516
|
+ onApplicationDidLaunchFromLink: function(eventData) {
|
|
|
517
|
+ console.log('Did launch app from the link: ' + eventData.url);
|
|
|
518
|
+ }
|
|
|
519
|
+ };
|
|
|
520
|
+
|
|
|
521
|
+ app.initialize();
|
|
|
522
|
+ ```
|
|
|
523
|
+
|
|
|
524
|
+That's it! Now, by default for `myhost.com` links `onApplicationDidLaunchFromLink` method will be called, but for `news` section - `onNewsListPageRequested` and `onNewsDetailedPageRequested`.
|
|
|
525
|
+
|
|
|
526
|
+### Android web integration
|
|
|
527
|
+
|
|
|
528
|
+If you have already tried to use `adb` to simulate application launch from the link - you probably saw chooser dialog with at least two applications in it: browser and your app. This happens because web content can be handled by multiple things. To prevent this from happening you need to activate app indexing. App indexing is the second part of deep linking, where you link that URI/URL between Google and your app.
|
|
|
529
|
+
|
|
|
530
|
+Integration process consists of three steps:
|
|
|
531
|
+
|
|
|
532
|
+1. Modify your web pages by adding special `<link />` tags in the `<head />` section.
|
|
|
533
|
+2. Verify your website on Webmaster Tools.
|
|
|
534
|
+3. Connect your app in the Google Play console.
|
|
|
535
|
+
|
|
|
536
|
+#### Modify web pages
|
|
|
537
|
+
|
|
|
538
|
+To create a link between your mobile content and the page on the website you need to include proper `<link />` tags in the `<head />` section of your website.
|
|
|
539
|
+
|
|
|
540
|
+Link tag is constructed like so:
|
|
|
541
|
+
|
|
|
542
|
+```html
|
|
|
543
|
+<link rel="alternate"
|
|
|
544
|
+ href="android-app://<package_name>/<scheme>/<host><path>" />
|
|
|
545
|
+```
|
|
|
546
|
+
|
|
|
547
|
+where:
|
|
|
548
|
+- `<package_name>` - your application's package name;
|
|
|
549
|
+- `<scheme>` - url scheme;
|
|
|
550
|
+- `<host>` - hostname;
|
|
|
551
|
+- `<path>` - path component.
|
|
|
552
|
+
|
|
|
553
|
+For example, if your `config.xml` file looks like this:
|
|
|
554
|
+
|
|
|
555
|
+```xml
|
|
|
556
|
+<universal-links>
|
|
|
557
|
+ <host name="myhost.com">
|
|
|
558
|
+ <path url="/news/" />
|
|
|
559
|
+ <path url="/profile/" />
|
|
|
560
|
+ </host>
|
|
|
561
|
+</universal-links>
|
|
|
562
|
+```
|
|
|
563
|
+
|
|
|
564
|
+and a package name is `com.example.ul`, then `<head />` section on your website will be:
|
|
|
565
|
+
|
|
|
566
|
+```html
|
|
|
567
|
+<head>
|
|
|
568
|
+<link rel="alternate" href="android-app://com.example.ul/http/myhost.com/news/" />
|
|
|
569
|
+<link rel="alternate" href="android-app://com.example.ul/http/myhost.com/profile/" />
|
|
|
570
|
+
|
|
|
571
|
+<!-- Your other stuff from the head tag -->
|
|
|
572
|
+</head>
|
|
|
573
|
+```
|
|
|
574
|
+
|
|
|
575
|
+Good news is that **plugin generates those tags for you**. When you run `cordova build` (or `cordova run`) - they are placed in `ul_web_hooks/android/android_web_hook.html` file inside your Cordova project root directory.
|
|
|
576
|
+
|
|
|
577
|
+So, instead of manually writing them down - you can take them from that file and put on the website.
|
|
|
578
|
+
|
|
|
579
|
+#### Verify your website on Webmaster Tools
|
|
|
580
|
+
|
|
|
581
|
+If your website is brand new, you’ll want to verify it through [Webmaster Tools](https://www.google.com/webmasters/tools/). That’s how the Google crawler knows that it’s there and can index it to do everything it needs to do. In order to do that - just add your website in the console and follow the instructions to versify, that you own the site. Most likely, they will ask you to add something on your page.
|
|
|
582
|
+
|
|
|
583
|
+#### Connect your app in the Google Play console
|
|
|
584
|
+
|
|
|
585
|
+Next, you’ll want to connect your app using the Google Play Console so the app indexing starts working. If you go to your app, there’s a menu that says `Services and API` in which you can click `Verify Website`, and provide the URL to check that it has the appropriate tags in the HTML. Once that’s all set up, it will start showing in search results.
|
|
|
586
|
+
|
|
|
587
|
+#### Digital Asset Links support
|
|
|
588
|
+
|
|
|
589
|
+For Android version 6.0 (Marshmallow) or greater [Digital Asset Links](https://developers.google.com/digital-asset-links/v1/getting-started) can be used.
|
|
|
590
|
+
|
|
|
591
|
+Here's a very simplified example of how the website `www.example.com` could use Digital Asset Links to specify that any links to URLs in that site should open in a designated app rather than the browser:
|
|
|
592
|
+
|
|
|
593
|
+1. The website `www.example.com` publishes a statement list at `https://www.example.com/.well-known/assetlinks.json`. This is the official name and location for a statement list on a site. Statement lists in any other location, or with any other name, are not valid for this site. In our example, the statement list consists of one statement, granting its Android app the permission to open links on its site:
|
|
|
594
|
+
|
|
|
595
|
+ ```json
|
|
|
596
|
+ [{
|
|
|
597
|
+ "relation": ["delegate_permission/common.handle_all_urls"],
|
|
|
598
|
+ "target" : { "namespace": "android_app", "package_name": "com.example.app",
|
|
|
599
|
+ "sha256_cert_fingerprints": ["hash_of_app_certificate"] }
|
|
|
600
|
+ }]
|
|
|
601
|
+ ```
|
|
|
602
|
+
|
|
|
603
|
+ A statement list supports an array of statements within the [ ] marks, but our example file contains only one statement.
|
|
|
604
|
+
|
|
|
605
|
+2. The Android app listed in the statement above has an intent filter that specifies the scheme, host, and path pattern of URLs that it wants to handle: in this case, `https://www.example.com`. The intent filter includes a special attribute `android:autoVerify`, new to Android M, which indicates that Android should verify the statement on the website, described in the intent filter when the app is installed.
|
|
|
606
|
+
|
|
|
607
|
+3. A user installs the app. Android sees the intent filter with the `autoVerify` attribute and checks for the presence of the statement list at the specified site. If present, Android checks whether that file includes a statement granting link handling to the app, and verifies the app against the statement by certificate hash. If everything checks out, Android will then forward any `https://www.example.com` intents to the `example.com` app.
|
|
|
608
|
+
|
|
|
609
|
+4. The user clicks a link to `https://www.example.com/puppies` on the device. This link could be anywhere: in a browser, in a Google Search Appliance suggestion, or anywhere else. Android forwards the intent to the `example.com` app.
|
|
|
610
|
+
|
|
|
611
|
+5. The `example.com` app receives the intent and chooses to handle it, opening the puppies page in the app. If for some reason the app had declined to handle the link, or if the app were not on the device, then the link will be send to the next default intent handler, matching that intent pattern (i.e. browser).
|
|
|
612
|
+
|
|
|
613
|
+### Testing UL for Android locally
|
|
|
614
|
+
|
|
|
615
|
+To test Android application for Deep Linking support you just need to execute the following command in the console:
|
|
|
616
|
+
|
|
|
617
|
+```sh
|
|
|
618
|
+adb shell am start
|
|
|
619
|
+ -W -a android.intent.action.VIEW
|
|
|
620
|
+ -d <URI> <PACKAGE>
|
|
|
621
|
+```
|
|
|
622
|
+
|
|
|
623
|
+where
|
|
|
624
|
+- `<URI>` - url that you want to test;
|
|
|
625
|
+- `<PACKAGE>` - your application's package name.
|
|
|
626
|
+
|
|
|
627
|
+**Note:** if you didn't configure your website for UL support - then most likely after executing the `adb` command you will see a chooser dialog with multiple applications (at least browser and your test app). This happens because you are trying to view web content, and this can be handled by several applications. Just choose your app and proceed. If you configured your website as [described above](#android-web-integration) - then no dialog is shown and your application will be launched directly.
|
|
|
628
|
+
|
|
|
629
|
+Let's create new application to play with:
|
|
|
630
|
+1. Create new Cordova project and add Android platform to it:
|
|
|
631
|
+
|
|
|
632
|
+ ```sh
|
|
|
633
|
+ cordova create TestAndroidApp com.example.ul TestAndroidApp
|
|
|
634
|
+ cd ./TestAndroidApp
|
|
|
635
|
+ cordova platform add android
|
|
|
636
|
+ ```
|
|
|
637
|
+
|
|
|
638
|
+2. Add UL plugin:
|
|
|
639
|
+
|
|
|
640
|
+ ```sh
|
|
|
641
|
+ cordova plugin add cordova-mirtech-plugin-universal-links
|
|
|
642
|
+ ```
|
|
|
643
|
+
|
|
|
644
|
+3. Add `<universal-links>` preference into `config.xml` (`TestAndroidApp/config.xml`):
|
|
|
645
|
+
|
|
|
646
|
+ ```xml
|
|
|
647
|
+ <!-- some other data from config.xml -->
|
|
|
648
|
+ <universal-links>
|
|
|
649
|
+ <host name="myhost.com" />
|
|
|
650
|
+ </universal-links>
|
|
|
651
|
+ ```
|
|
|
652
|
+
|
|
|
653
|
+4. Build and run the app:
|
|
|
654
|
+
|
|
|
655
|
+ ```sh
|
|
|
656
|
+ cordova run android
|
|
|
657
|
+ ```
|
|
|
658
|
+
|
|
|
659
|
+5. Close your application and return to console.
|
|
|
660
|
+6. Enter in console:
|
|
|
661
|
+
|
|
|
662
|
+ ```sh
|
|
|
663
|
+ adb shell am start -W -a android.intent.action.VIEW -d "http://myhost.com/any/path" com.example.ul
|
|
|
664
|
+ ```
|
|
|
665
|
+
|
|
|
666
|
+ As a result, your application will be launched and you will see in console:
|
|
|
667
|
+
|
|
|
668
|
+ ```
|
|
|
669
|
+ Starting: Intent { act=android.intent.action.VIEW dat=http://myhost.com/any/path pkg=com.example.ul }
|
|
|
670
|
+ Status: ok
|
|
|
671
|
+ Activity: com.example.ul/.MainActivity
|
|
|
672
|
+ ThisTime: 52
|
|
|
673
|
+ TotalTime: 52
|
|
|
674
|
+ Complete
|
|
|
675
|
+ ```
|
|
|
676
|
+
|
|
|
677
|
+ If you'll try to use host (or path), that is not defined in `config.xml` - you'll get a following error:
|
|
|
678
|
+
|
|
|
679
|
+ ```
|
|
|
680
|
+ Starting: Intent { act=android.intent.action.VIEW dat=http://anotherhost.com/path pkg=com.example.ul }
|
|
|
681
|
+ Error: Activity not started, unable to resolve Intent { act=android.intent.action.VIEW dat=http://anotherhost.com/path flg=0x10000000 pkg=com.example.ul }
|
|
|
682
|
+ ```
|
|
|
683
|
+
|
|
|
684
|
+This way you can experiment with your Android application and check how it corresponds to different links.
|
|
|
685
|
+
|
|
|
686
|
+### iOS web integration
|
|
|
687
|
+
|
|
|
688
|
+In the case of iOS integration of the Universal Links is a little harder. It consist of two steps:
|
|
|
689
|
+
|
|
|
690
|
+1. Register your application on [developer console](https://developer.apple.com) and enable `Associated Domains` feature. Make sure your website is SSL ready.
|
|
|
691
|
+2. Generate, and upload `apple-app-site-association` file on your website (if you don't have it yet).
|
|
|
692
|
+
|
|
|
693
|
+First one you will have to do manually, but plugin will help you with the second step.
|
|
|
694
|
+
|
|
|
695
|
+#### Activate UL support in member center
|
|
|
696
|
+
|
|
|
697
|
+1. Go to your [developer console](https://developer.apple.com). Click on `Certificate, Identifiers & Profiles` and then on `Identifiers`.
|
|
|
698
|
+
|
|
|
699
|
+ 
|
|
|
700
|
+
|
|
|
701
|
+2. If you already have a registered App Identifier - just skip this and go to `3`. If not - create it by clicking on `+` sign, fill out `name` and `bundle ID`. `name` can be whatever you want, but `bundle ID` should be the one you defined in your Cordova's `config.xml`.
|
|
|
702
|
+
|
|
|
703
|
+ 
|
|
|
704
|
+
|
|
|
705
|
+3. In the `Application Services` section of your App Identifier activate `Associated Domains` and save the changes.
|
|
|
706
|
+
|
|
|
707
|
+ 
|
|
|
708
|
+
|
|
|
709
|
+Now your App ID is registered and has `Associated Domains` feature.
|
|
|
710
|
+
|
|
|
711
|
+#### Configure apple-app-site-association file for website
|
|
|
712
|
+
|
|
|
713
|
+In order for Universal Links to work - you need to associate your application with the certain domain. For that you need to:
|
|
|
714
|
+
|
|
|
715
|
+1. Make your site to work over `https`.
|
|
|
716
|
+2. Create `apple-app-site-association` file, containing your App ID and paths you want to handle.
|
|
|
717
|
+3. Upload `apple-app-site-association` file in the root of your website.
|
|
|
718
|
+
|
|
|
719
|
+##### Step 1
|
|
|
720
|
+
|
|
|
721
|
+We are not gonna describe stuff regarding certificate acquiring and making your website to work over `https`. You can find lots of information about that on the Internet.
|
|
|
722
|
+
|
|
|
723
|
+##### Step 2
|
|
|
724
|
+
|
|
|
725
|
+When you run `cordova build` (or `cordova run`) - plugin takes data from `config.xml` and generates `apple-app-site-association` files for each host you defined. Files are placed in the `ul_web_hooks/ios/` folder of your Cordova project. File names are:
|
|
|
726
|
+```
|
|
|
727
|
+<hostname>#apple-app-site-association
|
|
|
728
|
+```
|
|
|
729
|
+
|
|
|
730
|
+For example, let's say your application's bundle ID is `com.example.ul`, and `config.xml` has several hosts:
|
|
|
731
|
+
|
|
|
732
|
+```xml
|
|
|
733
|
+<universal-links>
|
|
|
734
|
+ <host name="firsthost.com">
|
|
|
735
|
+ <path url="/some/path/*" />
|
|
|
736
|
+ </host>
|
|
|
737
|
+ <host name="secondhost.com" />
|
|
|
738
|
+</universal-links>
|
|
|
739
|
+```
|
|
|
740
|
+
|
|
|
741
|
+Run `cordova build`, and then go to `ul_web_hooks/ios/` folder in your Cordova project. You will see there two files:
|
|
|
742
|
+
|
|
|
743
|
+```
|
|
|
744
|
+firsthost.com#apple-app-site-association
|
|
|
745
|
+secondhost.com#apple-app-site-association
|
|
|
746
|
+```
|
|
|
747
|
+
|
|
|
748
|
+Content of the first one is:
|
|
|
749
|
+```json
|
|
|
750
|
+{
|
|
|
751
|
+ "applinks": {
|
|
|
752
|
+ "apps": [],
|
|
|
753
|
+ "details": [
|
|
|
754
|
+ {
|
|
|
755
|
+ "appID": "<YOUR_TEAM_ID_FROM_MEMBER_CENTER>.com.example.ul",
|
|
|
756
|
+ "paths": [
|
|
|
757
|
+ "/some/path/*"
|
|
|
758
|
+ ]
|
|
|
759
|
+ }
|
|
|
760
|
+ ]
|
|
|
761
|
+ }
|
|
|
762
|
+}
|
|
|
763
|
+```
|
|
|
764
|
+
|
|
|
765
|
+And the second one:
|
|
|
766
|
+```json
|
|
|
767
|
+{
|
|
|
768
|
+ "applinks": {
|
|
|
769
|
+ "apps": [],
|
|
|
770
|
+ "details": [
|
|
|
771
|
+ {
|
|
|
772
|
+ "appID": "<YOUR_TEAM_ID_FROM_MEMBER_CENTER>.com.example.ul",
|
|
|
773
|
+ "paths": [
|
|
|
774
|
+ "*", "/"
|
|
|
775
|
+ ]
|
|
|
776
|
+ }
|
|
|
777
|
+ ]
|
|
|
778
|
+ }
|
|
|
779
|
+}
|
|
|
780
|
+```
|
|
|
781
|
+
|
|
|
782
|
+**Note:** in the second case plugin will add `/` to the paths, so the app would be opened with `https://secondhost.com.com/` links, and not only with `https://secondhost.com/some/random.html`.
|
|
|
783
|
+
|
|
|
784
|
+Before uploading them on your servers - you need to replace `<YOUR_TEAM_ID_FROM_MEMBER_CENTER>` with your actual team ID from the member center. You can find it in `Developer Account Summary` section on the [developer.apple.com](https://developer.apple.com/membercenter/index.action#accountSummary).
|
|
|
785
|
+
|
|
|
786
|
+Also, it is a `Prefix` preference in the App ID description.
|
|
|
787
|
+
|
|
|
788
|
+
|
|
|
789
|
+
|
|
|
790
|
+If you already have `apple-app-site-association` file - then you need to add `applinks` block to it from the generated file.
|
|
|
791
|
+
|
|
|
792
|
+##### Step 3
|
|
|
793
|
+
|
|
|
794
|
+Upload `apple-app-site-association` file in the root of your domain.
|
|
|
795
|
+
|
|
|
796
|
+**It should be downloadable from the direct link.** For example, `https://firsthost.com/apple-app-site-association`.
|
|
|
797
|
+
|
|
|
798
|
+**No redirects are allowed!** When application is launched - it downloads it from that link, so if it can't find it - Universal Links are not gonna work.
|
|
|
799
|
+
|
|
|
800
|
+That's it, you have finished configuring iOS for UL support.
|
|
|
801
|
+
|
|
|
802
|
+### Testing iOS application
|
|
|
803
|
+
|
|
|
804
|
+Unlike Android, Apple doesn't provide any tools to test Universal Links. So you have to do all the [integration stuff](#ios-web-integration) before any real testing. So please, do that.
|
|
|
805
|
+
|
|
|
806
|
+But if you don't want to... well, there is one way to skip it. You can use [branch.io](https://branch.io) to handle all the SSL/apple-app-site-association stuff for you. How to do that - described in their [documentation](https://dev.branch.io/recipes/branch_universal_links/#enable-universal-links-on-the-branch-dashboard). From there you can skip Xcode and SDK integration stuff, because you don't need that.
|
|
|
807
|
+
|
|
|
808
|
+Step-by-step guide:
|
|
|
809
|
+
|
|
|
810
|
+1. Go to developer console and register your App ID, as described in [Activating UL support in member center](#activate-ul-support-in-member-center).
|
|
|
811
|
+
|
|
|
812
|
+2. Register account on [branch.io](https://dashboard.branch.io/), if you don't have it yet.
|
|
|
813
|
+
|
|
|
814
|
+3. Login into [branch dashboard](https://dashboard.branch.io/). Go to `Settings` -> `Link Settings`, activate `Enable Universal Links`, fill in `Bundle identifier` and `Team ID`.
|
|
|
815
|
+
|
|
|
816
|
+ 
|
|
|
817
|
+
|
|
|
818
|
+4. It will take some time to update their servers, so be patient. To check if it is ready - just open [https://bnc.lt/apple-app-site-association](https://bnc.lt/apple-app-site-association) and search for your `Bundle identifier`.
|
|
|
819
|
+
|
|
|
820
|
+ Pay attention for `paths` - if there is any for your app, then write it down.
|
|
|
821
|
+
|
|
|
822
|
+ For example:
|
|
|
823
|
+ ```json
|
|
|
824
|
+ ...,"9F38WJR2U8.com.example.ul":{"paths":["/a2Be/*"]},...
|
|
|
825
|
+ ```
|
|
|
826
|
+
|
|
|
827
|
+5. Create new Cordova iOS application and add UL plugin:
|
|
|
828
|
+
|
|
|
829
|
+ ```sh
|
|
|
830
|
+ cordova create TestProject com.example.ul TestProject
|
|
|
831
|
+ cd ./TestProject
|
|
|
832
|
+ cordova platform add ios
|
|
|
833
|
+ cordova plugin add cordova-mirtech-plugin-universal-links
|
|
|
834
|
+ ```
|
|
|
835
|
+
|
|
|
836
|
+6. Add `bnc.lt` and your other hosts into `config.xml`:
|
|
|
837
|
+
|
|
|
838
|
+ ```xml
|
|
|
839
|
+ <universal-links>
|
|
|
840
|
+ <host name="bnc.lt" />
|
|
|
841
|
+ <host name="yourdomain.com" />
|
|
|
842
|
+ </universal-links>
|
|
|
843
|
+ ```
|
|
|
844
|
+
|
|
|
845
|
+ For test purpose you can leave only `bnc.lt` in there. But if you specifying your hosts - you need to [white label](https://dev.branch.io/recipes/branch_universal_links/#white-label-domains) them.
|
|
|
846
|
+
|
|
|
847
|
+7. Attach your real device to the computer and run application on it:
|
|
|
848
|
+
|
|
|
849
|
+ ```sh
|
|
|
850
|
+ cordova run ios
|
|
|
851
|
+ ```
|
|
|
852
|
+
|
|
|
853
|
+ Emulator will not work.
|
|
|
854
|
+
|
|
|
855
|
+8. Email yourself a link that need's to be tested.
|
|
|
856
|
+
|
|
|
857
|
+ For example, `https://bnc.lt/a2Be/somepage.html`. As you can see, link constructed from hostname and path component, specified in `apple-app-site-association` file. This link may not even lead to the real page, it doesn't matter. It's only purpose is to open the app.
|
|
|
858
|
+
|
|
|
859
|
+ Now click on your link. Application should be launched. If not - check all the steps above. Also, check your provisioning profiles in Xcode.
|
|
|
860
|
+
|
|
|
861
|
+### Useful notes on Universal Links for iOS
|
|
|
862
|
+
|
|
|
863
|
+#### They don't work everywhere
|
|
|
864
|
+
|
|
|
865
|
+First of all - you need to accept the fact, that Universal Links **doesn't work everywhere**. Some applications doesn't respect them. You can read more in [that article](https://blog.branch.io/ios-9.2-deep-linking-guide-transitioning-to-universal-links), section `Universal Links Still Don’t Work Everywhere`.
|
|
|
866
|
+
|
|
|
867
|
+#### How links handled in Safari
|
|
|
868
|
+
|
|
|
869
|
+When user clicks on the link - Safari checks, if any of the installed apps can handle it. If app is found - Safari starts it, if not - link opened as usually in the browser.
|
|
|
870
|
+
|
|
|
871
|
+Now, let's assume you have a following setup in `config.xml`:
|
|
|
872
|
+```xml
|
|
|
873
|
+<universal-links>
|
|
|
874
|
+ <host name="mywebsite.com">
|
|
|
875
|
+ <path url="/some/page.html" />
|
|
|
876
|
+ </host>
|
|
|
877
|
+</universal-links>
|
|
|
878
|
+```
|
|
|
879
|
+
|
|
|
880
|
+By this we state, that our app should handle `http://mywebsite.com/some/page.html` link. So, if user clicks on `http://mywebsite.com` - application would not launch. And this is totally as you want it to be. Now comes the interesting part: if user opens `http://mywebsite.com` in the Safari and then presses on `http://mywebsite.com/some/page.html` link - application is not gonna start, he will stay in the browser. And at the top of that page he will see a Smart Banner. To launch the application user will have to click on that banner. And this is a normal behaviour from iOS. If user already viewing your website in the browser - he doesn't want to leave it, when he clicks on some link, that leads on the page inside your site. But if he clicks on the `http://mywebsite.com/some/page.html` link from some other source - then it will start your application.
|
|
|
881
|
+
|
|
|
882
|
+Another thing that every developer should be aware of:
|
|
|
883
|
+
|
|
|
884
|
+When a user is in an app, opened by Universal Links - a return to browser option will persist at the top of the screen (i.e. `mywebsite.com`). Users who have clicked the `mywebsite.com` option will be taken to their Safari browser, and Smart Banner is persistently rendered on the top of the window. This banner has an `OPEN` call to action. For all future clicks of URLs, associated with this app via Universal Links, the app will never be launched again for the user, and the user will continue being redirected to the Safari page with the banner. If the user clicks `OPEN` - then the app will be launched, and all future clicks of the URL will deep linking the user to the app.
|
|
|
885
|
+
|
|
|
886
|
+### Additional documentation links
|
|
|
887
|
+
|
|
|
888
|
+**Android:**
|
|
|
889
|
+- [Video tutorial on Android App Indexing](https://realm.io/news/juan-gomez-android-app-indexing/)
|
|
|
890
|
+- [Enable Deep Linking on Android](https://developer.android.com/training/app-indexing/deep-linking.html)
|
|
|
891
|
+- [Specifying App Content for Indexing](https://developer.android.com/training/app-indexing/enabling-app-indexing.html)
|
|
|
892
|
+- [Documentation on enabling App Indexing on the website](https://developers.google.com/app-indexing/android/publish#host-your-links)
|
|
|
893
|
+
|
|
|
894
|
+**iOS:**
|
|
|
895
|
+- [Apple documentation on Universal Links](https://developer.apple.com/library/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html)
|
|
|
896
|
+- [Apple documentation on apple-app-site-association file](https://developer.apple.com/library/ios/documentation/Security/Reference/SharedWebCredentialsRef/index.html)
|
|
|
897
|
+- [How to setup universal links on iOS 9](https://blog.branch.io/how-to-setup-universal-links-to-deep-link-on-apple-ios-9)
|
|
|
898
|
+- [Branch.io documentation on universal links](https://dev.branch.io/recipes/branch_universal_links/#enable-universal-links-on-the-branch-dashboard)
|
|
|
899
|
+- [Where universal links don't work](https://blog.branch.io/ios-9.2-deep-linking-guide-transitioning-to-universal-links)
|
