Query parameter

Definition

A query parameter is a key-value pair in the portion of a URL that follows a question mark, separated from other pairs by an ampersand, and used to pass data to the resource the URL identifies without changing which resource that is.

Query parameters are how a deep link carries everything that is not the destination: the campaign that produced the click, the click identifier used to match a deferred deep link, and whatever product or content the app should open on. They are also the part of a URL most often corrupted in transit, because the characters that delimit them are the same characters people put inside them.

The grammar, and the characters that break it

The fragment rule catches teams out in the other direction. Everything after # is never sent to the server, so a parameter placed after the fragment marker is invisible to your redirect service, your analytics and your logs, while remaining perfectly readable to JavaScript on the page. A campaign parameter that only appears in client-side reporting and never in server logs has usually landed after a #.

Two behaviours have no standard at all and differ by framework: duplicate keys, where ?id=1&id=2 may yield the first value, the last, or an array; and ordering, which is preserved in the string but not guaranteed by any parser. Do not rely on either. If you need a list, name it explicitly — ?ids=1,2,3 — and parse it yourself.

Where you can match on a query parameter, and where you cannot

This is the part that is genuinely platform-specific, and getting it wrong produces a link that verifies, opens the app, and then lands on the wrong screen.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          {
            "/": "/product/*",
            "?": { "variant": "gift" },
            "comment": "Only gift-variant product URLs open in the app"
          },
          {
            "/": "/search",
            "?": "*",
            "comment": "Any query on /search is claimed"
          },
          {
            "/": "/product/*",
            "?": { "preview": "true" },
            "exclude": true,
            "comment": "Preview links stay in the browser"
          }
        ]
      }
    ]
  }
}

The components format is the only place in either platform's association file where the query is part of the matching decision, and the exclude flag combined with a ? matcher is the sanctioned way to keep a subset of URLs in the browser. Android has no equivalent — an intent filter matches on the path and nothing else, so every query-dependent routing decision on Android has to happen inside your app.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val data: Uri? = intent.data
    // getQueryParameter decodes percent-escapes for you. Do not
    // decode again — "%2520" round-tripped twice becomes "%20",
    // which is the signature of a double-encoded link.
    val productId = data?.getQueryParameter("id")
    val clickId = data?.getQueryParameter("click_id")
    val source = data?.getQueryParameter("utm_source")

    // Duplicate keys: be explicit rather than trusting the default.
    val allIds: List<String> = data?.getQueryParameters("id") ?: emptyList()

    // A missing parameter is not an error. Route to a sensible
    // default screen rather than crashing or showing a blank state.
    route(productId ?: return goHome(), clickId, source)
}

The three ways links lose their parameters

The first is double encoding, which happens whenever a URL is put inside another URL. A redirect target containing its own query must be encoded as a single value, or its & will be read as a delimiter of the outer query and everything after it will be attributed to the wrong parameter.

# WRONG. The nested & terminates the outer "redirect" value, so
# the service sees redirect=https://example.com/p and a stray
# id=42 parameter of its own.
curl -sI "https://links.example.com/l/abc?redirect=https://example.com/p?id=42&utm_source=news"

# RIGHT. The whole nested URL is one encoded value.
curl -sI "https://links.example.com/l/abc?redirect=https%3A%2F%2Fexample.com%2Fp%3Fid%3D42&utm_source=news"

# Follow every hop and print only the Location headers. Any hop
# that drops your click_id is the one to fix.
curl -sIL "https://links.example.com/l/abc?click_id=xyz789&utm_source=news"   | grep -i '^location:'

# Confirm the final URL still carries everything.
curl -s -o /dev/null -w '%{url_effective}\n' -L   "https://links.example.com/l/abc?click_id=xyz789&utm_source=news"

The second is the redirect chain itself. A hop that rewrites the URL without copying the query forward discards it, and this is common in CDN rules, vanity-domain forwarders and marketing platforms that wrap links. The symptom is an install with a destination but no campaign — the routing works and the attribution does not. The curl -sIL invocation above localises the offending hop in one command.

The third is the surface the link is opened in. In-app browsers append their own parameters and occasionally strip others, which both pollutes your reporting and changes the URL your app receives — see deep links in in-app browsers. Treat unknown parameters as ignorable rather than fatal, and never key a cache or a signature on the full query string, because you do not control what gets added to it.