Documentation

Clipboard matching

Exact deferred attribution, at the cost of a visible paste banner on iOS. What your users see, and what it is worth.

The trade, in one paragraph

Deferred matching without the clipboard is a guess: we compare coarse signals and get it right about four times in ten. Clipboard matching does not guess. We put a random token on the clipboard when somebody taps your link, your app reads it back on first launch, and when it is there, that is an exact match.

The cost is that iOS asks your user, and your user can say no. On iOS 16 and later, an app reading the clipboard programmatically causes the system to put up a prompt naming both apps — “Allow ‘Your App’ to paste from ‘Safari’?” — with Allow and Don’t Allow. It happens once, on the first launch after installing, and never again for that install.

An earlier version of this page described the older, passive “Pasted from Safari” banner and said your user could not turn it off. That was the iOS 14 and 15 behaviour, and it understated this in the direction that sells the feature. On iOS 16 and later it is a decision your user makes, in a modal, before anything is read. Refusing costs nothing: the SDK reports that it looked and found nothing, and deferred matching carries on without it.

That is the whole decision. Some teams take it happily for accurate affiliate payouts; others will not put an unexplained banner in front of a brand-new user. It is off by default, and you can turn it on or off at any time in the app’s settings — the change takes effect on the next click, and nothing needs rebuilding or resubmitting.

The part we have not been able to test

We have not run this on a physical iPhone, and there is a specific reason it might not work there at all. WebKit requires a recent user gesture before a page may write to the clipboard, and the handoff page is reached by a tap on a link somewhere else rather than by a tap on itself — so the write may be refused. Every other browser we can reason about permits it.

If that is what happens on iOS, clipboard matching writes nothing, the SDK finds nothing, and deferred matching falls back to the ordinary measured guess. Nothing breaks and nobody is misattributed — but the feature would be doing nothing while still costing your users one extra page load on the way to the App Store. That is why it is off by default and why this paragraph is here rather than in a footnote.

It will be confirmed on a real device before it is recommended. Until then, treat the numbers below as what this can deliver rather than as what it has been measured delivering.

What your user actually sees

They tap your link. Safari opens for a moment.
Instead of going straight to the App Store, they see a small page saying “Taking you to the App Store” for a fraction of a second, then the App Store opens.
They install your app as normal, and open it.
iOS asks them whether your app may paste from Safari, naming both apps. They tap Allow or Don’t Allow. Either answer is fine; only one of them gives you an exact match.

Steps 2 and 4 are the cost. Step 2 is ours and it is brief; step 4 is the operating system’s and we cannot suppress it or pre-empt it. If either is unacceptable to you, leave this off — everything else about the product works exactly the same.

What it is worth, in numbers

Attribution accuracy by method, and what each costs the user
How the install was matched	Accuracy	Visible to your user
Your app was opened by the link	Exact	Nothing
Clipboard token	Exact	An interstitial for a fraction of a second, and one paste banner
Coarse signals (the default)	40.6% matched, 3.41% of those wrong	Nothing

Those coarse-signal figures, and the much worse ones for a shared office network, are on the deferred matching page. If your affiliates share a network, clipboard matching is the answer to the problem described there.

Clipboard matching does not replace the other methods, it joins them. An install is attributed by whichever knows the answer first: the link that opened your app, then the clipboard token, then coarse signals. Turning the clipboard on costs you nothing in cases where it was not needed.

What is on the clipboard

A random string, and nothing else:

A whole clipboard tokentext

qr1.4f9a2c7e13b06d85af2e91c4d7b30e6a

It carries no destination, no app name, no campaign and nothing derived from any of them — it is a lookup key into a row only we can read. If one of your users taps a link and then pastes into a message before opening your app, what they send is that meaningless string.

It is single use and expires after 60 minutes, the same window as coarse-signal matching. Once it has attributed an install it can never attribute another, and expired tokens are deleted rather than ignored.

What we do with a clipboard that is not ours

Nothing. It never leaves the device. The SDK checks what it read against the shape above on the phone, and anything that does not match is discarded there — not sent to us, not written to a log, not passed to your error handler.

That matters because a clipboard is where people keep passwords, card numbers and private messages. The one thing we will accept from it is a string we put there ourselves.

Turning it on

Your app → Settings → Clipboard matching → tick and save.
That is all. It takes effect on the next click; no rebuild, no resubmission, and the SDK needs no change.

Turning it off is the same switch. Tokens already on somebody’s clipboard simply stop being written and expire on their own.

Refusing it from the code as well

If you would rather your app never touched the clipboard whatever the dashboard says — a reasonable position for a team with its own privacy commitments — the SDK takes a veto:

The app refuses, regardless of the settingtypescript

const qr = await QubeRoute.init({
  key: 'qr_live_YOUR_KEY',
  clipboardMatching: false,
})

With that set, the SDK never reads the clipboard, no banner can ever appear, and deferred attribution falls back to coarse signals.

Android

Not needed, and not used. Google provides the Play Install Referrer, which tells a freshly installed app exactly which link produced it — with no clipboard, no permission and no banner. An Android install takes that path instead, and the server does not even ask an Android device for the clipboard, so switching this setting on has no effect there at all.

How Android setup works.

Next: when it does not work.

Ask the documentation

It answers from these pages only, and links what it used. If the answer is not here it says so rather than guessing — then email [email protected].

← All documentation