Supporting SKAdNetwork

SKAdNetwork is Apple's privacy-focused attribution framework for iOS app install campaigns. Starting with Unity SDK version 4.0.17, SKAdNetwork is enabled 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.

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.

Legacy SDK Versions

If you're using a Unity SDK version older than 4.0.17, you need to manually enable SKAdNetwork support using one of the following methods.

using UnityEngine;
using Singular;

public class AppInitializer : MonoBehaviour
{
    void Awake()
    {
        // Register for SKAdNetwork attribution
        SingularSDK.SkanRegisterAppForAdNetworkAttribution();
    }
}

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.

public static bool SkanUpdateConversionValue(int value)

using UnityEngine;
using Singular;

public class ConversionTracker : MonoBehaviour
{
    void OnUserSignUp()
    {
        // Track the sign-up event
        SingularSDK.Event("SignUp");

        // Update SKAN conversion value to 7
        bool success = SingularSDK.SkanUpdateConversionValue(7);

        if (success)
        {
            Debug.Log("Conversion value updated successfully");
        }
        else
        {
            Debug.LogWarning("Failed to update conversion value");
        }
    }

    void OnPurchaseComplete(float purchaseAmount)
    {
        // Track revenue event
        SingularSDK.Revenue("USD", purchaseAmount);

        // Update conversion value based on purchase tier
        int conversionValue = CalculateConversionValue(purchaseAmount);
        SingularSDK.SkanUpdateConversionValue(conversionValue);
    }

    int CalculateConversionValue(float 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
    }
}

public static int? SkanGetConversionValue()

using UnityEngine;
using Singular;

public class ConversionMonitor : MonoBehaviour
{
    void CheckConversionValue()
    {
        int? currentValue = SingularSDK.SkanGetConversionValue();

        if (currentValue.HasValue)
        {
            Debug.Log($"Current conversion value: {currentValue.Value}");

            // Only update if current value is below threshold
            if (currentValue.Value < 30)
            {
                SingularSDK.SkanUpdateConversionValue(30);
            }
        }
        else
        {
            Debug.LogWarning("Conversion value not available");
        }
    }
}

public static void SetConversionValueUpdatedHandler(SingularConversionValueUpdatedHandler handler)

using UnityEngine;
using Singular;

public class ConversionValueMonitor : MonoBehaviour, SingularConversionValueUpdatedHandler
{
    void Awake()
    {
        // Register this class as the conversion value update handler
        SingularSDK.SetConversionValueUpdatedHandler(this);
    }

    // This method is called whenever the conversion value is updated
    public void OnConversionValueUpdated(int newValue)
    {
        Debug.Log($"Conversion value updated to: {newValue}");

        // Log the update to your analytics
        LogConversionValueUpdate(newValue);

        // Trigger any app-specific behavior
        if (newValue >= 50)
        {
            UnlockPremiumFeature();
        }
    }

    void LogConversionValueUpdate(int value)
    {
        // Your analytics logging logic
        Debug.Log($"Analytics: SKAN CV = {value}");
    }

    void UnlockPremiumFeature()
    {
        // Your custom logic
        Debug.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.

SDK Initialization Timing

The timing of SDK initialization relative to the ATT prompt is critical. If the SDK initializes and sends the first session before the user responds to the ATT prompt, the IDFA won't be captured, resulting in less accurate attribution.

Why Delay Initialization?

By default, the Singular SDK sends a session immediately upon initialization. When this session comes from a new device, it triggers Singular's attribution process using only the data available at that moment. If the user hasn't yet responded to the ATT prompt, the IDFA will be unavailable, and the attribution will be based on less accurate methods.

Configure SDK Wait Timeout

Configure the SDK to wait for the user's ATT response before initializing by setting the waitForTrackingAuthorizationWithTimeoutInterval property. This delay gives the user time to respond to the ATT prompt while preventing indefinite delays if the prompt is not shown.

Configuration Steps

1. Select the SingularSDKObject in your Unity scene hierarchy.
2. In the Inspector pane, locate the waitForTrackingAuthorizationWithTimeoutInterval property.
3. Set the value based on your ATT implementation:
   • Showing ATT prompt: Set to 300 (5 minutes)
   • Not showing ATT prompt: Leave at 0 (no wait)

Implementation Example

Here's how to implement ATT in your Unity app with proper SDK initialization timing.

using UnityEngine;
using Singular;

#if UNITY_IOS
using Unity.Advertisement.IosSupport;
#endif

public class ATTManager : MonoBehaviour
{
    void Start()
    {
#if UNITY_IOS
        // Check ATT status on iOS
        RequestTrackingAuthorization();
#else
        // Initialize SDK immediately on non-iOS platforms
        InitializeSingularSDK();
#endif
    }

#if UNITY_IOS
    void RequestTrackingAuthorization()
    {
        // Check current authorization status
        var status = ATTrackingStatusBinding.GetAuthorizationTrackingStatus();

        if (status == ATTrackingStatusBinding.AuthorizationTrackingStatus.NOT_DETERMINED)
        {
            // Request authorization if not yet determined
            ATTrackingStatusBinding.RequestAuthorizationTracking(OnATTResponse);
        }
        else
        {
            // Status already determined, initialize SDK
            InitializeSingularSDK();
        }
    }

    void OnATTResponse(int status)
    {
        // Log the user's response
        switch (status)
        {
            case (int)ATTrackingStatusBinding.AuthorizationTrackingStatus.AUTHORIZED:
                Debug.Log("User authorized tracking - IDFA will be available");
                break;
            case (int)ATTrackingStatusBinding.AuthorizationTrackingStatus.DENIED:
                Debug.Log("User denied tracking - IDFA not available");
                break;
            case (int)ATTrackingStatusBinding.AuthorizationTrackingStatus.RESTRICTED:
                Debug.Log("Tracking restricted by device settings");
                break;
            default:
                Debug.Log("ATT status unknown");
                break;
        }

        // Initialize SDK after receiving response
        InitializeSingularSDK();
    }
#endif

    void InitializeSingularSDK()
    {
        // SDK is initialized with waitForTrackingAuthorizationWithTimeoutInterval
        // configured in the Inspector, so it will wait for ATT if needed
        // If Initialize On Awake is disabled, manually initialize here
        // SingularSDK.InitializeSingularSDK();

        Debug.Log("Singular SDK initialized");
    }
}

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.
• Custom messaging: Customize your ATT prompt message in your Info.plist file using the NSUserTrackingUsageDescription key to clearly explain your tracking purpose.
• 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.

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