Metriqus SDK for Flutter

This is the Metriqus SDK for Flutter. Metriqus is a data analytic platform for web and mobile.

Compatibility

  • This SDK supports iOS 12 or later and Android API level 21 (Lollipop) or later.
  • The SDK is compatible with Flutter 3.0.0 or later.

Installation

To install the Metriqus SDK, choose one of the following methods.

1. Install via pub.dev

To use the Metriqus SDK in your Flutter app, add it to your pubspec.yaml:

dependencies:
  metriqus_flutter_sdk: ^1.0.0

Then run:

flutter pub get

Integrate the SDK

The Metriqus SDK initialization is handled in your main.dart file. To set up the Metriqus SDK:

import 'package:metriqus_flutter_sdk/metriqus_flutter_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Setup SDK listeners
  Metriqus.onLog.listen((logMessage) {
    print('🔵 Metriqus Log: $logMessage');
  });

  Metriqus.onSdkInitialize.listen((isInitialized) {
    print('🔧 SDK Initialization: ${isInitialized ? 'SUCCESS' : 'FAILED'}');
  });

  // Initialize SDK
  final settings = MetriqusSettings(
    clientKey: 'your_client_key',
    clientSecret: 'your_client_secret',
    environment: Environment.sandbox,
    logLevel: LogLevel.verbose,
  );

  Metriqus.initSdk(settings);
  runApp(MyApp());
}

To set up the Metriqus SDK, enter the following information:

  • Client Key: Check your credentials to find your client key.
  • Client Secret: Check your credentials to find your client secret.
  • Environment:
    • Choose Environment.sandbox if you are testing your app and want to send test data. You need to enable sandbox mode in the dashboard to see test data.
    • Choose Environment.production when you have finished testing and are ready to release your app.
  • Log Level: This controls what logs you receive.

The Metriqus SDK starts automatically when initSdk() is called. You can also initialize manually by calling:

Metriqus.initSdk(metriqusSettings);

Metriqus SDK Tracking API

The following functions allow you to track user events, ad revenue, and other analytics-related actions within your Flutter project.

Event Tracking Functions

  • trackIAPEvent(MetriqusInAppRevenue metriqusEvent)
    Tracks in-app purchase (IAP) events.

  • trackCustomEvent(MetriqusCustomEvent customEvent)
    Tracks custom events with user-defined parameters.

  • trackPerformance(double fps)
    Tracks FPS and other performance-related metrics.

  • trackItemUsed(MetriqusItemUsedEvent itemEvent)
    Tracks when an item (currency, equipment, etc.) is used.

  • trackLevelStarted(MetriqusLevelStartedEvent levelEvent)
    Tracks when a level starts.

  • trackLevelCompleted(MetriqusLevelCompletedEvent levelEvent)
    Tracks when a level is completed.

  • trackCampaignAction(MetriqusCampaignActionEvent campaignEvent)
    Tracks campaign-related actions such as "Showed", "Clicked", "Closed", or "Purchased".

  • trackScreenView(String screenName)
    Tracks when a user views a specific screen in the app.

  • trackButtonClick(String buttonName)
    Tracks button click events.

Ad Revenue Tracking Functions

  • trackAdRevenue(MetriqusAdRevenue adRevenue)
    Tracks general ad revenue.

  • trackAdmobAdRevenue(MetriqusAdmobAdRevenue admobRevenue)
    Tracks ad revenue from AdMob.

  • trackApplovinAdRevenue(MetriqusApplovinAdRevenue applovinRevenue)
    Tracks ad revenue from AppLovin.

User Attribute Functions

  • setUserAttribute(TypedParameter parameter)
    Sets a user attribute.

  • getUserAttributes()
    Retrieves all user attributes.

  • removeUserAttribute(String key)
    Removes a specific user attribute by key.

Device and System Information Functions

  • getAdid()
    Retrieves the Advertising ID (AdID) of the user.

  • getDeviceInfo()
    Retrieves device information.

  • getUserId()
    Retrieves the unique user identifier.

  • getSessionId()
    Retrieves the current session ID.

  • getGeolocation()
    Retrieves geolocation data.

  • isFirstLaunch()
    Checks if this is the first app launch.

  • getUserFirstTouchTimestamp()
    Retrieves the user's first touch timestamp.

SDK State and Control Functions

  • isInitialized
    Checks whether the Metriqus SDK is initialized.

  • isTrackingEnabled
    Checks whether tracking is enabled.

  • getMetriqusSettings()
    Retrieves the Metriqus SDK settings.

  • verboseLog(String message)
    Sends a manual debug log.

  • updateIOSConversionValue(int value) (iOS Only)
    Updates iOS conversion value.

  • clearStorage()
    Clears all cached data (for debugging).

Notes

  • These functions are designed for Flutter Android/iOS platforms.
  • Ensure the SDK is initialized before calling any tracking functions.
  • Use Environment.sandbox for testing and Environment.production for live apps.
  • All tracking functions are designed to work seamlessly across app sessions.

Usage Guide

Initialization

import 'package:metriqus_flutter_sdk/metriqus_flutter_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final settings = MetriqusSettings(
    clientKey: 'your_client_key',
    clientSecret: 'your_client_secret',
    environment: Environment.sandbox,
    logLevel: LogLevel.verbose,
  );
  
  Metriqus.initSdk(settings);
  runApp(MyApp());
}

App Lifecycle Management

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.resumed:
        Metriqus.onResume();
        break;
      case AppLifecycleState.paused:
        Metriqus.onPause();
        break;
      case AppLifecycleState.detached:
        Metriqus.onQuit();
        break;
    }
  }
}

Event Tracking

Track Custom Events

void trackCustomEvent() {
  final customEvent = MetriqusCustomEvent('button_clicked');
  customEvent.addParameter(TypedParameter.string('button_name', 'play_button'));
  customEvent.addParameter(TypedParameter.string('screen', 'main_menu'));
  customEvent.addParameter(TypedParameter.int('timestamp', MetriqusUtils.getCurrentUtcTimestampSeconds()));
  customEvent.addParameter(TypedParameter.int('user_level', 5));
  customEvent.addParameter(TypedParameter.string('test', 'test'));
  customEvent.addParameter(TypedParameter.bool('test', true));
  customEvent.addParameter(TypedParameter.int('test', 1));
  customEvent.addParameter(TypedParameter.double('test', 1.0));
  
  Metriqus.trackCustomEvent(customEvent);
}

Track In-App Purchases (IAP)

void trackIAPEvent() {
  final iapRevenue = MetriqusInAppRevenue.withRevenue(4.99, 'USD');
  iapRevenue.brand = 'metriqus';
  iapRevenue.variant = 'premium';
  iapRevenue.productId = 'premium_upgrade';
  iapRevenue.name = 'Premium Upgrade';
  iapRevenue.category = 'upgrade';
  iapRevenue.category2 = 'upgrade';
  iapRevenue.category3 = 'upgrade';
  iapRevenue.category4 = 'upgrade';
  iapRevenue.category5 = 'upgrade';
  iapRevenue.price = 4.99;
  iapRevenue.quantity = 1;
  iapRevenue.refund = 0;
  iapRevenue.coupon = 'TEST2025';
  iapRevenue.affiliation = 'metriqus';
  iapRevenue.locationId = 'location_123';
  iapRevenue.listId = 'list_123';
  iapRevenue.listName = 'list_123';
  iapRevenue.listIndex = 1;
  iapRevenue.promotionId = 'promo_123';
  iapRevenue.promotionName = 'promo_123';
  iapRevenue.creativeName = 'creative_123';
  iapRevenue.creativeSlot = 'slot_123';
  
  // Item parameters
  iapRevenue.itemParams = [
    TypedParameter.string('test', 'test'),
    TypedParameter.bool('test', true),
    TypedParameter.int('test', 1),
    TypedParameter.double('test', 1.0),
  ];

  iapRevenue.setTransactionId('txn_${MetriqusUtils.getCurrentUtcTimestampSeconds()}');
  Metriqus.trackIAPEvent(iapRevenue);
}

Track Performance (FPS)

Metriqus.trackPerformance(60);

Track Item Usage

void trackItemUsed() {
  final itemUsedEvent = MetriqusItemUsedEvent();
  itemUsedEvent.itemName = 'health_potion';
  itemUsedEvent.amount = 1.0;
  itemUsedEvent.itemType = 'consumable';
  itemUsedEvent.itemRarity = 'common';
  itemUsedEvent.itemClass = 'healing';
  itemUsedEvent.itemCategory = 'potion';
  itemUsedEvent.reason = 'battle';

  Metriqus.trackItemUsed(itemUsedEvent);
}

Track Level Start

void trackLevelStarted() {
  final levelStartEvent = MetriqusLevelStartedEvent();
  levelStartEvent.levelNumber = 5;
  levelStartEvent.levelName = 'Dragon Valley';
  levelStartEvent.map = 'fantasy_world';

  Metriqus.trackLevelStarted(levelStartEvent);
}

Track Level Completion

void trackLevelCompleted() {
  final levelCompletedEvent = MetriqusLevelCompletedEvent();
  levelCompletedEvent.levelNumber = 5;
  levelCompletedEvent.levelName = 'Dragon Valley';
  levelCompletedEvent.map = 'fantasy_world';
  levelCompletedEvent.duration = 240.0; // 4 minutes
  levelCompletedEvent.levelProgress = 100.0;
  levelCompletedEvent.levelReward = 15000;
  levelCompletedEvent.levelReward1 = 500; // experience
  levelCompletedEvent.levelReward2 = 200; // coins

  Metriqus.trackLevelCompleted(levelCompletedEvent);
}

Track Campaign Actions

void trackCampaignAction() {
  final campaignEvent = MetriqusCampaignActionEvent(
    'summer_2024',
    MetriqusCampaignActionType.click,
    variantId: 'variant_a'
  );
  
  Metriqus.trackCampaignAction(campaignEvent);
}

Track Screen View

Metriqus.trackScreenView('MainMenu');

Track Button Click

Metriqus.trackButtonClick('PlayButton');

Track Ad Revenue (Generic, AdMob, AppLovin)

// General Ad Revenue
void trackAdRevenue() {
  final adRevenue = MetriqusAdRevenue.withRevenue(0.15, 'USD', MetriqusAdUnit.banner, source: 'metriqus');
  adRevenue.adRevenueNetwork = 'AdMob';
  adRevenue.adRevenuePlacement = 'main_screen';
  adRevenue.adImpressionsCount = 1;
  
  Metriqus.trackAdRevenue(adRevenue);
}

// AdMob Ad Revenue
void trackAdmobRevenue() {
  final admobRevenue = MetriqusAdmobAdRevenue.withRevenue(0.22, 'EUR', MetriqusAdUnit.interstitial);
  admobRevenue.adRevenueNetwork = 'AdMob';
  admobRevenue.adRevenuePlacement = 'interstitial';
  admobRevenue.adImpressionsCount = 1;
  
  Metriqus.trackAdmobAdRevenue(admobRevenue);
}

// AppLovin Ad Revenue
void trackApplovinRevenue() {
  final applovinRevenue = MetriqusApplovinAdRevenue.withRevenue(0.18, 'USD', MetriqusAdUnit.rewarded);
  applovinRevenue.adRevenueNetwork = 'AppLovin MAX';
  applovinRevenue.adRevenuePlacement = 'level_complete';
  applovinRevenue.adImpressionsCount = 1;
  
  Metriqus.trackApplovinAdRevenue(applovinRevenue);
}

User Attributes

Set User Attribute

Metriqus.setUserAttribute(TypedParameter.string('user_type', 'premium'));
Metriqus.setUserAttribute(TypedParameter.int('user_level', 25));
Metriqus.setUserAttribute(TypedParameter.bool('is_premium', true));

Get All User Attributes

final attributes = Metriqus.getUserAttributes();

Remove a User Attribute

Metriqus.removeUserAttribute('user_type');

User & Session Info

Get Advertising ID

final adid = Metriqus.getAdid();

Get Device Info

final deviceInfo = Metriqus.getDeviceInfo();

Get Unique User ID

final userId = Metriqus.getUserId();

Get Session ID

final sessionId = Metriqus.getSessionId();

Get Geolocation

final geolocation = Metriqus.getGeolocation();

Check if First Launch

final isFirstLaunch = Metriqus.isFirstLaunch();

Get First Touch Timestamp

final timestamp = Metriqus.getUserFirstTouchTimestamp();

Utility Classes

MetriqusOrderStatus

Constant values for order statuses:

// Successful order status
String orderStatus = MetriqusOrderStatus.success;

// Failed order status  
String orderStatus = MetriqusOrderStatus.fail;

// Cancelled order status
String orderStatus = MetriqusOrderStatus.cancel;

MetriqusAdUnit

Enum values for ad unit types with type safety:

// Banner ad
MetriqusAdUnit adUnit = MetriqusAdUnit.banner;

// Interstitial ad
MetriqusAdUnit adUnit = MetriqusAdUnit.interstitial;

// Rewarded ad
MetriqusAdUnit adUnit = MetriqusAdUnit.rewarded;

// Rewarded interstitial ad
MetriqusAdUnit adUnit = MetriqusAdUnit.rewardedInterstitial;

// Native advanced ad
MetriqusAdUnit adUnit = MetriqusAdUnit.nativeAdvenced;

// App open ad
MetriqusAdUnit adUnit = MetriqusAdUnit.appOpen;

// Convert enum to string value
String adUnitString = MetriqusAdUnit.banner.value; // Returns "banner"

// Convert string to enum
MetriqusAdUnit? adUnit = MetriqusAdUnit.fromString("banner"); // Returns MetriqusAdUnit.banner

SDK Settings & Debugging

Check Initialization

final isInitialized = Metriqus.isInitialized;

Check Tracking Enabled

final isTrackingEnabled = Metriqus.isTrackingEnabled;

Get Metriqus Settings

final settings = Metriqus.getMetriqusSettings();

Manual Debug Log

Metriqus.verboseLog('Hello Metriqus!');

iOS Conversion Value Update

(Only available on iOS builds)

Metriqus.updateIOSConversionValue(5);

Clear Storage (Debug)

Metriqus.clearStorage();

Running the Example

cd example
flutter pub get
flutter run

License

MIT

Libraries

metriqus_flutter_sdk
Metriqus Flutter SDK