adRevenue

Singular.adRevenue Method

Tracks ad revenue events with detailed ad data information. This method allows you to report revenue generated from ads displayed in your application with various parameters to categorize and analyze the ad performance.

Signature

static void adRevenue(SingularAdData? adData)

Usage Example

// Create ad data object
final adData = SingularAdData("AdMob", "USD", 0.05)
    .withNetworkName("Google")
    .withAdType("Rewarded")
    .withAdPlacementName("level_complete")
    .withAdUnitId("ca-app-pub-123456789/1234567890");

// Track ad revenue event
Singular.adRevenue(adData);

clearGlobalProperties

Singular.clearGlobalProperties Method

Removes all previously set global properties. This is useful when you need to reset the global properties, for example when a user logs out of your application.

Signature

static void clearGlobalProperties()

Usage Example

// Clear all global properties, for example when a user logs out
Singular.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink Method

Creates a short link with referrer information that can be used for sharing and attribution. This method generates trackable links that can be shared with users, allowing you to attribute installs and activities to specific referral sources.

Signature

static void createReferrerShortLink(String baseLink, String referrerName, String referrerId, Map args, ShortLinkCallback shortLinkCallback)

Usage Example

// Create a short link for referral
Singular.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Referrer Name
    "aq239897", // Referrer ID
    {
        "channel": "sms", 
        "campaign": "summer_promo"
    }, // Passthrough parameters
    (String? data, String? error) {
        if (error != null) {
            print("Error creating short link: $error");
        } else {
            print("Generated short link: $data");
            // Share the link with users
        }
    }
);

customRevenue

Singular.customRevenue Method

Tracks a custom revenue event with a specified event name, currency, and amount. This allows you to track revenue events with custom names for more specific revenue tracking.

• Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

• Currency Codes must be ALL CAPS and adhere to the three-letter ISO 4217 currency code

Signature

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

Usage Example

// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);

customRevenueWithAllAttributes

Singular.customRevenueWithAllAttributes Method

Tracks a custom revenue event with a specified event name, currency, amount, and detailed product information. This allows for comprehensive revenue tracking with product details.

• Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

• Currency Codes must be ALL CAPS and adhere to the three-letter ISO 4217 currency code

Signature

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

Usage Example

// Track a custom revenue event with detailed product information
Singular.customRevenueWithAllAttributes(
    "item_purchased",
    "USD",
    19.98,
    "SKU123456",
    "Premium Sword",
    "Weapons",
    2,
    9.99
);

customRevenueWithAttributes

Singular.customRevenueWithAttributes Method

Tracks a custom revenue event with a specified event name, currency, amount, and additional custom attributes. This allows for more detailed revenue tracking with custom parameters.

• Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

• Currency Codes must be ALL CAPS and adhere to the three-letter ISO 4217 currency code

Signature

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

Usage Example

// Track a custom revenue event with additional parameters
Singular.customRevenueWithAttributes(
    "in_app_purchase",
    "USD",
    5.99,
    {
        "product_id": "com.app.gems_pack_small",
        "quantity": 1,
        "transaction_id": "T12345678",
        "receipt_id": "R98765432"
    }
);

event

Singular.event Method

Tracks a simple event with the specified name. Use this method to track user actions and engagement within your application.

• Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

Signature

static void event(String eventName)

Usage Example

// Track a simple event
Singular.event("level_completed");

eventWithArgs

Singular.eventWithArgs Method

Tracks an event with the specified name and additional custom attributes. This allows for more detailed event tracking with custom parameters.

• Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.
• Event attribute names and attribute values are limited to 500 ASCII characters.

Signature

static void eventWithArgs(String eventName, Map args)

Usage Example

// Track an event with additional parameters
Singular.eventWithArgs(
    "level_completed",
    {
        "level_id": 5,
        "score": 12500,
        "time_spent": 120,
        "difficulty": "medium"
    }
);

getGlobalProperties

Singular.getGlobalProperties Method

Retrieves all currently set global properties. This method returns a Future that resolves to a Map containing all global properties that have been set for the SDK.

Signature

static Future getGlobalProperties()

Usage Example

// Get all global properties
Singular.getGlobalProperties()

getLimitDataSharing

Singular.getLimitDataSharing Method

Retrieves the current data sharing limitation status. This method returns a Future that resolves to a boolean indicating whether data sharing is currently limited.

Signature

static Future getLimitDataSharing()

Usage Example

// Check if data sharing is limited
Singular.getLimitDataSharing()

handlePushNotification

Singular.handlePushNotification Method

Processes a push notification payload for attribution. This method should be called when your app receives a push notification to allow Singular to attribute it correctly. This method is only available on iOS.

Signature

static void handlePushNotification(Map pushNotificationPayload)

Usage Example

// Handle a received push notification
void onPushNotificationReceived(Map payload) {
  Singular.handlePushNotification(payload);
}

inAppPurchase

Singular.inAppPurchase Method

Tracks an in-app purchase event with the specified event name and purchase data. This method is used to report in-app purchases made within your application.

• Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

Signature

static void inAppPurchase(String eventName, SingularIAP purchase)

Usage Example

import 'package:singular_flutter_sdk/singular_iap.dart';

singularPurchase = new SingularIOSIAP(
   product.price,
   product.currencyCode,
   purchase.productId,
   purchase.purchaseId,
   purchase.verificationData.serverVerificationData);

singularPurchase = new SingularAndroidIAP(
   product.price,
   product.currencyCode,
   purchase.singature,
   purchase.verificationData.serverVerificationData);

Singular.inAppPurchase(eventName, singularPurchase);

inAppPurchaseWithAttributes

Singular.inAppPurchaseWithAttributes Method

Tracks an in-app purchase event with the specified event name, purchase data, and additional custom attributes. This allows for more detailed purchase tracking with custom parameters.

• Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

Signature

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

Usage Example

import 'package:singular_flutter_sdk/singular_iap.dart';

singularPurchase = new SingularIOSIAP(
   product.price,
   product.currencyCode,
   purchase.productId,
   purchase.purchaseId,
   purchase.verificationData.serverVerificationData);

singularPurchase = new SingularAndroidIAP(
   product.price,
   product.currencyCode,
   purchase.singature,
   purchase.verificationData.serverVerificationData);

// Track the purchase with additional attributes
Singular.inAppPurchaseWithAttributes(
    eventName, 
    singularPurchase,
    purchase,
    {
        "user_level": 42,
        "is_first_purchase": true,
        "gems_balance": 1500
    }
);

isAllTrackingStopped

Singular.isAllTrackingStopped Method

Checks if all tracking is currently stopped. This method returns a Future that resolves to a boolean indicating whether tracking is currently stopped.

Signature

static Future isAllTrackingStopped()

Usage Example

// Check if tracking is stopped
Singular.isAllTrackingStopped()

limitDataSharing

Singular.limitDataSharing Method

Sets the data sharing limitation status. Use this method to limit data sharing based on user consent or privacy requirements.

Signature

static void limitDataSharing(bool shouldLimitDataSharing)

Usage Example

// To limit data sharing (e.g., when user opts out) 
Singular.limitDataSharing(true);

// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false);

registerDeviceTokenForUninstall

Singular.registerDeviceTokenForUninstall Method

Registers the device token for uninstall tracking. This method should be called with the push notification token to enable uninstall tracking.

Signature

static void registerDeviceTokenForUninstall(String deviceToken)

Usage Example

// Register device token for uninstall tracking
Singular.registerDeviceTokenForUninstall(token);

resumeAllTracking

Singular.resumeAllTracking Method

Resumes all tracking activities that were previously stopped. Use this method to re-enable tracking after it has been stopped.

Signature

static void resumeAllTracking()

Usage Example

// Resume tracking, for example when user opts back in
Singular.resumeAllTracking();

setCustomUserId

Singular.setCustomUserId Method

Sets a custom user ID for the current user. This allows you to associate Singular data with your own user identification system.

Signature

static void setCustomUserId(String customUserId)

Usage Example

// Set custom user ID after user logs in
Singular.setCustomUserId(customUserId);

setDeviceCustomUserId

Singular.setDeviceCustomUserId Method

Sets a custom user ID at the device level. This allows you to associate Singular data with your own user identification system at the device level.

Signature

static void setDeviceCustomUserId(String customUserId)

Usage Example

// Set device-level custom user ID
Singular.setDeviceCustomUserId(customUserId);

setFCMDeviceToken

Singular.setFCMDeviceToken Method

Sets the Firebase Cloud Messaging (FCM) device token for push notifications. This is used for uninstall tracking and push notification attribution on Android devices.

Signature

static void setFCMDeviceToken(String fcmToken)

Usage Example

// Set FCM token when received from Firebase
void onFCMTokenReceived(String token) {
    Singular.setFCMDeviceToken(token);
}

setGlobalProperty

Singular.setGlobalProperty Method

Sets a global property that will be sent with all events. This allows you to add consistent attributes to all events without specifying them each time.

Signature

static Future setGlobalProperty(String key, String value, bool overrideExisting)

Usage Example

// Set a global property
Singular.setGlobalProperty("user_tier", "premium", true).then((isSuccess) {
    print("Global property set successfully: $isSuccess");
});

skanGetConversionValue

Singular.skanGetConversionValue Method

Retrieves the current SKAdNetwork conversion value. This method is specific to iOS and returns a Future that resolves to the current conversion value used for SKAdNetwork attribution.

Signature

static Future skanGetConversionValue()

Usage Example

// Get the current SKAdNetwork conversion value
if (Platform.isIOS) {
    Singular.skanGetConversionValue().then((conversionValue) {
        print("Current conversion value: $conversionValue");
    });
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution Method

Registers the app for SKAdNetwork attribution. This method is specific to iOS and should be called to enable SKAdNetwork attribution.

Signature

static void skanRegisterAppForAdNetworkAttribution()

Usage Example

// Register for SKAdNetwork attribution
if (Platform.isIOS) {
    Singular.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue Method

Updates the SKAdNetwork conversion value. This method is specific to iOS and allows you to manually update the conversion value used for SKAdNetwork attribution.

Signature

static Future skanUpdateConversionValue(int conversionValue)

Usage Example

// Update the SKAdNetwork conversion value
if (Platform.isIOS) {
    Singular.skanUpdateConversionValue(5).then((isSuccess) {
        print("Conversion value updated successfully: $isSuccess");
    });
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues Method

Updates the SKAdNetwork conversion values with additional parameters. This method is specific to iOS 16.1+ and allows you to update the fine, coarse, and lock values for SKAdNetwork 4.0 attribution.

Signature

static void skanUpdateConversionValues(int conversionValue, int coarse, bool lock)

Usage Example

// Update the SKAdNetwork 4.0 conversion values
if (Platform.isIOS) {
    Singular.skanUpdateConversionValues(
        5,       // fine value (0-63)
        1,       // coarse value (0=low, 1=medium, 2=high)
        false    // lock
    );
}

start

Singular.start Method

Initializes the Singular SDK with the provided configuration. This is the first method you should call to start using the Singular SDK.

Signature

static void start(SingularConfig config)

Usage Example

// Create configuration object
SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');

// Configure additional options if needed
config.customUserId = "user-123456";
config.sessionTimeout = 60;

// Initialize the SDK
Singular.start(config);

stopAllTracking

Singular.stopAllTracking Method

Stops all tracking activities. Use this method to disable tracking when users opt out or for privacy compliance.

Signature

static void stopAllTracking()

Usage Example

// Stop tracking, for example when user opts out.
Singular.stopAllTracking();

trackingOptIn

Singular.trackingOptIn Method

Indicates that the user has opted in to tracking. Call this method when the user explicitly consents to tracking and data collection.

Signature

static void trackingOptIn()

Usage Example

// User has opted in to tracking
Singular.trackingOptIn();

trackingUnder13

Singular.trackingUnder13 Method

Indicates that the user is under 13 years old. Call this method to comply with COPPA and other regulations for users under 13 years old.

Signature

static void trackingUnder13()

Usage Example

// Notifies Singular the User is under 13 years old, GDPR_UNDER_13 flag applied.
Singular.trackingunder13();

unsetCustomUserId

Singular.unsetCustomUserId Method

Removes the previously set custom user ID. Call this method when the user logs out or when you no longer want to associate events with the current user ID.

Signature

static void unsetCustomUserId()

Usage Example

// Clear custom user ID when user logs out
Singular.unsetCustomUserId();

unsetGlobalProperty

Singular.unsetGlobalProperty Method

Removes a previously set global property. Call this method when you no longer want a specific global property to be sent with events.

Signature

static void unsetGlobalProperty(String key)

Usage Example

// Remove a global property
Singular.unsetGlobalProperty("user_tier");