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.

// Track a simple custom event
cordova.plugins.SingularCordovaSdk.event('SignUp');

// Track a standard event
cordova.plugins.SingularCordovaSdk.event('sngLogin');

Method Signature:

event(eventName: string): void

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.

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

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

Method Signature:

eventWithArgs(eventName: string, args: Object): void

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 Cordova IAP plugins to retrieve the purchase object with complete transaction details from platform stores.

• iOS: Use cordova-plugin-purchase or similar to access StoreKit purchase details
• Android: Use cordova-plugin-purchase or similar to obtain Google Play Billing purchase details

SingularIAP Constructor

Create an in-app purchase object for tracking revenue with platform-specific receipt validation and fraud prevention.

Constructor Signature:

function SingularIAP(product: Object): SingularIAP

For the complete constructor reference, see SingularIAP constructor 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 Singular SDK and SingularIAP constructor
var Singular = cordova.plugins.SingularCordovaSdk;
var SingularIAP = cordova.require('singular-cordova-sdk.SingularIAP');

// iOS App Store purchase example
function handleiOSPurchase(purchase) {
  // Create iOS product object
  var iosProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'ios-appstore',
      appStoreReceipt: purchase.receipt, // Base64 receipt from StoreKit
      id: purchase.transactionId // Transaction identifier
    }
  };

  // Create SingularIAP object
  var iosIAP = new SingularIAP(iosProduct);

  // Track the purchase with Singular
  // The SingularIAP object is passed as additional args
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', iosIAP);
}

// Android Play Store purchase example
function handleAndroidPurchase(purchase) {
  // Create Android product object
  var androidProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'android-playstore',
      receipt: purchase.receipt, // JSON receipt from Google Play
      signature: purchase.signature // Signature from Google Play
    }
  };

  // Create SingularIAP object
  var androidIAP = new SingularIAP(androidProduct);

  // Track the purchase with Singular
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', androidIAP);
}

// Example integration with cordova-plugin-purchase
document.addEventListener('deviceready', function() {
  // Initialize the store
  store.register({
    id: 'com.app.premiumgems',
    type: store.CONSUMABLE
  });

  // Handle purchase approved
  store.when('com.app.premiumgems').approved(function(product) {
    // Determine platform and handle accordingly
    if (device.platform === 'iOS') {
      handleiOSPurchase(product.transaction);
    } else if (device.platform === 'Android') {
      handleAndroidPurchase(product.transaction);
    }

    // Finish the transaction
    product.finish();
  });

  // Refresh the store
  store.refresh();
});

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.

Revenue Method

Track simple revenue events with a specified currency and amount.

// Track revenue without product details
cordova.plugins.SingularCordovaSdk.revenue('USD', 4.99);

Method Signature:

revenue(currency: string, amount: number): void

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

RevenueWithArgs Method

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

// Track revenue with attributes
cordova.plugins.SingularCordovaSdk.revenueWithArgs('USD', 9.98, {
  productSKU: 'coin_package_abc123',
  productName: 'Coin Pack 10',
  productCategory: 'Bundles',
  productQuantity: 2,
  productPrice: 4.99,
  transaction_id: 'T12345'
});

Method Signature:

revenueWithArgs(currency: string, amount: number, args: Object): void

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

CustomRevenue Method

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

// Track custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue('PremiumUpgrade', 'USD', 9.99);

Method Signature:

customRevenue(eventName: string, currency: string, amount: number): void

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

CustomRevenueWithArgs Method

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

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

Method Signature:

customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Object): void

For the complete list of methods, see customRevenueWithArgs 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.