journiq_flutter_sdk 0.1.3

Journiq deep linking, attribution, and analytics SDK for Flutter. Wraps native Android and iOS SDKs via platform channels.

Journiq Flutter SDK

Official Flutter plugin for Journiq — deep linking, deferred deep links, event tracking, and attribution analytics.

Wraps the native Android SDK and iOS SDK via platform channels.

Features

• Deferred Deep Links — Attribute installs to the link that drove them, even across the app store
• Link Management — Create, list, and retrieve short links programmatically
• Event Tracking — Track conversions and custom events with offline queue and automatic batching
• Analytics — Retrieve link click stats and app configuration
• Cross-platform — Single Dart API backed by native SDKs on both Android and iOS

Requirements

Platform	Minimum Version
Android	API 24 (Android 7.0)
iOS	13.0
Flutter	3.3.0+
Dart	3.11.0+

Installation

Add to your pubspec.yaml:

dependencies:
  journiq_flutter_sdk: ^0.1.0

Then run:

flutter pub get

Quick Start

1. Initialize the SDK

import 'package:journiq_flutter_sdk/journiq_flutter_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Journiq.configure(apiKey: 'jq_pub_your_key_here');
  runApp(MyApp());
}

2. Check for Deferred Deep Links

final match = await Journiq.deepLinks.checkDeferredDeepLink();
if (match.matched) {
  // Attribution is stored automatically — events will be linked to this deep link
  Navigator.pushNamed(context, match.deepLinkPath ?? '/');
}

3. Handle Incoming URL Scheme Links

// When the app opens via a URL scheme (e.g., myapp://product/123?jq_link=...)
void handleDeepLink(Uri uri) {
  // Extract and store attribution, returns a clean URI for routing
  final cleanUri = Journiq.deepLinks.handleIncomingLink(uri);
  navigateTo(cleanUri.path);
}

4. Track Events

// deepLinkId is automatically attached from the last attribution source
await Journiq.events.track(
  'PURCHASE',
  metadata: {'amount': '29.99', 'currency': 'USD'},
);

// Or pass explicitly if needed
await Journiq.events.track(
  'PURCHASE',
  deepLinkId: 'specific_link_id',
  metadata: {'amount': '29.99', 'currency': 'USD'},
);

4. Create Links

final link = await Journiq.links.create(LinkCreateRequest(
  webUrl: 'https://example.com/product/123',
  title: 'Cool Product',
  deepLinkPath: '/product/123',
  utmSource: 'app',
  utmMedium: 'share',
));
// Share link.shortUrl

5. User Identity

// After login
await Journiq.setIdentity('user_12345');

// On logout
await Journiq.logout();

API Reference

Journiq

Method	Description
configure({apiKey, baseUrl?})	Initialize the SDK. Call once at app startup.
isInitialized	Whether the SDK has been configured.
setIdentity(userId)	Set user identity for cross-device attribution.
logout()	Remove user identity and clear attribution.
onAppForegrounded()	Trigger event queue flush (call from lifecycle handler).
attributedDeepLinkId	The currently stored deep link ID (read-only).
attributedClickId	The currently stored click ID (read-only).

Journiq.deepLinks

Method	Description
checkDeferredDeepLink()	Check for a deferred deep link match on first open. Auto-stores attribution. Returns MatchResult.
handleIncomingLink(Uri)	Extract attribution from an incoming URL scheme link. Returns clean Uri for routing.

Journiq.links

Method	Description
create(LinkCreateRequest)	Create a new deep link. Returns DeepLink.
list({page, limit})	List deep links with pagination.
get(linkId)	Get a single deep link by ID.

Journiq.events

Method	Description
track(eventName, {deepLinkId?, metadata?})	Track a conversion or custom event. Auto-attaches stored deepLinkId if not provided.
flush()	Force flush queued events immediately.

Journiq.analytics

Method	Description
getLinkStats(linkId)	Get click statistics for a link. Returns LinkStats.
getAppConfig()	Get app configuration. Returns AppConfig.

Platform Setup

1. Configure URL Schemes in Journiq Dashboard

In the Journiq dashboard, navigate to Apps → your app → Edit and configure:

Field	Example	Description
iOS URL Scheme	myapp://{{path}}	Template used to open your iOS app. {{path}} is replaced with the deep link path at redirect time.
Android URL Scheme	myapp://{{path}}	Template used to construct the Android intent URL.
Bundle ID	com.example.myapp	Your iOS app bundle identifier
Package Name	com.example.myapp	Your Android application ID
App Store URL	https://apps.apple.com/app/id123456	Fallback if app not installed (iOS)
Play Store URL	https://play.google.com/store/apps/details?id=com.example.myapp	Fallback if app not installed (Android)

Important: The {{path}} placeholder is required. When a user clicks a link with deepLinkPath: "product/123", the redirect service generates myapp://product/123.

2. iOS Setup

Install native SDK

cd ios && pod install

Register your URL scheme

Add your custom scheme to ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
    <key>CFBundleURLName</key>
    <string>com.example.myapp</string>
  </dict>
</array>

Replace myapp with the scheme portion of your iOS URL Scheme (everything before ://).

3. Android Setup

The SDK dependency is pulled from Maven Central automatically.

Register your URL scheme

Add an intent filter to your main activity in android/app/src/main/AndroidManifest.xml:

<activity
    android:name=".MainActivity"
    android:launchMode="singleTop"
    ...>

    <!-- Existing intent filters ... -->

    <!-- Journiq deep link URL scheme -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" />
    </intent-filter>
</activity>

Replace myapp with the scheme portion of your Android URL Scheme.

4. Handle Incoming Deep Links in Flutter

Use the app_links package to listen for incoming URLs, then parse them with the Journiq SDK:

import 'package:app_links/app_links.dart';
import 'package:journiq_flutter_sdk/journiq_flutter_sdk.dart';

class DeepLinkHandler {
  final _appLinks = AppLinks();

  void init() {
    // Handle link when app is already running
    _appLinks.uriLinkStream.listen((Uri uri) {
      _handleDeepLink(uri);
    });

    // Handle link that launched the app
    _appLinks.getInitialLink().then((uri) {
      if (uri != null) _handleDeepLink(uri);
    });
  }

  void _handleDeepLink(Uri uri) {
    final path = uri.path.replaceFirst('/', ''); // e.g. "product/123"
    final params = uri.queryParameters;           // e.g. {"ref": "campaign1"}

    // Navigate to the appropriate screen
    navigateTo(path, params);
  }
}

Alternatively, if you use go_router, deep links are handled automatically via its route definitions.

How It Works

User clicks Journiq link (e.g. https://links.example.com/abc123)
    │
    ▼
Journiq redirect service detects platform
    │
    ├── iOS mobile ──► Redirects to myapp://product/123
    │                   (falls back to App Store if not installed)
    │
    ├── Android ────► Redirects via intent URL
    │                   intent:#Intent;scheme=myapp;package=com.example.myapp;
    │                   S.browser_fallback_url=<Play Store URL>;end
    │                   (falls back to Play Store if not installed)
    │
    └── Web/Desktop ► Redirects to webUrl

Every click goes through the redirect service, ensuring analytics are always recorded before the app opens.

License

MIT