Alfresco Mobile for iOS: App Launch Fundamentals

Apple allows iOS apps to register a custom URL scheme, which allows them to be launched from web pages and third party apps. This page documents a number of ways you, as a web developer, can author HTML and JavaScript to launch the Alfresco Mobile app. We will also demonstrate several different ways to handle cases where the app is not installed on a device.

The Alfresco Mobile URL Scheme

Alfresco Mobile for iOS has registered the alfresco:// URL scheme.

Duplicate installed URL schemes

iOS does not prevent multiple apps from registering the same URL scheme. Due to its Open Source nature, several third party apps exist in the App Store which are built upon the Alfresco Mobile codebase. Unless the developer of the third party app has explicity changed the registered scheme, it is entirely possible for a user to have two or more apps which are able to respond to an alfresco:// link. Apple states that the behaviour in these situations is undefined and it may not be the Alfresco Mobile app which is launched.

A Simple HTML Link

If you can guarantee that your users have the Alfresco Mobile app installed on their devices, you may generate very simple links

Alfresco Mobile for iOS
<a href="alfresco://">Alfresco Mobile for iOS</a>

Error Handling

With the simple HTML link example above, a user who does not have the Alfresco Mobile app installed will be presented with an unhelpful error pop-up and no obvious call to action to fix the problem. Currently Apple provides no means for a web developer to pre-determine whether an app is present on a device or not. Therefore we must construct the HTML link in such a way that Mobile Safari has an error handling path. This error handling generally takes the form of a fallback URL, relocating the user to a marketing site, or the appropriate App Store page.

The error (or fallback) handling requires a few lines of JavaScript. This can be embedded in the link HTML itself or in the <head> section of the web page. The technical details of the JavaScript code are not important; this common technique is used by many app developers.

Alfresco Mobile for iOS
<a href="alfresco://" onclick="setTimeout(function(){ window.location='https://itunes.apple.com/app/alfresco/id459242610?mt=8' }, 100)">Alfresco Mobile for iOS</a>

Let's examine the components of the example above:

onclick="..."
Run some JavaScript code when the user taps on the link.
setTimeout(fn,t)
Execute the JavaScript function fn after t milliseconds
window.location='...'
Relocate the user's browser to a different URL
https://itunes.apple.com/app/alfresco/id459242610?mt=8
The URL of the Alfresco Mobile app in the App Store. These links can be generated easily using the iTunes Link Maker

Putting all this together, we're telling Mobile Safari to redirect the user to a URL (the App Store in this example) 100ms after the link has been tapped. Due to the way iOS operates, Mobile Safari will not run the page redirect code if the user has an app installed that can handle the custom URL scheme. In other words, users that have Alfresco Mobile installed will be presented with that app, whereas users who do not yet have the Alfresco app will be redirected to the correct App Store page where they can download it.

Fallback URLs

The fallback URL that we use doesn't have to address the app's App Store page; although in most cases this offers the best user experience. For example, you may want to present the user with a marketing page first explaining why they should install the app, or you may have a suitably responsive web site that the user can interact with in place of the mobile app.

Improving the HTML Markup

The HTML markup described above had all the JavaScript inline with the link itself. This is fine if there's just one link on the page, but often there will be more and we can improve the HTML markup with that in mind.

Alfresco Mobile for iOS
<head>
  <script type="text/javascript">
  function launchApp(fallbackURL) {
    window.setTimeout(function() {
      window.location = fallbackURL;
    }, 100);
  }
  </script>
</head>

<a href="alfresco://" onclick="launchApp('https://itunes.apple.com/app/alfresco/id459242610?mt=8')">Alfresco Mobile for iOS</a>

The above example is functionally exactly the same as the previous one, but we've moved the JavaScript code into the <head> block of the page. This is not only considered better practice, but also allows us to generate multiple different links in a much cleaner way:

Alfresco Mobile for iOS
An alternate App Store URL
Fallback to the Alfresco Mobile marketing site at mobile.alfresco.com 
<head>
  <script type="text/javascript">
  function launchApp(fallbackURL) {
    window.setTimeout(function() {
      window.location = fallbackURL;
    }, 100);
  }
  </script>
</head>

<a href="alfresco://" onclick="launchApp('https://itunes.apple.com/app/alfresco/id459242610?mt=8')">Alfresco Mobile for iOS</a>
<a href="alfresco://" onclick="launchApp('http://appstore.com/alfresco')">An alternate App Store URL</a>
<a href="alfresco://" onclick="launchApp('http://mobile.alfresco.com')">Fallback to the Alfresco Mobile marketing site at mobile.alfresco.com</a>

Further Information

If you have any questions regarding this document, please contact:

Mike Hatfield
Lead Engineer, Mobile Apps @ Alfresco
[email protected]

July 2015

Copyright © Alfresco Software, Inc.