Documentation

Quickstart

Install the SDK and handle an incoming link on Capacitor, Cordova, React Native, Flutter or the web. The shared path is identical; only the framework step differs.

This gets you from nothing to a link opening your app, on whichever framework you use. Everything on this page works today.

The first four steps are the same on every platform. Step 5 is the only framework-specific part, and step 6 applies only if you are shipping to an app store — a web integration is finished at step 5.

1. Create an account

Sign up at /signup with an email address and a password of at least twelve characters. There are no rules about capitals or symbols — length and not being on a list of known passwords is what is asked for, which is current NCSC and NIST guidance.

You will be sent a confirmation link. Opening it confirms the address and sends you to sign in; it does not sign you in by itself, because a link that arrives by email and hands out a session is a session available to anybody who can read the inbox.

2. Add an app

An app is one mobile application. Creating one allocates it a five character host of its own, permanently:

Your app's link hosthttp

71k8c.qbrt.app

That host is never reused, even if you delete the app. Links printed on physical things outlive the accounts that made them, so recycling a host would mean somebody else’s links resolving into your app.

3. Create an API key

Keys live on the app’s API keys page. Check the live/test switch in the bar at the top first: a key belongs to one app and one environment and cannot be moved between them.

The key is shown once. We store a hash and a short display prefix, so there is no mechanism by which we could show it again — which is what the rotate button is for.

Your first authenticated callbash

curl https://app.quberoute.com/api/v1/app \
  -H "Authorization: Bearer qr_sk_test_YOUR_KEY"

{
  "app": {
    "id": "0d6f1a3c-2f4b-4c8e-9a1d-7b2c6e5f0a11",
    "name": "Your app",
    "subdomainKey": "71k8c",
    "linkHost": "71k8c.qbrt.app"
  },
  "environment": "test"
}

If this returns your app, everything is wired up correctly.

4. Install the SDK and handle the incoming link

The same three lines everywhere the SDK runs: install it, initialise it with your key, and receive the link. Only the fourth step — how the framework hands a URL to JavaScript — differs, and that is the section after this one.

Installbash

npm install @quberoute/sdk

Version 0.2.2, published on npm under the MIT licence, with no dependencies and no peer dependencies.

The shared path — identical on every platformtypescript

import { QubeRoute } from '@quberoute/sdk'

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

qr.onLink(link => {
  // link.params carries whatever you put on the link.
  console.log(link.alias, link.params)
})

5. The framework-specific step

Pick yours. Everything above is unchanged; this is only about how the URL reaches the SDK.

Capacitor

Install @capacitor/app and run npx cap sync. The SDK reads launch URLs through that plugin and needs nothing else from you. This is the path that has had the most use.

Cordova

The SDK detects the cordova global and listens on both routes Cordova uses: the handleOpenURL global, and the universalLinks plugin’s subscription if you have it installed.

Cold start needs one line. Cordova can call handleOpenURL before your code has called QubeRoute.init, so the URL arrives with nothing listening. Queue it and the SDK picks it up:

Cordova — in index.html, before your bundlexml

<script>
  window.QubeRoutePendingUrls = [];
  function handleOpenURL(url) { window.QubeRoutePendingUrls.push(url); }
</script>

Without this a link that cold-starts the app is lost. With it, nothing is.

React Native

React Native has its own Linking API and the SDK uses it rather than replacing it. Hand it over once, before init:

React Nativetypescript

import { Linking } from 'react-native'
import { QubeRoute } from '@quberoute/sdk'

;(globalThis as Record<string, unknown>).QubeRouteLinking = Linking

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

Flutter

There is no Dart package. Saying so plainly is more use than leaving Flutter off the list: the API is plain REST and a Flutter app can use it directly with package:http and app_links or uni_links for the incoming URL.

Take the URL your link handler gives you and POST it to /api/v1/sdk/resolve with your publishable key. The response is the same link object the SDK delivers to onLink. The API reference has the shape.

What you give up by not having a package is the deferred-matching handshake, which the SDK does for you on first launch. Everything about a link that opens an app you already have is a single call.

Web

The SDK runs in a browser. On a page load it reads the current URL, so a link opened on the web resolves and its parameters reach onLink exactly as they do in an app. track() works the same way.

Two honest limits. A web page does not resume, so there is no second link event — a new link is a new page load. And there is no install on the web, so nothing here crosses the install boundary: a visit in a browser is not joined to a later app install.

6. Platform setup

Only needed for the app stores. A web integration is finished at step 5.

iOS

You will need a Mac, an Apple Developer account and your bundle identifier. These used to sit at the top of this page, ahead of every Android and web developer who did not need them.

On the app’s iOS settings page:

Bundle identifier — reverse-DNS, such as com.example.retail. In Xcode under Signing & Capabilities.
Apple Team ID — exactly ten letters and digits. Top right of the Apple Developer portal, under Membership details.
URI scheme and App Store details — optional.

Two organisations claiming the same bundle identifier is allowed — it happens legitimately, for example when an agency and a client both have an account — but it is recorded in the audit log, because it is also what impersonation would look like.

Then read iOS universal links setup for the association file and the entitlement.

Android

No Mac and no paid developer account. You need your applicationId and the SHA-256 fingerprints of your signing keys — Android setup covers both, and why the fingerprints are plural.

7. What comes next

Testing it before you ship shows how to prove the whole path without an App Store build, and deferred matching explains what happens when somebody taps a link without the app installed, including how well it 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