vela_links 0.2.3

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, 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.

Platforms: Android and iOS. Needs: Flutter 3.22 or newer.

What you get

• Deep links and deferred deep links: a web link, a QR code or a custom scheme opens a screen in your app. A person who installs from a link lands on that screen at first launch.
• Short share links and QR codes: create links from inside the app. Every app gets a trackable QR code.
• Link analytics: 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.

Quick start

1. Add your app in the dashboard. Sign up at deeplinks.velaapps.in (there is a free plan), add your app (package name, signing fingerprint, Apple Team ID, store links) and copy the SDK key. Its SDK setup tab shows the exact Android and iOS settings for your app, and Verify setup checks them for you.

2. Install.

flutter pub add vela_links

3. Start it and listen for links.

import 'package:vela_links/vela_links.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  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
    }
  });

  runApp(const MyApp());
}

Create a short link from inside the app, to share anywhere:

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:

MaterialApp(
  navigatorObservers: [VelaLinksObserver()], // reports each named screen
  routes: {/* your named routes */},
)

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

// 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 shows active users, new installs, sessions, how many people come back after 1, 7 and 30 days, your 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.

Platform setup

The dashboard fills these 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>
<!-- plus a second intent-filter like it with <data android:scheme="YOUR-URI-SCHEME"/> for your custom scheme -->

• iOS: add applinks:YOUR-LINK-DOMAIN under Associated Domains, add your URI scheme as a URL type, 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.
• Android reads the Play Install Referrer by itself for deferred links.

Good to know

• The SDK key identifies your app and can create links and report opens for it, nothing else. It lives in your app like an analytics key, so it is rate-limited, and you can rotate it in the dashboard at any time.
• Revenue is client-reported. Anyone who copies the key out of your app could send fake events, so verify real purchases on your own server. The package name or bundle id check only guards against mistakes, because the app sends the id itself.
• 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.
• Event rules: names use letters, digits and _. Up to 10 properties with short text, number or true/false values. A purchase needs an amount and a three-letter currency (INR if you give none). An orderId with unsupported characters is left off and the purchase is still recorded. Every event has its own id, so a resend after a bad network is stored once, and the same event repeated within a second counts once.
• One person, many phones: call setUserId after sign-in and resetUser() on sign-out. Both first send what is waiting under the previous identity. User ids are 1 to 100 visible ASCII characters with no spaces. Without one, each install is its own anonymous person.
• Consent first: by default first_open and session_start are queued as soon as init runs. If you must ask first, call init(trackEvents: false), then setTrackingEnabled(true) once the person agrees. setTrackingEnabled(false) stops in-app events only: link opens still resolve, and are counted unless you pass reportOpens: false. autoTrack: false turns off only the automatic events.
• 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.
• Errors: every network step has a time limit (requestTimeout, 10 seconds). A failure raises VelaLinksException (background work never raises) and never stops your app starting. VelaLinks.instance throws a StateError before init has finished, so use VelaLinks.maybeInstance?.track(...) where code can run earlier. baseUrl must be https:// (plain http:// only for localhost or the Android emulator 10.0.2.2), and redirects are never followed.

Privacy: what the SDK sends and stores

Sent to the Vela Links service, over https

• Always: 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.
• With in-app events: 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 (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. It 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.
• 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. 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).

Stored on the phone (shared preferences, keys starting vela_links.): the random install id; the events not yet sent (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 whether the first-launch check finished. Android Auto Backup and iCloud can restore these onto a new phone, which would give two phones one install id. If that matters to you, exclude the vela_links.* keys from backup.

Not used: no advertising id (IDFA/GAID), no device id, no location, and no native code of its own.

Please describe this in your app's privacy policy, ask for consent where your law requires it, and use it to fill 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.