Additional Server Configuration

Introduction

This document provides additional information about the support of Apple universal links.

What are Universal Links?

When you support universal links, iOS users can tap a link to your website and be seamlessly redirected to your installed app, without going through Safari. If your app isn’t installed, tapping a link to your website opens your website in Safari. For more details, see Support Universal Links.

There’s some special changes that need to be made. Quoting from Apple’s official documentation on Universal Link Support:

Adding support for universal links is easy. There are three steps you need to take:

  1. Create an apple-app-site-association file that contains JSON data about the URLs that your app can handle.

  2. Upload the apple-app-site-association file to your HTTPS web server. You can place the file at the root of your server or in the .well-known subdirectory.

  3. Prepare your app to handle universal links.

The apple-app-site-association data is generated by ownBrander and must be served statically over HTTPS.

You can safely place it in the root folder of your ownCloud installation (e.g., /var/www/owncloud).

What is an apple-app-site-association?

The apple-app-site-association directory is either a subdirectory of your ownCloud URL or of the /.well-known/ directory, and must be served over HTTPS. Data generated by ownBrander is accessed via this subdirectory.

The name "apple-app-site-association" is mandatory.

The file which gets accessed when using this subdirectory is also named apple-app-site-association without any extension. When this subdirectory is accessed, the web server must set the content type to application/json. The physical path used when accessing this directory must be defined in your web server config. In the examples below, the path for the file is /var/www/owncloud/.

When using a physical path to the file inside your ownCloud directory, this file must be present when you upgrade ownCloud, or you chose a different path outside the ownCloud root.

Apache Configuration

To achieve the second requirement, some changes will also need to be made to your Apache configuration. If you configured your installation with the official Admin Manual, your Apache owncloud.conf file must include the following:

# Create an alias for the file (for compatibility reasons):
AliasMatch "^/(\.well-known/)?apple-app-site-association$" "/var/www/owncloud/apple-app-site-association"

<Directory /var/www/owncloud/>
    Options +FollowSymlinks
    AllowOverride All

    # Set the right mime-type for the file:
    <Files apple-app-site-association>
        Header set Content-type "application/json"
    </Files>

    [...]
</Directory>
See the AliasMatch documentation for more details

Also, a new RewriteCond directive, included in the code block below, needs to be included in your .htaccess (or VirtualHost configuration), so that no other redirections will apply to any of these two paths.

RewriteCond %\{REQUEST_URI} !^/(.well-known/)?apple-app-site-association$

NGINX Configuration

For NGINX, the directives to be added are:

location ~* ^/(\.well-known/)?apple-app-site-association {
    # uncomment and update the root configuration line below,
    # in case the path to your ownCloud installation is in a different location.
    # root '/var/www/owncloud';
    default_type 'application/json';
}
If you’re behind a firewall, additional access rules will be required to whitelist the URLs.