vela_links 0.2.1

Deep links, deferred deep links, short links, QR codes, link tracking and in-app event analytics (sessions, screens, sign-ups, purchases) for Flutter.

vela_links

Deep links, app links (Android App Links and iOS Universal Links), deferred deep links, short share links, QR codes, link tracking and in-app analytics for Flutter apps, powered by the Vela Links service. A link opens the right screen in your app, even when the app is not installed yet, and you see which links and campaigns bring people who sign up and pay.

Features

• Deep links and app links: open a screen in your app from a web link, a QR code or a custom scheme.
• Deferred deep links: a person who installs the app from a link lands on the right screen at first launch.
• Short share links: create links from inside the app and share them anywhere.
• QR codes: every app gets a trackable QR code, and any link can be shown as a QR code.
• Link tracking: see taps, QR scans, installs and opens per link in the dashboard.
• In-app analytics: active users, sessions, retention, screens, sign-ups, purchases and revenue, credited to the link or campaign that brought each person.

1. Set up your app in the dashboard

Sign up at https://deeplinks.velaapps.in (there is a free plan to try it), add your app (package name, signing fingerprint, Apple Team ID, store links) and copy the SDK key. The dashboard shows the exact Android and iOS settings for your app.

2. Install

flutter pub add vela_links

3. Use

import 'package:vela_links/vela_links.dart';

WidgetsFlutterBinding.ensureInitialized(); // before init, in main()
await VelaLinks.init(
  apiKey: 'vl_...',
  baseUrl: 'https://api.links.velaapps.in',
  slug: 'your-app-slug', // optional: ignore links that belong to another app
);

// A link opened your app (or matched your first launch after install)
VelaLinks.instance.onLink.listen((link) {
  // link.route, link.params, link.deferred
  if (const {'/invite', '/product'}.contains(link.route)) {
    // open that screen; ignore anything you do not expect
  }
});

// Create a short link from inside the app
final url = await VelaLinks.instance.createLink(route: '/invite', params: {'id': '42'});

If a link arrives before you start listening, read it once with VelaLinks.instance.consumePendingLink().

4. See how people use your app

Add the screen observer once, and the SDK reports opens, new installs, sessions and screens by itself:

MaterialApp(
  navigatorObservers: [VelaLinksObserver()], // reports each named screen
  routes: {'/home': ..., '/cart': ...},
)

Then add one line wherever something important happens:

VelaLinks.instance.track('signup');
VelaLinks.instance.track('share', properties: {'channel': 'whatsapp'});
VelaLinks.instance.trackPurchase(499, currency: 'INR', orderId: 'ORD-1001');
VelaLinks.instance.track('tutorial_done', once: true); // once per person, however often it runs

// after sign-in, with your own user id (not an email or phone number):
await VelaLinks.instance.setUserId('user_123');

The dashboard's Behaviour tab then shows active users, new installs, sessions, how many people come back after 1, 7 and 30 days, the most used screens and events, funnels (for example install, sign-up, purchase), revenue, and which link or campaign brought the people who pay. With another router, call VelaLinks.instance.trackScreen('Name') yourself.

• Event names use letters, digits and _ (for example add_to_cart). Properties can hold up to 10 short values; do not put emails or phone numbers in them (the service also replaces anything that looks like one).
• No double counting: every event has its own id, so a resend after a bad network is stored once. The same event repeated within a second counts once, an order with an orderId counts once, and once: true records an event a single time per person.
• One person, many phones: call setUserId after sign-in. What the phone did before signing in, and the person's activity on other phones, is then counted as one person. Only a one-way code of the id is stored. Without it each install is a separate anonymous person.
• Events are sent in the background in small batches, kept and retried if there is no network, and never slow or crash the app.
• VelaLinks.init(trackEvents: false) turns it all off, autoTrack: false turns off only the automatic first_open and session_start. Use VelaLinks.instance.setTrackingEnabled(false) for a privacy setting or consent screen, and resetUser() when a person signs out.

5. Platform setup

• Android: an intent filter for your link domain and your URI scheme (shown in the dashboard), and the Play Install Referrer is read automatically for deferred links.
• iOS: the Associated Domains entitlement applinks:<your link domain> and your URI scheme.

The dashboard's SDK setup tab shows these filled in for your app. In short:

<!-- AndroidManifest.xml, inside your main <activity> -->
<meta-data android:name="flutter_deeplinking_enabled" android:value="false" />
<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:scheme="https" android:host="YOUR-LINK-DOMAIN" android:pathPrefix="/l/"/>
</intent-filter>

On iOS add applinks:YOUR-LINK-DOMAIN under Associated Domains, and set FlutterDeepLinkingEnabled to NO in Info.plist. Turning off Flutter's own deep-link handling stops it from also trying to open /l/... as a route in your Navigator.

Good to know

• The SDK key identifies your app. It can create links and report opens for that one app, and nothing else. It is meant to live in your app, like an analytics key, so it is rate-limited. Once you save your app's package name or bundle id in the dashboard, the key also is refused from an app with a different id. This is a safety net against mistakes, not a lock: the id is sent by the app, so someone who copies the key out of your app could still claim another id. Because the key lives in the app, treat everything reported with it, revenue included, as unverified client data, and verify real purchases on your own server. You can rotate the key in the dashboard at any time.
• baseUrl must be https:// (plain http:// only for localhost or the Android emulator 10.0.2.2). The key is sent only to that address, and redirects are never followed.
• Every network step has a time limit (requestTimeout, default 10 seconds). Any failure, whatever its cause (no network, a bad certificate, a timeout), raises VelaLinksException (background work such as reporting opens never raises) and never stops your app starting. createLink throws an ArgumentError for an empty route or params that are not JSON.
• Treat link.route and link.params as untrusted input, like any deep link: check the route against the screens you allow, and never put secrets in link params.
• Call VelaLinks.instance.dispose() to stop listening. Calling init again replaces the previous instance.
• reportOpens: false turns off open and QR-scan reporting. setTrackingEnabled(false) stops in-app events only; link opens still resolve (a link must be looked up to open) and are counted unless reportOpens: false.
• VelaLinks.instance throws a StateError before init has finished. Where code can run earlier (for example a background handler), use VelaLinks.maybeInstance?.track(...).
• Consent first: with autoTrack: true (the default) first_open and session_start are queued as soon as init runs. If you must ask for consent before anything is collected, call init(trackEvents: false), then setTrackingEnabled(true) once the person agrees: the automatic events start at that moment and are stamped then. Events are queued on the phone until they are sent.
• Events and numbers: property names use letters, digits and _ (up to 30 characters, 10 properties), values are short text, numbers or true/false (lists and maps are skipped). A purchase needs an amount and a three-letter currency (INR if you give none). An orderId that uses other characters than letters, digits and _ . : - is left off, and the purchase is still recorded. Screen names from VelaLinksObserver are the route names: avoid putting ids in them. The app version sent is your versionName with anything other than letters, digits and . _ + - removed.
• Switching accounts: call setUserId after sign-in and resetUser() on sign-out. Both first send what is waiting under the previous identity (a few seconds at most). User ids are 1 to 100 visible ASCII characters with no spaces.
• Backups: on Android (Auto Backup) and iOS (iCloud) the saved values below can be restored to a new phone, which would give two phones one install id. If that matters to you, exclude the vela_links.* shared-preferences keys from backup.
• Adding the SDK to an app that is already installed: the first-launch check also runs once for people who update. On iOS that can show the paste notice once, and on Android an old install referrer could open an old link. Pass matchDeferred: false in that release, and turn it on in the next one.

Privacy: what the SDK sends

• To the Vela Links service, over https: your SDK key, your app's package name or bundle id, the link code that opened the app, and whether it came from a link or a QR code. When you create a link: the route, params and title you give it.
• In-app events (when you use them): the event name, the time, your properties, screen names, purchase amounts, currency and order ids, the app version, the platform, a random install id made on the phone, the user id if you call setUserId (sent as given; the service stores only a one-way hash), and the links that brought the install. The service adds a country from the request and keeps no IP address, and replaces values that look like an email address or a long phone number, but it cannot recognise names or addresses in free text, so do not send personal data. Ask for consent where your law requires it, and describe it in your privacy policy.
• First launch after install (it stops after one success, or after 3 launches that could not reach the service): on Android only the Vela Links token from the Play install referrer is read, and nothing else from it. On iOS the clipboard is read once per try, only to look for a Vela Links token (iOS may show its paste notice); the token is cleared once used, and any other clipboard text is ignored and never sent. If there is no token, the service can still match an iOS install to a recent tap using a one-way hash of the network address (it never stores the address itself).
• The SDK uses no advertising id (IDFA/GAID), no device id, no location, and has no native code of its own. It stores these on the device (shared preferences, keys starting vela_links.): the random install id; the queue of events not yet sent (your event names and properties, in plain text, for up to 7 days); the links that brought the install and last opened the app; your user id if you set one; the names of once-only events already sent; whether first-open was reported and when the app was last active; whether tracking is switched off; and, for the first-launch check, whether it finished and how many tries it made.
• Include this in your app's privacy policy and in the App Store and Play Console data forms.

Support and security

Questions: [e-mail]. To report a security problem privately, see SECURITY.md.

License

MIT. See LICENSE.