appurl.json

Let's say you own the domain http://example.com, and you want URLs beginning with http://example.com to point to your native app(s) as well as your website.

You'll need to tell AppURL clients to transform "http" into "custom", or whatever your apps' custom URL scheme is.

To declare your http-to-custom-scheme transformation, you host a file called appurl.json at the root of your domain or subdomain, e.g. example.com/appurl.json.

To open URLs in apps whenever possible, AppURL clients are programmed to consult a (sub)domain's /appurl.json file right before making an HTTP GET request to any path within that subdomain. (AppURL clients should support HTTP caching to reduce the overhead of this step.)

A simple example: Grid6

Grid6 is a tiny example app that lets you make 6x6 pixel art to share with your friends.

Grid6's website is grid6.us. Grid6's native apps use the custom URL scheme grid6.us, following AppURL's recommendation for picking a URL scheme.

Here's what grid6.us/appurl.json looks like:

{
    "name": "Grid6",
    "editions": [
        {
            "platform": "android",
            "downloadUrl": "http://appurl.org/static/pkg/grid6.apk"
        }, {
            "platform": "wp8",
            "downloadUrl": "http://appurl.org/static/pkg/grid6.xap"
        }
    ],
    "email": "contact@appurl.org",
    "developer": "AppURL",
    "homepage": "http://grid6.us/grid.html",
    "iconUrl": "http://appurl.org/static/grid6logo.png",
    "webPrefix": "grid6.us/",
    "nativePrefix": "grid6.us:/",
    "transforms": [
        {
            "description": "This URL specifies the light grid formations.",
            "web": "{state}",
            "native": "{state}",
            "title": "Grid6 Formation"
        }
    ]
}

appurl.json fields

Required
name
The app's human-readable name.
webPrefix
The root URL of your website. Must be in the same origin as the URL hosting your appurl.json. Without a scheme, the http scheme is assumed.
nativePrefix
The root URL of views in your native app. AppURL clients transform webPrefix directly to nativePrefix when attempting to open a URL in an app.
transforms

An array of transformer objects, each with the following fields:

title
Human-readable title of this part of your website and apps' URL-space.
description
Human-readable description of this part of your website and apps' URL-space.
web
A URL transform identifying a set of http paths to transform. May include variables to match in a web URL's path and query string.
native
Defines how native URLs are generated from URLs. May reference variables captured by the web URL transform.

Optional

homepage
Web URL of an informational home page for your apps. Often the same as webPrefix.
iconUrl
Web URL of an icon image for your underlying app product (rather than a platform-specific icon).
editions

An array of objects representing platform-specific editions of your app, each with the following fields:

downloadUrl
Web URL of a page where users can download this edition of your app, e.g. the URL of an iTunes or Google Play app store page.
platform

The platform on which this edition runs, which must be one of the following:

  • "android" (Android)
  • "bb7" (BlackBerry 7)
  • "bb10" (BlackBerry 10)
  • "firefoxos" (Firefox OS)
  • "iphone" (iPhone)
  • "ipad" (iPad)
  • "macos" (Mac OS X)
  • "tizen" (Tizen)
  • "win8modern" (Windows 8 Modern UI)
  • "windows" (Windows EXE)
  • "wp7" (Windows Phone 7)
  • "wp8" (Windows Phone 8)
name (optional)

Human-readable name for this edition.

iconUrl (optional)

Web URL of an icon image specific to this edition of your app.

A tricky example: Spotify

Spotify is a subscription music service with many platform-specific native app editions (see the list at appurl.org/app/open.spotify.com).

The following appurl.json file tells AppURL clients how to launch the right edition of Spotify:

{
    "appName": "Spotify",
    "homepage": "http://spotify.com",
    "iconUrl": "http://d2c87l0yth4zbw.cloudfront.net/i/press/logotype/spotify-logo-96x96-no-tagline.png",

    "webPrefix": "open.spotify.com/",
    "nativePrefix": "spotify:",

    "transforms": [
        {   "title": "Search",
            "description": "Search for artists, albums, or songs.",
            "web": "search/{query}",
            "native": "search:{query}",
            "nativeDelim": ":"
        },
        {   "title": "User",
            "description": "View information about a user.",
            "web": "user/{userid}",
            "native": "user:{userid}",
            "nativeDelim": ":"
        },
        {   "title": "Playlist",
            "description": "View a user's playlist.",
            "web": "user/{userid}/playlist/{playlistid}",
            "native": "user:{userid}:playlist:{playlistid}",
            "nativeDelim": ":"
        }
    ],

    "editions": [
        {
            "platform": "iphone",
            "downloadUrl": "https://itunes.apple.com/us/app/spotify/id324684580?mt=8"
        },
        {
            "platform": "ipad",
            "downloadUrl": "https://itunes.apple.com/us/app/spotify/id324684580?mt=8"
        },
        {
            "platform": "android",
            "downloadUrl": "https://play.google.com/store/apps/details?id=com.spotify.mobile.android.ui"
        },
        {
            "platform": "wp8",
            "downloadUrl": "http://www.windowsphone.com/en-us/store/app/spotify/10f2995d-1f82-4203-b7fa-46ddbd07a6e6"
        },
        {
            "platform": "wp7",
            "downloadUrl": "http://www.windowsphone.com/en-us/store/app/spotify/10f2995d-1f82-4203-b7fa-46ddbd07a6e6"
        },
        {
            "platform": "windows",
            "downloadUrl": "https://www.spotify.com/us/download/windows/"
        },
        {
            "platform": "macosx",
            "downloadUrl": "https://www.spotify.com/us/download/mac/"
        },
        {
            "platform": "bb10",
            "downloadUrl": "http://appworld.blackberry.com/webstore/content/118611/"
        }
    ]
}

Note the use of a nativeDelim field to handle Spotify's use of ':' as a delimiter in its custom-scheme URLs. (The default value of nativeDelim is '/'.)

For more details, see URL transforms.

Submit your app to AppURL.org

AppURL.org maintains a list of AppURL-enabled apps. We hope to provide:

  • A standard reference for linking to apps
  • An efficient API for http-to-custom-scheme URL transformation

Once you create an appurl.json file, you can add your app to AppURL.org.