URL Transforms

---

URL transforms tell AppURL clients how to transform http URLs into custom-scheme URLs.

Your appurl.json's web, native and optional nativeDelim fields specify URL transforms for your app.

Examples

Oranges

Oranges is a realtime hyperlocal skeuomorphic orange-buying app.

It has a website at oranges.example.com, and multiple native apps which all handle the URL scheme oranges.example.com (following AppURL's recommendation for picking a URL scheme).

Both the Oranges website and the Oranges native apps can look up orders.

Oranges' website has URLs like this:

http://oranges.example.com/u/JohnSmith?oid=123#shipping

Oranges' apps have URLs like this:

oranges.example.com:JohnSmith/order/123#shipping

So Oranges' appurl.json file specifies a URL transform like this:

{
    "webPrefix": "oranges.example.com/",
    "nativePrefix": "oranges.example.com:",
    "transforms": [{
        "web": "u/{user}?oid={id}",
        "native": "{user}/order/{id}"
    }]
}

Grapes

Grapes is a microblogging platform for grape-related topics.

Grapes' website has URLs like this:

http://grapes.example.com/concord.html?u=Jenny&c=red&x=5

Grapes' apps have URLs like this:

grapes.example.com:pages/concord/Jenny?col=red

So Grapes' appurl.json file specifies a URL transform like this:

{
    "webPrefix": "grapes.example.com/",
    "nativePrefix": "grapes.example.com:pages/",
    "transforms": [{
        "web": "{page}.html?c={color}&u={user}",
        "native": "{page}/{user}?col={color}"
    }]
}

How it works

Let's see how the URL transform works in our Grapes example.

We start with a web URL:

http://grapes.example.com/concord.html?u=Jenny&c=red&x=5

Our web URL has a web prefix that matches the webPrefix field in our URL transform spec. If no scheme is given in the webPrefix, we assume http:

grapes.example.com/

The rest of the web URL is the web tail:

concord.html?u=Jenny&c=red

To transform the web URL, we start by replacing the web prefix with the specified native prefix:

grapes.example.com:pages/

Then we scan the web tail and assign values to the page, color and user variables specified with curly braces in the web field:

page = "concord"

color = "red"

user = "Jenny"

Finally, we substitute the variable values into the specified native tail pattern and append it to our native prefix:

grapes.example.com:pages/concord/Jenny?col=red

URL segments

When the web pattern in a URL transform attempts to match a URL, it goes segment by segment.

URLs have two kinds of segments:

1. Path segments are delimited by the "/" character (unless a nativeDelim is specified). The URLs in the examples contain the path segments u, JohnSmith, order, concord.html, concord and Jenny.
2. Query segments come after the "?" character and are delimited by "&" characters. The URLs in the examples contain the query segments oid=123, u=Jenny, c=red, x=5 and col=red.

To match, all the path segments in a URL must match the path segments in a web pattern, one-for-one and in the same order.

Query segments in a URL match the query segments in a web pattern. Unmatched segments from the URL are kept, unmatched segments from the pattern are ignored. Query arguments that contain an "=" character are matched by keyword, and their order doesn't matter. Query arguments without a "=" character are matched in order.

Variables

The variables in a web pattern are the segments or parts of segments enclosed in {curly braces}.

Variable matching happens on a segment-by-segment basis. A variable in a web pattern attempts to match precisely the substring of its corresponding URL segment that makes the two segments match.

In the Oranges example, the {user} variable in the web pattern matched JohnSmith in the web URL.

In the Grapes example, the {page} variable in the web pattern matched concord, the {color} variable matched red and the {user} variable matched Jenny in the web URL. (Notice that ordering of query segments didn't matter, and nothing in the web pattern needed to match x=5 in the web URL.)

Up to one variable per segment is allowed. If a query segment contains an "=" character, any variable in that segment has to go after the "=".

URL fragments

A fragment is the substring of a URL that comes after the "#" character, if present.

URL transforms apply to the part of the URL before the fragment and leave the fragment untransformed, as you can see in the Oranges example.

The nativeDelim Field

Most native URLs use the '/' character as a path segment delimiter, just like web URLs do. If your app uses a different delimiter, you can use the optional nativeDelim field in your appurl.json to specify it.

For example, Spotify uses ':' to delimit segments in its native URLs. So Spotify's appurl.json includes "nativeDelim": ":".