Supporting SKAdNetwork

SKAdNetwork is Apple's privacy-focused attribution framework for iOS app install campaigns. The Singular Flutter SDK enables SKAdNetwork by default in Managed Mode, where Singular automatically updates conversion values based on your configured conversion model in the dashboard.

Understanding SKAN Modes

Managed Mode (Default)

In Managed Mode, Singular automatically handles conversion value updates based on the conversion model you configure in your dashboard. This is the recommended approach for most apps as it requires minimal code and provides optimal conversion tracking.

• Automatic updates: Singular manages all conversion value updates based on user events and your configured model.
• Dashboard configuration: Design your conversion model in the Singular dashboard without code changes.
• Optimization: Benefit from Singular's expertise in maximizing conversion value updates within Apple's constraints.
• 24-hour window management: Singular handles SKAdNetwork's 24-hour update window intelligently to maximize data collection.

Manual Mode (Advanced)

Manual Mode gives you complete control over conversion value updates, allowing you to implement custom logic for determining when and how to update SKAN conversion values. Use this mode only if you have specific requirements that Managed Mode cannot fulfill.

Disabling SKAdNetwork Support

SKAdNetwork tracking is enabled by default. To disable it, set the skAdNetworkEnabled configuration property to false when building your SingularConfig object.

import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET');
config.skAdNetworkEnabled = false; // Disable SKAdNetwork

Configuring Manual Mode

To implement custom conversion value logic, enable Manual Mode and use the provided SDK methods to update and monitor conversion values throughout your app's lifecycle.

Enable Manual Mode

Set the manualSkanConversionManagement configuration property to true when building your SingularConfig object to take control of conversion value updates.

import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET');
config.manualSkanConversionManagement = true; // Enable manual mode

Update Conversion Value (SKAN 2.0-3.0)

Use the skanUpdateConversionValue method to manually update the SKAdNetwork conversion value based on your custom logic. The conversion value must be an integer between 0 and 63.

Method Signature

static void skanUpdateConversionValue(int conversionValue)

Usage Example

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// User completed signup - update conversion value to 7
void onUserSignUp() {
  if (Platform.isIOS) {
    // Track the sign-up event
    Singular.event('SignUp');

    // Update SKAN conversion value
    Singular.skanUpdateConversionValue(7);
    print('Conversion value updated to 7');
  }
}

// User completed purchase - update based on purchase amount
void onPurchaseComplete(double purchaseAmount) {
  if (Platform.isIOS) {
    // Track revenue event
    Singular.customRevenue('Purchase', 'USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    int conversionValue = calculateConversionValue(purchaseAmount);
    Singular.skanUpdateConversionValue(conversionValue);
    print('Conversion value updated to $conversionValue');
  }
}

int calculateConversionValue(double amount) {
  // Your custom logic to determine conversion value
  if (amount >= 100) return 63;  // High value
  if (amount >= 50) return 40;   // Medium value
  if (amount >= 10) return 20;   // Low value
  return 10;                      // Minimal value
}

Update Conversion Values (SKAN 4.0)

For iOS 16.1+, use the skanUpdateConversionValues method to update SKAdNetwork 4.0 conversion values with fine value, coarse value, and lock parameters. This provides more granular control over conversion value updates.

Method Signature

static void skanUpdateConversionValues(
  int conversionValue,  // Fine value (0-63)
  int coarse,           // Coarse value (0=low, 1=medium, 2=high)
  bool lock             // Lock status
)

Usage Example

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

void updateSKAN4ConversionValue(
  int fineValue, 
  String coarseValue,
  bool shouldLock
) {
  if (Platform.isIOS) {
    // Map coarse value string to number
    Map<String, int> coarseMap = {
      'low': 0, 
      'medium': 1, 
      'high': 2
    };

    // Update SKAdNetwork 4.0 conversion values
    Singular.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue] ?? 0,
      shouldLock
    );

    print('SKAN 4.0 updated: fine=$fineValue, coarse=$coarseValue, lock=$shouldLock');
  }
}

// Example: High-value user completes tutorial
void onTutorialComplete() {
  updateSKAN4ConversionValue(15, 'medium', false);
}

// Example: Premium purchase - lock the value
void onPremiumPurchase() {
  updateSKAN4ConversionValue(63, 'high', true);
}

Get Current Conversion Value

Retrieve the current conversion value tracked by the Singular SDK. This is useful for implementing conditional logic based on the current state and works in both Managed and Manual modes.

Method Signature

static Future<int> skanGetConversionValue()

Usage Example

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

Future<void> checkAndUpdateConversionValue() async {
  if (Platform.isIOS) {
    int currentValue = await Singular.skanGetConversionValue();
    print('Current conversion value: $currentValue');

    // Only update if current value is below threshold
    if (currentValue < 30) {
      Singular.skanUpdateConversionValue(30);
      print('Updated conversion value to 30');
    }
  }
}

Monitor Conversion Value Updates

Set up a handler to receive real-time notifications whenever the conversion value changes. This enables you to react to conversion value updates and log analytics or trigger other app behaviors.

Configuration

Configure the conversion value update handler using the conversionValueUpdatedCallback property when initializing the SDK.

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

void initializeSingularSDK() {
  SingularConfig config = SingularConfig('API_KEY', 'SECRET');

  // Set up conversion value update handler
  config.conversionValueUpdatedCallback = (int conversionValue) {
    print('Conversion value updated to: $conversionValue');

    // Log the update to your analytics
    logConversionValueUpdate(conversionValue);

    // Trigger app-specific behavior
    if (conversionValue >= 50) {
      unlockPremiumFeature();
    }
  };

  Singular.start(config);
}

void logConversionValueUpdate(int value) {
  // Your analytics logging logic
  print('Analytics: SKAN CV = $value');
}

void unlockPremiumFeature() {
  // Your custom logic
  print('Premium feature unlocked based on high conversion value');
}

Supporting App Tracking Transparency (ATT)

App Tracking Transparency (ATT) is Apple's privacy framework requiring user consent before accessing the device's IDFA (Identifier for Advertisers) and sharing user data. Implementing ATT correctly is critical for iOS attribution and maximizing the accuracy of your user acquisition campaigns.

Why ATT Matters for Attribution

Starting with iOS 14.5, apps must request user permission through the ATT framework before accessing the IDFA. While attribution is still possible without the IDFA using fingerprinting and probabilistic methods, having the IDFA significantly improves attribution accuracy and provides deterministic matching.

• Deterministic attribution: The IDFA enables precise, device-level attribution that connects ad impressions directly to installs.
• Ad network optimization: Ad networks can better optimize campaigns and provide more accurate reporting with IDFA access.
• User-level insights: Access to IDFA allows for more granular user behavior analysis and cohort tracking.

Implementation Requirements

For iOS 14.5+ (including iOS 18), use the ATTrackingManager framework to request user consent before accessing the IDFA for tracking. The Singular SDK supports ATT, allowing initialization before consent and delaying events until consent is granted or a timeout occurs.

Step 1: Add ATT Framework Configuration

Configure your iOS app to support the ATT framework by updating your Info.plist file with a user-facing usage description.

1. Open Info.plist: Navigate to your Flutter project's iOS Info.plist file (located in ios/Runner/Info.plist).
2. Add usage description: Add the NSUserTrackingUsageDescription key with a clear explanation of why your app needs tracking permission.

<key>NSUserTrackingUsageDescription</key>
<string>This app uses tracking to provide personalized ads and improve your experience.</string>

Step 2: Install ATT Support Package

Install a Flutter ATT support package to enable ATT functionality in your app. We recommend the app_tracking_transparency plugin.

Add Dependency

dependencies:
  flutter:
    sdk: flutter
  singular_flutter_sdk: ^1.8.0
  app_tracking_transparency: ^2.0.4

After adding the dependency, run flutter pub get to install the package.

flutter pub get

Step 3: Configure SDK Wait Timeout

Configure the Singular SDK to wait for the user's ATT response before initializing by setting the waitForTrackingAuthorizationWithTimeoutInterval property. This delay ensures the IDFA is captured if the user grants permission.

import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET');
config.waitForTrackingAuthorizationWithTimeoutInterval = 300; // Wait up to 5 minutes

Step 4: Request ATT Consent

Implement the ATT request flow in your app, prompting users for tracking permission at an appropriate time in your user experience.

import 'package:flutter/material.dart';
import 'dart:io';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:app_tracking_transparency/app_tracking_transparency.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeApp();
  }

  Future<void> initializeApp() async {
    if (Platform.isIOS) {
      // Request ATT authorization
      final trackingStatus = await AppTrackingTransparency.requestTrackingAuthorization();

      // Log the user's response
      print('ATT Status: $trackingStatus');
      // Possible values: TrackingStatus.authorized, .denied, .restricted, .notDetermined
    }

    // Initialize Singular SDK (configured with wait timeout)
    SingularConfig config = SingularConfig('API_KEY', 'SECRET');
    config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
    config.enableLogging = true;

    Singular.start(config);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

Understanding ATT Flow

When you set an initialization delay using waitForTrackingAuthorizationWithTimeoutInterval, the app flow works as follows:

1. When the app opens, the Singular SDK starts recording a session and user events but does not send them to the Singular server yet.
2. When App Tracking Transparency consent is granted/denied, or the set time elapses, the SDK sends the session and any queued events to the Singular server (with or without the IDFA).
3. Singular then starts the attribution process, taking advantage of the IDFA if it is available.

ATT Scenarios

The following table summarizes the possible scenarios using this integration:

ATT Best Practices

• Pre-prompt messaging: Show users a pre-ATT screen explaining why you need tracking permission and how it benefits them (better ads, improved experience). This can significantly increase opt-in rates.
• Timing matters: Show the ATT prompt at a natural moment in your app flow, not immediately on first launch. Let users experience your app first to build trust.
• Timeout configuration: Set waitForTrackingAuthorizationWithTimeoutInterval to 30-300 seconds. Post-timeout, Singular proceeds with SKAN 4.0 attribution (no IDFA).
• Test thoroughly: Test both authorized and denied scenarios to ensure your app functions correctly regardless of the user's choice.
• Respect user choice: Never repeatedly prompt users who have denied tracking or show aggressive messaging that pressures them to opt in.
• Error handling: Check tracking status for restricted (e.g., parental controls) or notDetermined states and log for analytics.
• SKAN 4.0 Integration: Ensure conversion value updates align with ATT consent to optimize SKAN postbacks (e.g., use Singular's dashboard for mapping events to values 0-63).

Additional Resources

• Apple's App Tracking Transparency Framework Documentation
• Singular SDK Opt-In and Opt-Out Practices
• Apple's User Privacy and Data Use Guidelines
• Singular's SKAdNetwork Guide
• Flutter App Tracking Transparency Plugin