Supporting SKAdNetwork

SKAdNetwork is Apple's privacy-focused attribution framework for iOS app install campaigns. The Singular Cordova 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.

// Create configuration
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Disable SKAdNetwork
singularConfig.withSkAdNetworkEnabled(false);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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.

// Create configuration with manual SKAN mode
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Enable manual SKAN conversion management
singularConfig.withManualSkanConversionManagement();

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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.

// Check if running on iOS
if (device.platform === 'iOS') {
  // User completed signup - update conversion value to 7
  function onUserSignUp() {
    // Track the sign-up event
    cordova.plugins.SingularCordovaSdk.event('SignUp');

    // Update SKAN conversion value
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(7, function(success) {
      if (success) {
        console.log('Conversion value updated successfully');
      } else {
        console.warn('Failed to update conversion value');
      }
    });
  }

  // User completed purchase - update based on purchase amount
  function onPurchaseComplete(purchaseAmount) {
    // Track revenue event
    cordova.plugins.SingularCordovaSdk.revenue('USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    var conversionValue = calculateConversionValue(purchaseAmount);
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(conversionValue, function(success) {
      if (success) {
        console.log('Conversion value updated to: ' + conversionValue);
      }
    });
  }

  function calculateConversionValue(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.

// Check if running on iOS
if (device.platform === 'iOS') {
  function updateSKAN4ConversionValue(fineValue, coarseValue, shouldLock) {
    // Map coarse value string to number
    var coarseMap = { low: 0, medium: 1, high: 2 };

    // Update SKAdNetwork 4.0 conversion values
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue],
      shouldLock,
      function(success) {
        if (success) {
          console.log('SKAN 4.0 updated: fine=' + fineValue + ', coarse=' + coarseValue + ', lock=' + shouldLock);
        }
      }
    );
  }

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

  // Example: Premium purchase - lock the value
  function 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.

// Check if running on iOS
if (device.platform === 'iOS') {
  function checkAndUpdateConversionValue() {
    cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(currentValue) {
      if (currentValue !== null) {
        console.log('Current conversion value: ' + currentValue);

        // Only update if current value is below threshold
        if (currentValue < 30) {
          cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(30, function(success) {
            if (success) {
              console.log('Updated conversion value to 30');
            }
          });
        }
      } else {
        console.warn('Conversion value not available');
      }
    });
  }
}

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.

// Create configuration with conversion value handler
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Set up conversion value update handler
singularConfig.withConversionValueUpdatedHandler(function(conversionValue) {
  console.log('Conversion value updated to: ' + conversionValue);

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

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

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

function logConversionValueUpdate(value) {
  // Your analytics logging logic
  console.log('Analytics: SKAN CV = ' + value);
}

function unlockPremiumFeature() {
  // Your custom logic
  console.log('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. Add to Info.plist: Include the NSUserTrackingUsageDescription key in your iOS project's Info.plist file (located in platforms/ios/[YourAppName]/[YourAppName]-Info.plist).
2. Provide clear description: Add a clear explanation of why your app needs tracking permission that will be displayed to users in the ATT prompt.

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

Step 2: Install ATT Support Plugin

Install a third-party Cordova plugin to enable ATT functionality in your app. The cordova-plugin-tracking-transparency plugin provides a JavaScript interface to Apple's ATTrackingManager.

cordova plugin add cordova-plugin-tracking-transparency

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.

// Create configuration with ATT wait timeout
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Wait up to 5 minutes for ATT consent
singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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.

document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Check if running on iOS
  if (device.platform === 'iOS') {
    // Request ATT authorization
    cordova.plugins.idfa.requestPermission().then(function(response) {
      var status = response.tracking;
      console.log('ATT Status:', status);
      // Possible values: 'authorized', 'denied', 'restricted', 'notDetermined'

      // Initialize Singular after ATT prompt
      initializeSingular();
    }).catch(function(error) {
      console.error('ATT Error:', error);
      // Initialize Singular even if ATT fails
      initializeSingular();
    });
  } else {
    // Android - initialize immediately
    initializeSingular();
  }
}

function initializeSingular() {
  // Create configuration with wait timeout
  var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    "YOUR_SDK_KEY",
    "YOUR_SDK_SECRET"
  );

  singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  singularConfig.withLoggingEnabled();

  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(singularConfig);
  console.log('Singular SDK initialized');
}

Understanding the Flow

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

1. Session recording starts: 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. Waiting for consent: The SDK waits for App Tracking Transparency consent to be granted/denied, or the set time to elapse.
3. Data transmission: Once consent is resolved or timeout occurs, the SDK sends the session and any queued events to the Singular server (with or without the IDFA).
4. Attribution begins: Singular then starts the attribution process, taking advantage of the IDFA if it is available.

ATT Scenarios

The following table summarizes the possible scenarios and IDFA availability:

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