Tracking In-App Events

Track in-app events to analyze campaign performance and measure key performance indicators (KPIs) such as user logins, registrations, tutorial completions, or progression milestones.

Standard Events and Attributes

Understanding Event Types

Singular supports two types of events to accommodate both universal and app-specific tracking needs.

• Standard Events: Predefined events (e.g., sngLogin, sngContentView) recognized by Singular and supported by ad networks for reporting and optimization. Using standard events simplifies setup, as Singular automatically adds them to your Events list without manual definition. See the List of Standard Events and Attributes for complete event names and recommended attributes.
• Custom Events: Events unique to your app (e.g., Signup, AchievementUnlocked) that don't match Singular's standard events.

Your UA, marketing, or business team should compile the list of events based on your organization's marketing KPIs. Reference the guide How to Track In-App Events: Guide for Singular Attribution Customers for planning.

Custom Event Limitations

Custom events have specific character and encoding constraints to ensure compatibility with third-party partners and analytics solutions.

Sending Events

Event Method

Track simple events without additional attributes using the event() method.

import 'package:singular_flutter_sdk/singular.dart';

// Track a simple custom event
Singular.event('SignUp');

// Track a standard event
Singular.event('sngLogin');

Method Signature:

static void event(String eventName)

For the complete list of methods, see event method reference.

EventWithArgs Method

Track events with additional custom attributes to provide richer context and enable detailed segmentation in reports.

import 'package:singular_flutter_sdk/singular.dart';

// Track custom event with attributes
Singular.eventWithArgs('LevelComplete', {
  'level': 5,
  'score': 1250,
  'time_spent': 45.3
});

// Track standard event with recommended attributes
Singular.eventWithArgs('sngTutorialComplete', {
  'sngAttrContent': 'Flutter Basics',
  'sngAttrContentId': '32',
  'sngAttrContentType': 'video',
  'sngAttrSuccess': 'yes'
});

Method Signature:

static void eventWithArgs(String eventName, Map args)

For the complete list of methods, see eventWithArgs method reference.

Best Practices

Tracking In-App Revenue

Track revenue from in-app purchases (IAP), subscriptions, and custom revenue sources to measure campaign performance and return on ad spend (ROAS).

Revenue data flows through three channels:

• Interactive Reports: View revenue metrics in the Singular dashboard
• Export Logs: Access detailed ETL data for custom analysis
• Real-Time Postbacks: Send revenue events to external platforms

Why Track Revenue Events?

• Rich Analytics: Capture detailed transaction data to enhance Singular reports
• Fraud Prevention: Include transaction receipts (e.g., from Google Play or Apple App Store) to validate purchases and combat in-app fraud
• Campaign Optimization: Measure ROI by tying revenue to marketing efforts

In-App Purchase Integration

Capture the IAP Purchase Object

Use the Flutter in_app_purchase package to retrieve the purchase object with complete transaction details.

• Flutter: Use in_app_purchase package to access both iOS StoreKit and Android Google Play Billing purchase details

InAppPurchase Method

Track in-app purchase events with purchase details for revenue validation and fraud prevention.

Method Signatures:

static void inAppPurchase(String eventName, SingularIAP purchase)

static void inAppPurchaseWithAttributes(String eventName, SingularIAP purchase, Map attributes)

For the complete list of methods, see inAppPurchase method reference.

Complete IAP Implementation Example

Implement a complete purchase listener that captures IAP events and sends them to Singular with platform-specific purchase objects.

import 'dart:io' show Platform;
import 'package:in_app_purchase/in_app_purchase.dart';
import 'package:in_app_purchase_android/in_app_purchase_android.dart';
import 'package:in_app_purchase_storekit/in_app_purchase_storekit.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';

Future<void> handlePurchase(PurchaseDetails purchaseDetails) async {
  if (purchaseDetails.status != PurchaseStatus.purchased &&
      purchaseDetails.status != PurchaseStatus.restored) {
    return;
  }

  final response = await InAppPurchase.instance
      .queryProductDetails({purchaseDetails.productID});
  if (response.productDetails.isEmpty) {
    return;
  }
  final product = response.productDetails.first;

  // Extract price and currency with platform-specific handling
  double price = 0.0;
  String currency = 'USD';

  if (Platform.isAndroid && product is GooglePlayProductDetails) {
    final offer = product.productDetails.oneTimePurchaseOfferDetails;
    price = (offer?.priceAmountMicros ?? 0) / 1000000;
    currency = offer?.priceCurrencyCode ?? 'USD';
  } else if (Platform.isIOS && product is AppStoreProductDetails) {
    price = product.skProduct.price;
    currency = product.skProduct.priceLocale.currencyCode ?? 'USD';
  }

  SingularIAP? singularPurchase;

  if (Platform.isAndroid && purchaseDetails is GooglePlayPurchaseDetails) {
    singularPurchase = SingularAndroidIAP(
      price,
      currency,
      purchaseDetails.billingClientPurchase.signature,
      purchaseDetails.billingClientPurchase.originalJson,
    );
  } else if (Platform.isIOS && purchaseDetails is AppStorePurchaseDetails) {
    singularPurchase = SingularIOSIAP(
      price,
      currency,
      purchaseDetails.productID,
      purchaseDetails.skPaymentTransaction.transactionIdentifier ?? '',
      purchaseDetails.verificationData.serverVerificationData,
    );
  } else {
    return;
  }

  const String eventName = 'iap_purchase';
  
  // Track with attributes (use only ONE tracking method)
  Singular.inAppPurchaseWithAttributes(eventName, singularPurchase, {
    'user_level': 42,
    'is_first_purchase': true,
    'gems_balance': 1500
  });

  await InAppPurchase.instance.completePurchase(purchaseDetails);
}

Manual Revenue Tracking

Revenue without Purchase Validation

Track revenue by passing currency, amount, and optional product details without the Purchase object. Note that this method does not provide transaction receipts for validation.

CustomRevenue Method

Track custom revenue events with a specified event name, currency, and amount.

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue event
Singular.customRevenue('PremiumUpgrade', 'USD', 9.99);

Method Signature:

static void customRevenue(String eventName, String currency, double amount)

For the complete list of methods, see customRevenue method reference.

CustomRevenueWithAttributes Method

Track custom revenue events with a specified event name, currency, amount, and additional custom attributes.

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue event with attributes
Singular.customRevenueWithAttributes('PremiumBundlePurchase', 'USD', 99.99, {
  'productSKU': 'premium_bundle_xyz',
  'productName': 'Premium Bundle',
  'productCategory': 'Bundles',
  'productQuantity': 1,
  'discount_applied': true
});

Method Signature:

static void customRevenueWithAttributes(
  String eventName,
  String currency,
  double amount,
  Map attributes
)

For the complete list of methods, see customRevenueWithAttributes method reference.

CustomRevenueWithAllAttributes Method

Track custom revenue events with all possible attributes including product SKU, name, category, quantity, and custom attributes.

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with all attributes
Singular.customRevenueWithAllAttributes(
  'CoinPackagePurchase',
  'USD',
  4.99,
  'coin_package_abc123',
  'Coin Pack 10',
  'Virtual Currency',
  2,
  {
    'payment_method': 'google_play',
    'transaction_id': 'T12345'
  }
);

Method Signature:

static void customRevenueWithAllAttributes(
  String eventName,
  String currency,
  double amount,
  String productSKU,
  String productName,
  String productCategory,
  int productQuantity,
  Map attributes
)

For the complete list of methods, see customRevenueWithAllAttributes method reference.

Subscription Revenue

Tracking Subscriptions

Singular offers a comprehensive guide on implementing subscription events using the Singular SDK. The guide covers in-app subscription event tracking across various platforms.

• Read the Subscription Event Technical Implementation Guide if you would like to track subscription revenue

Hybrid Event Tracking (Advanced)

Singular recommends sending all events and revenue through the Singular SDK integrated into your app for optimal attribution. However, Singular can collect events from other sources when necessary.

Events sent outside the Singular SDK must comply with Singular's Server-to-Server Event documentation requirements and provide matching device identifiers for correct attribution.

Hybrid Event Tracking Guides

Sending Events from an Internal Server

Collect revenue data from your internal server to analyze campaign performance and ROI.

Requirements:

• Capture Device Identifiers: From an in-app Registration or Login Event, capture and pass the device identifiers and store this data with the User ID on your server. Because device identifiers may change for a user, update the identifiers when a user generates an app session. This guarantees the server-side event will be attributed to the correct device
• Platform-Specific Identifiers: Server-side events are platform specific and should only be sent with the device identifier matching the device platform (e.g., IDFA or IDFV for iOS devices, GAID for Android devices)
• Real-Time Updates: Use the Singular Internal BI postback mechanism to push an event in real time to your internal endpoint so that you can update the data set on the server side. See the Internal BI Postback FAQ
• Implementation Details: Review the Tracking Revenue section in the Server-to-Server Integration guide for details

Sending Events from a Revenue Provider

Integrate third-party revenue providers like RevenueCat or adapty to send purchase and subscription revenue to Singular.

Supported Providers:

• RevenueCat: Learn more in the RevenueCat documentation
• adapty: Learn more in the adapty documentation

Sending Events from Segment

Enable Segment to send events to Singular in parallel with the Singular SDK by adding a "Cloud-Mode" destination in Segment.

Follow the implementation guide Singular-Segment Integration for detailed setup instructions.