📊 clickstream_analytics_plus #

A modern Flutter plugin for AWS Clickstream Analytics
Supports Android, iOS, macOS, and Web, with a federated architecture for future platform extensions (Linux, Windows).

🧠 Overview #

clickstream_analytics_plus is a cross-platform Flutter plugin that makes it easy to collect and send analytics events to AWS Clickstream Analytics on AWS.

It provides a unified Flutter interface wrapping the official native SDKs:

• Android → AWS Clickstream Android SDK
• iOS / macOS → AWS Clickstream Swift SDK
• Web → AWS Clickstream Web SDK

This plugin enhances the original SDKs with:

• a Dart-first API (fully typed, null-safe)
• session lifecycle integration (pause/resume via AppLifecycleObserver)
• multi-tab sample demo app
• macOS and Web support, which are not available in the official plugin

🍏 iOS / macOS Integration Guide #

Why SPM Is Required #

This plugin depends on the AWS Clickstream Swift SDK, which in turn depends on AWS Amplify v2 for Swift. Both are distributed exclusively via Swift Package Manager (SPM) — they are not available on CocoaPods or Carthage.

The .podspec files included in this plugin are stubs that satisfy Flutter's CocoaPods tooling. They do not pull in the Clickstream native SDK — that resolution happens through the Package.swift manifests.

Dual Integration: CocoaPods + SPM Side by Side #

Most existing Flutter apps use CocoaPods for other dependencies (Firebase, Google Maps, etc.). Flutter 3.24+ supports CocoaPods and SPM running side by side in the same project. This is the expected setup — you do not need to migrate away from CocoaPods.

When both are active:

• CocoaPods continues to manage pods listed in your Podfile (including the Flutter engine).
• SPM handles packages declared via Package.swift manifests in plugins (like this plugin's Clickstream SDK dependency).
• Xcode resolves both dependency graphs independently — they coexist without conflict.

Setup for Existing CocoaPods Projects #

Prerequisites: Flutter 3.24+, Xcode 15+, Swift 5.9+.

Step 1 — Enable SPM in Flutter:

flutter config --enable-swift-package-manager

Verify with flutter config — you should see enable-swift-package-manager: true.

Step 2 — Add the plugin and rebuild:

flutter pub add clickstream_analytics_plus
flutter build ios   # or: flutter build macos

On the first build after enabling SPM, Flutter will:

1. Keep your existing Podfile and Pods/ directory untouched.
2. Generate a FlutterGeneratedPluginSwiftPackage inside ios/Flutter/ephemeral/Packages/.
3. Add an SPM package reference in the Xcode project, which pulls the Clickstream SDK and Amplify via SPM.
4. Create or update Package.resolved at the workspace level with pinned SPM dependency versions.

Your Podfile stays the same. No manual changes needed.

Step 3 — Commit the project changes:

After the first successful build, you'll see changes in:

ios/Runner.xcodeproj/project.pbxproj   # Now references the SPM package
ios/Flutter/Debug.xcconfig              # CocoaPods include added
ios/Flutter/Release.xcconfig            # CocoaPods include added

Note: Package.resolved files are generated lock files. You can gitignore them (this plugin does) or commit them for reproducible builds — either approach works.

New Projects (SPM-Only) #

For greenfield projects, you can skip CocoaPods entirely:

flutter config --enable-swift-package-manager
flutter create --platforms=ios,macos my_app
cd my_app
flutter pub add clickstream_analytics_plus
flutter run

Deployment Targets #

The minimum deployment targets required by the Clickstream Swift SDK:

If your project sets a lower target, you'll get build errors. Update accordingly:

• Podfile (iOS): platform :ios, '13.0'
• Podfile (macOS): platform :osx, '10.15'
• Xcode: Set "Minimum Deployments" in the Runner target's General tab.

CI/CD Considerations #

Xcode version: Use Xcode 15+ (SPM resolution requires Swift 5.9+).

SPM package resolution: The first build downloads the full SPM dependency graph (Amplify, AWS SDK for Swift, Starscream, SQLite.swift, etc.) which can take 2–5 minutes. Cache the SPM SourcePackages directory to speed up subsequent builds.

GitHub Actions:

- name: Cache CocoaPods
  uses: actions/cache@v4
  with:
    path: ios/Pods
    key: pods-${{ hashFiles('ios/Podfile.lock') }}

- name: Cache SPM packages
  uses: actions/cache@v4
  with:
    path: build/ios/SourcePackages
    key: spm-${{ hashFiles('**/Package.resolved') }}

Codemagic:

Codemagic supports two configuration approaches — the Workflow Editor (UI-based) and codemagic.yaml (code-based). Both work with this plugin's dual CocoaPods + SPM setup.

Option A — Workflow Editor (UI):

The Workflow Editor provides script hook points where you can inject custom scripts (click the + between sections). For this plugin, add a Post-clone script to enable SPM before the build runs:

The available hook points in order are: post-clone → pre-test → post-test → pre-build → post-build → pre-publish → post-publish.

In the Build section of the Workflow Editor, ensure:

• Xcode version is set to 15.0+
• CocoaPods is left enabled (Codemagic handles pod install automatically)

Codemagic caches CocoaPods by default. For SPM caching in the Workflow Editor, add these under Environment > Custom cache paths:

$HOME/Library/Caches/org.swift.swiftpm
$CM_BUILD_DIR/build/ios/SourcePackages

Option B — codemagic.yaml:

For full control, use a YAML configuration:

workflows:
  ios-workflow:
    environment:
      xcode: 15.4  # must be 15+
      flutter: stable
    cache:
      cache_paths:
        - $HOME/Library/Caches/org.swift.swiftpm  # Global SPM cache
        - $CM_BUILD_DIR/build/ios/SourcePackages   # Project-level SPM packages
    scripts:
      - name: Enable SPM
        script: flutter config --enable-swift-package-manager
      - name: Get dependencies
        script: flutter pub get
      - name: Build iOS
        script: flutter build ios --no-codesign

Tip: Codemagic's macOS build machines include full Xcode installations, so xcode-select issues are rare. If SPM resolution is slow on the first run, the cache paths above will speed up subsequent builds.

Common CI gotchas:

Troubleshooting #

"Unable to find module dependency: 'Clickstream'"

SPM is not enabled or did not resolve the Clickstream SDK.

1. Verify: flutter config should show enable-swift-package-manager: true.
2. Clean rebuild: flutter clean && flutter pub get && flutter build ios.
3. Open ios/Runner.xcworkspace in Xcode → File > Packages — you should see clickstream-analytics-on-aws-swift-sdk listed.

Deployment target too low

The package product 'Clickstream' requires minimum platform version 13.0

Set iOS to 13.0+ / macOS to 10.15+ in your Podfile and Xcode project settings. Run pod install, then rebuild.

Package.resolved merge conflicts

Accept either version, then run flutter build ios to let SPM re-resolve.

"Package resolution failed" or "cannot clone repository"

SPM needs network access to clone repos from GitHub. Check network/proxy settings. Behind a corporate proxy:

git config --global http.proxy http://your-proxy:port

Build fails after upgrading Flutter or Xcode

Full clean rebuild:

flutter clean
rm -rf ios/Pods ios/Podfile.lock
rm -rf build/
flutter pub get
cd ios && pod install && cd ..
flutter build ios

For more details, see the Flutter SPM guide for app developers.

🧩 Installation #

Add to your Flutter project:

flutter pub add clickstream_analytics_plus

Then rebuild your app:

flutter run

🚀 Quick Start #

import 'package:clickstream_analytics_plus/clickstream_analytics_plus.dart';

final analytics = ClickstreamAnalyticsPlus();

Future<void> main() async {
  final ok = await analytics.initialize(
    appId: 'yourAppId',
    endpoint: 'https://example.com/collect',
    logEvents: true,
    compressEvents: true,
    sessionTimeoutMs: 1800000,
    sendEventIntervalMs: 10000,
    initialGlobalAttributes: {'platform': 'flutter'},
  );

  if (ok) {
    await analytics.setUserId('user_123');
    await analytics.recordEvent('app_start', attributes: {'screen': 'home'});
  }
}

🎯 Core API #

Initialization #

await analytics.initialize(
  appId: 'myAppId',
  endpoint: 'https://your-endpoint.com/collect',
  logEvents: true,
  compressEvents: true,
  sessionTimeoutMs: 1800000,
  sendEventIntervalMs: 10000,
  initialGlobalAttributes: {'platform': 'flutter', 'build': 'demo'},
);

Record Event #

await analytics.recordEvent(
  'button_click',
  attributes: {
    'screen': 'home',
    'timestamp': DateTime.now().toIso8601String(),
  },
);

Set User ID and Attributes #

await analytics.setUserId('user123');
await analytics.setUserAttributes({'plan': 'pro', 'region': 'US'});

Manage Global Attributes #

await analytics.setGlobalAttributes({'platform': 'flutter'});
await analytics.removeGlobalAttribute('platform');

Flush Events #

await analytics.flushEvents();

Check SDK Version #

final version = await analytics.getSdkVersion();

🧱 Platform Coverage #

⚠️ Some methods are safely stubbed where the native SDK does not expose direct APIs.

💡 Example App #

A full-featured multi-tab example app is included:

• Home Tab → Initialize & show SDK version
• Events Tab → Record and flush events
• User Tab → Update user/global attributes

Run it with:

cd example
flutter run

🧰 Development #

To build and format:

flutter pub get
dart format .
flutter analyze

To test Android:

cd example && flutter build apk

To test iOS/macOS:

cd example && flutter build ios

To test Web:

flutter run -d chrome

🛠 Architecture #

This plugin follows the Flutter Federated Plugin pattern, with separate implementations for:

• clickstream_analytics_plus_android
• clickstream_analytics_plus_ios
• clickstream_analytics_plus_macos
• clickstream_analytics_plus_web

Future community contributions can extend this to Windows and Linux.

🔍 Comparison with Official AWS Plugin #

✅ clickstream_analytics_plus focuses on multi-platform support, developer flexibility, and an idiomatic Flutter API.
It is not an official AWS package but a community-maintained federated extension built atop the same SDKs.

⚖️ License #

Licensed under the Apache 2.0 License.

🙌 Credits #

This project is inspired by and wraps the official
AWS Clickstream Analytics SDKs
for Android, Swift, and Web.

Maintained independently by the Flutter community.