Documentation

Capacitor quickstart

From nothing to a working deep link, in five lines and about ten minutes. Written for somebody who has never used us.

This takes about ten minutes if your app is already on the App Store, and about twenty if it is not. You need a Mac, an Apple Developer account, and your app’s bundle identifier.

One package of ours, plus one Capacitor plugin you may already have. @quberoute/sdk is plain TypeScript with no dependencies of its own — no native module, no pod install for it, nothing to rebuild natively when you upgrade it.

It reads incoming links through @capacitor/app, which is Capacitor’s own plugin for launch URLs and which most Ionic apps already depend on. If yours does not, install it with the line below. The SDK will tell you if it is missing — through onError, naming the fix — rather than opening your app and quietly never firing onLink.

1. Create an app, and get your key

Sign in, create an app, and open its SDK setup page. That page shows the four values in this guide — your link host, your publishable key, your bundle identifier and your Team ID — already filled in, so you can copy rather than adapt.

Use a publishable key, which begins qr_live_ or qr_test_. It is compiled into your app and shipped to the public, so it is designed to be public: it can report installs, resolve your own links and record events, and it can do nothing else. Never ship a secret key (qr_sk_…) inside an app — the SDK will refuse it and tell you why.

Start in test. Test links, keys and installs are completely separate from live and are never billed.

2. Install the package

Ours, and Capacitor's own launch-URL pluginbash

npm install @quberoute/sdk @capacitor/app
npx cap sync

3. Add the associated domain

This is the part iOS requires and it is the part that most often goes wrong. In Xcode, select your target, then Signing & Capabilities, then + Capability → Associated Domains, and add one entry using your own link host from the SDK setup page:

Associated Domains — your link host, from the dashboardtext

applinks:YOUR-KEY.links.quberoute.com

Your Apple Developer account must have Associated Domains enabled for this App ID, and the provisioning profile must be regenerated afterwards. Xcode usually does this for you when automatic signing is on. If it does not, that is the first thing to check when nothing works.

While you are testing, add ?mode=developer to the associated domain entry — see the Apple caching delay, which is the single commonest reason a correct setup appears broken.

4. Five lines

In whichever file runs once when your app starts — app.component.ts in an Ionic Angular app, App.tsx in Ionic React:

The whole integrationtypescript

import { QubeRoute } from '@quberoute/sdk'

const qr = await QubeRoute.init({ key: 'qr_test_YOUR_KEY' })

qr.onLink(link => {
  // link.data is whatever you put in the link when you created it.
  this.router.navigateByUrl(link.data.path as string)
})

That is the integration. init never throws and never waits for the network — it resolves as soon as it has read local storage, and the link arrives at onLink a moment later.

Register onLink straight after init. On a cold start the link is often resolved before your handler exists; the SDK holds it and delivers it the instant you register, so the order above is safe. If you register it three screens later, it still arrives — but your user has already seen the wrong screen.

5. Track what matters

Attributed back to the link that produced the installtypescript

await qr.track('purchase', { value: 4.99, currency: 'GBP' })

Write the value as a person would — 4.99, not 499. The currency is required whenever there is a value. track never throws — but it does await the send, up to the three-second timeout, so do not put it in front of something a person is waiting for. If the device is offline the event is queued and goes out with the next one, up to a hundred events.

6. Test it

Create a link in the dashboard, in test, with some deep link data. Then:

Put the link in a note or a message on the device — not in Safari’s address bar. Typing a universal link into the address bar does not open the app; that is iOS behaviour and it catches everybody.
Tap it. Your app should open and onLink should fire.
If Safari opens instead, go to when it does not work. Do not guess — the list there is ordered by how often each cause is the real one.

What happens when somebody does not have the app

They go to the App Store, install, and open it. iOS tells your freshly installed app nothing about the link that sent them there — so we match the install against recent clicks instead, and onLink fires with source: 'deferred' and a confidence below 1.

This is genuinely imperfect and we would rather you knew the numbers before you build anything on them: deferred matching, and how well it works.

Before you go live

Swap the test key for the live one and add the live associated domain. They are different hosts: YOUR-KEY and YOUR-KEY-test.
Remove ?mode=developer from the associated domain.
Fill in your privacy manifest — what to declare. A pure JavaScript package ships no manifest of its own, so this is yours to complete.

Next: how well deferred matching works.

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