@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/levelplay-unity-integration/references/ios-setup.md

@@ -0,0 +1,463 @@
+# iOS-Specific Setup for LevelPlay
+
+## Contents
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [SKAdNetwork Configuration](#skadnetwork-configuration)
+- [App Tracking Transparency (ATT)](#app-tracking-transparency-att)
+- [Privacy Manifest](#privacy-manifest)
+- [Xcode Build Settings](#xcode-build-settings)
+- [Testing on iOS](#testing-on-ios)
+- [Common iOS Issues](#common-ios-issues)
+- [iOS Privacy Checklist](#ios-privacy-checklist)
+- [Version-Specific Notes](#version-specific-notes)
+- [Best Practices](#best-practices)
+
+## Overview
+
+LevelPlay SDK on iOS requires additional configuration beyond the basic Unity integration. This guide covers iOS-specific setup, including SKAdNetwork, App Tracking Transparency (ATT), and privacy manifest requirements.
+
+## Prerequisites
+
+For the current supported Unity, iOS deployment target, and Xcode versions, see the [LevelPlay iOS SDK integration guide](https://docs.unity.com/en-us/grow/levelplay/sdk/ios/sdk-integration).
+
+## SKAdNetwork Configuration
+
+### What is SKAdNetwork?
+
+SKAdNetwork is Apple's privacy-preserving ad attribution framework. It allows advertisers to measure campaign effectiveness without accessing user-level data.
+
+### Setup Steps
+
+LevelPlay SDK automatically includes the required SKAdNetwork IDs in your app's Info.plist during the build process. However, you should verify this after building:
+
+1. Build your Unity project for iOS
+2. Open the generated Xcode project
+3. Check `Info.plist` for the `SKAdNetworkItems` array
+4. Verify it contains multiple SKAdNetwork IDs (format: `XXXX1234abc.skadnetwork`)
+
+**If SKAdNetwork IDs are missing:**
+
+The LevelPlay Unity Package should handle this automatically. If you notice missing IDs:
+- Ensure you're using the latest LevelPlay Unity Package version
+- Check the Unity console for any import warnings
+- Manually add the SKAdNetwork IDs if necessary (see Unity documentation)
+
+### Verifying SKAdNetwork Setup
+
+After building to Xcode, you should see entries like this in Info.plist:
+
+```xml
+<key>SKAdNetworkItems</key>
+<array>
+    <dict>
+        <key>SKAdNetworkIdentifier</key>
+        <string>cstr6suwn9.skadnetwork</string>
+    </dict>
+    <dict>
+        <key>SKAdNetworkIdentifier</key>
+        <string>4fzdc2evr5.skadnetwork</string>
+    </dict>
+    <!-- Many more entries... -->
+</array>
+```
+
+## App Tracking Transparency (ATT)
+
+### What is ATT?
+
+Apple requires ATT authorization before your app tracks users or accesses the device's advertising identifier on iOS 14.5+. Request ATT authorization before calling `LevelPlay.Init()` — this is both an Apple platform requirement and necessary for personalized ads (which also affects fill rate).
+
+### Implementation
+
+ATT requires two parts: a post-build script that writes the permission description string into `Info.plist`, and a native plugin that performs the actual permission request.
+
+### Part 1: Permission Description (Post-Build Script)
+
+Apple requires a user-facing description explaining why your app requests tracking permission. Add it via a post-build script — this is the reliable approach across all Unity versions. The **User Tracking Usage Description** field in Player Settings is not present in Unity 6.
+
+Create `Assets/Editor/iOSPostBuild.cs`:
+
+```csharp
+using UnityEngine;
+using UnityEditor;
+using UnityEditor.Callbacks;
+
+#if UNITY_IOS
+using UnityEditor.iOS.Xcode;
+using System.IO;
+#endif
+
+public class iOSPostBuild
+{
+#if UNITY_IOS
+    [PostProcessBuild(999)]
+    public static void OnPostProcessBuild(BuildTarget target, string buildPath)
+    {
+        if (target != BuildTarget.iOS) return;
+
+        var plistPath = Path.Combine(buildPath, "Info.plist");
+        var plist = new PlistDocument();
+        plist.ReadFromFile(plistPath);
+
+        // Required for ATT prompt — shown to users in the system dialog
+        plist.root.SetString(
+            "NSUserTrackingUsageDescription",
+            "We use tracking to show you relevant ads and support free gameplay."
+        );
+
+        plist.WriteToFile(plistPath);
+        Debug.Log("iOSPostBuild: NSUserTrackingUsageDescription added to Info.plist");
+    }
+#endif
+}
+```
+
+**Customise the description** to match your app's purpose. Apple reviews this text and may reject vague descriptions.
+
+### Part 2: Native Plugin for the Permission Request
+
+Create `Assets/Plugins/iOS/ATTRequester.mm`:
+
+```objc
+#import <AppTrackingTransparency/AppTrackingTransparency.h>
+
+typedef void (*ATTCallback)(int status);
+
+extern "C"
+{
+    // Returns current ATT status without prompting:
+    // 0 = Not Determined, 1 = Restricted, 2 = Denied, 3 = Authorized
+    int _ATT_GetStatus()
+    {
+        if (@available(iOS 14, *))
+        {
+            return (int)[ATTrackingManager trackingAuthorizationStatus];
+        }
+        return 3; // Pre-iOS 14: treat as Authorized
+    }
+
+    // Requests ATT permission and invokes callback with the resulting status.
+    // On pre-iOS 14 devices, immediately calls back with Authorized (3).
+    void _ATT_RequestPermission(ATTCallback callback)
+    {
+        if (@available(iOS 14, *))
+        {
+            [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status)
+            {
+                dispatch_async(dispatch_get_main_queue(), ^{
+                    if (callback) callback((int)status);
+                });
+            }];
+        }
+        else
+        {
+            if (callback) callback(3);
+        }
+    }
+}
+```
+
+**Note:** `dispatch_async(dispatch_get_main_queue(), ...)` returns the callback to Unity's main thread, which is required for safe IL2CPP interop.
+
+### Part 3: Integrating ATT into LevelPlayInitializer
+
+ATT must complete before `LevelPlay.Init()`. Modify your `LevelPlayInitializer.cs` from Step 7 to use a coroutine `Start()`:
+
+```csharp
+using System.Collections;
+using System.Runtime.InteropServices;
+using UnityEngine;
+using Unity.Services.LevelPlay;
+
+public class LevelPlayInitializer : MonoBehaviour
+{
+    [SerializeField] private string appKey;
+
+#if UNITY_IOS && !UNITY_EDITOR
+    private delegate void ATTCallbackDelegate(int status);
+
+    [DllImport("__Internal")] private static extern int _ATT_GetStatus();
+    [DllImport("__Internal")] private static extern void _ATT_RequestPermission(ATTCallbackDelegate callback);
+
+    private const int ATT_NOT_DETERMINED = 0;
+    private static bool _attDone = false;
+
+    [AOT.MonoPInvokeCallback(typeof(ATTCallbackDelegate))]
+    private static void OnATTCallback(int status)
+    {
+        Debug.Log($"ATT: user responded — status {status}");
+        _attDone = true;
+    }
+
+    private IEnumerator RequestATT()
+    {
+        // Skip prompt if user has already responded (e.g. returning user)
+        if (_ATT_GetStatus() != ATT_NOT_DETERMINED)
+        {
+            Debug.Log($"ATT: already determined (status {_ATT_GetStatus()})");
+            yield break;
+        }
+
+        _attDone = false;
+        _ATT_RequestPermission(OnATTCallback);
+        yield return new WaitUntil(() => _attDone);
+    }
+#endif
+
+    void Awake()
+    {
+        DontDestroyOnLoad(gameObject);
+    }
+
+    IEnumerator Start()
+    {
+#if UNITY_IOS && !UNITY_EDITOR
+        // Request ATT before initializing LevelPlay to maximise ad fill rate
+        yield return RequestATT();
+#else
+        yield return null; // Editor / Android: skip ATT
+#endif
+        InitializeLevelPlay();
+    }
+
+    private void InitializeLevelPlay()
+    {
+        // Add privacy settings here before Init (see Step 6.5)
+        LevelPlay.OnInitSuccess += OnInitSuccess;
+        LevelPlay.OnInitFailed += OnInitFailed;
+        LevelPlay.Init(appKey);
+    }
+
+    private void OnInitSuccess(LevelPlayConfiguration config)
+    {
+        Debug.Log("LevelPlay SDK initialized successfully");
+    }
+
+    private void OnInitFailed(LevelPlayInitError error)
+    {
+        Debug.LogError($"LevelPlay initialization failed: {error.ErrorMessage}");
+    }
+
+    void OnDestroy()
+    {
+        LevelPlay.OnInitSuccess -= OnInitSuccess;
+        LevelPlay.OnInitFailed -= OnInitFailed;
+    }
+}
+```
+
+**Key points:**
+- `[AOT.MonoPInvokeCallback]` is required for IL2CPP builds — without it the native callback will crash on device
+- `[DllImport("__Internal")]` binds to the native plugin functions
+- `_ATT_GetStatus()` prevents re-prompting users who have already responded
+- `IEnumerator Start()` with `WaitUntil(() => _attDone)` pauses until the user responds to the ATT dialog
+- `#if UNITY_IOS && !UNITY_EDITOR` guards ensure ATT code only compiles for iOS device builds
+
+## Privacy Manifest
+
+### iOS 17+ Requirements
+
+Apple requires apps to declare data types collected and the reasons for using certain APIs. LevelPlay SDK includes a privacy manifest, but you should be aware of what it declares.
+
+### What LevelPlay Declares
+
+The LevelPlay SDK's privacy manifest typically declares:
+- **Data Collection**: Device identifiers (IDFA), usage data, location (if used)
+- **Required Reason APIs**: User defaults, file timestamp, system boot time, disk space
+- **Tracking**: Yes (for personalized advertising)
+
+### Your App's Privacy Manifest
+
+Ensure your app's privacy manifest (if you have one) aligns with LevelPlay's declarations:
+
+1. Check for `PrivacyInfo.xcprivacy` in your Xcode project
+2. Verify it includes LevelPlay's data types
+3. Update your App Store privacy declarations accordingly
+
+## Xcode Build Settings
+
+### Required iOS Capabilities
+
+LevelPlay SDK requires certain capabilities to function properly:
+
+1. Open your Xcode project after building from Unity
+2. Select your target > **Signing & Capabilities**
+3. Verify these frameworks are included (LevelPlay should add them automatically):
+   - **AdSupport.framework**: For IDFA access
+   - **AppTrackingTransparency.framework**: For ATT (iOS 14+)
+   - **StoreKit.framework**: For SKAdNetwork
+
+### App Transport Security (ATS) Configuration
+
+**No ATS configuration is needed. Leave App Transport Security at its iOS default.** With ATS on, the LevelPlay SDK tells the auction to return secure ads only, so ads load without any `Info.plist` changes.
+
+**Do not add ATS exceptions for ads:**
+- **Never set `NSAllowsArbitraryLoads` to `true`.** It turns off transport security for every connection the app makes, including its own backend and login traffic, not just ads, and App Review commonly rejects it without a justification. If the user asks for it, explain this and leave ATS at the default.
+- **Don't set `NSAllowsArbitraryLoadsInWebContent` either.** On its own it makes the SDK request insecure ads, which iOS still blocks outside web views.
+- **Don't add `NSExceptionDomains` entries for ad networks.** The SDK doesn't read them.
+
+**Expected validation warning:** LevelPlay's integration validation reports "App Transport Security settings MISSING" when these keys are absent. That warning is expected with the default configuration. Don't resolve it by adding `NSAllowsArbitraryLoads`.
+
+### Recommended Xcode Build Settings
+
+In Xcode, verify these settings:
+
+- **Deployment Target**: see the [LevelPlay iOS SDK integration guide](https://docs.unity.com/en-us/grow/levelplay/sdk/ios/sdk-integration) for the currently supported minimum
+- **Enable Bitcode**: No
+- **Other Linker Flags**: Should include `-ObjC` (automatically added by Unity)
+
+## Testing on iOS
+
+### Test Device Setup
+
+1. Build and run on a physical iOS device (simulators have limitations)
+2. For ATT testing:
+   - Go to **Settings > Privacy & Security > Tracking**
+   - You can reset ATT prompt status by going to **Settings > General > Transfer or Reset iPhone > Reset > Reset Location & Privacy**
+
+### Integration Validation
+
+After building to iOS:
+
+```csharp
+void Start()
+{
+    #if UNITY_IOS
+    LevelPlay.OnInitSuccess += OnInitSuccess;
+    LevelPlay.OnInitFailed += OnInitFailed;
+    LevelPlay.Init("YOUR_APP_KEY");
+    #endif
+}
+
+void OnInitSuccess(LevelPlayConfiguration config)
+{
+    Debug.Log("LevelPlay initialized successfully on iOS");
+}
+
+void OnInitFailed(LevelPlayInitError error)
+{
+    Debug.LogError($"LevelPlay init failed on iOS: {error.ErrorMessage}");
+}
+```
+
+Check the Xcode console for initialization output. Look for:
+- ✅ "LevelPlay initialized successfully on iOS"
+- ❌ Any initialization errors or warnings
+
+### Testing Ads on iOS
+
+1. **Test mode**: Enable test mode in your LevelPlay dashboard
+2. **Real ads**: Disable test mode and test with real ads (use low-value test account)
+3. **Different ATT states**: Test with:
+   - ATT granted (tracking allowed)
+   - ATT denied (tracking disallowed)
+   - ATT restricted (device-level restriction)
+
+## Common iOS Issues
+
+### Issue: ATT prompt not showing
+
+**Causes:**
+- Missing `NSUserTrackingUsageDescription` in Info.plist
+- ATT already determined on device
+- Testing on iOS Simulator (use real device)
+
+**Solutions:**
+- Verify `iOSPostBuild.cs` exists in `Assets/Editor/` and ran successfully (check console for "iOSPostBuild: NSUserTrackingUsageDescription added to Info.plist")
+- Reset privacy settings on device: **Settings > General > Transfer or Reset iPhone > Reset > Reset Location & Privacy**
+- Test on physical iOS device
+
+### Issue: Ads not loading after ATT denial
+
+**This is expected behavior:**
+- When users deny tracking, personalized ads are limited
+- Non-personalized ads may still serve
+- Revenue may be lower for users who deny tracking
+
+**What to do:**
+- Continue with LevelPlay initialization regardless of ATT response
+- Don't block features if tracking is denied
+- Comply with Apple's guidelines
+
+### Issue: SKAdNetwork IDs missing
+
+**Causes:**
+- Outdated LevelPlay package
+- Custom build postprocessor conflict
+- Manual Info.plist modifications
+
+**Solutions:**
+- Update to latest LevelPlay Unity Package
+- Check for conflicting build scripts
+- Let LevelPlay handle SKAdNetwork IDs automatically
+
+### Issue: App rejected for privacy reasons
+
+**Common causes:**
+- Missing privacy manifest declarations
+- Incorrect ATT usage description
+- Data collection not properly declared
+
+**Solutions:**
+- Review Apple's App Privacy Details guidelines
+- Ensure ATT description is clear and user-friendly
+- Declare all data types collected in App Store Connect
+- Keep LevelPlay SDK updated (includes privacy manifest updates)
+
+## iOS Privacy Checklist
+
+Before submitting to App Store:
+
+- [ ] ATT prompt implemented: `ATTRequester.mm` in `Assets/Plugins/iOS/`, `iOSPostBuild.cs` in `Assets/Editor/`, `LevelPlayInitializer.cs` updated to `IEnumerator Start()`
+- [ ] SKAdNetwork IDs included in Info.plist
+- [ ] Privacy manifest present and accurate
+- [ ] App Store privacy declarations filled out
+- [ ] Data collection disclosed transparently
+- [ ] Tested on real iOS devices
+- [ ] Verified ads load and show correctly
+- [ ] Tested both ATT granted and denied scenarios
+- [ ] No tracking of users who denied ATT
+- [ ] Compliant with Apple's advertising policies
+
+## Additional Resources
+
+### Apple Documentation
+- [App Tracking Transparency Guide](https://developer.apple.com/documentation/apptrackingtransparency)
+- [SKAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork)
+- [User Privacy and Data Use](https://developer.apple.com/app-store/user-privacy-and-data-use/)
+
+### LevelPlay Documentation
+- Refer to LevelPlay's Unity documentation for the latest iOS setup requirements
+- Check for SDK update notes regarding iOS changes
+- Review LevelPlay's privacy manifest documentation
+
+## Version-Specific Notes
+
+### iOS 14.5+
+- ATT required for IDFA access
+- Personalized ads limited without tracking permission
+
+### iOS 15+
+- Custom product pages support
+- App privacy report visible to users
+
+### iOS 16+
+- Additional privacy enhancements
+- More granular location privacy
+
+### iOS 17+
+- Privacy manifest required
+- Increased API usage disclosure requirements
+- SDK transparency requirements
+
+## Best Practices
+
+1. **Request ATT at an appropriate time**: Not immediately on first launch, but before showing ads
+2. **Explain value to users**: Help users understand why you're requesting tracking
+3. **Respect user choice**: Never block app functionality if tracking is denied
+4. **Keep SDK updated**: Apple requirements change frequently
+5. **Test thoroughly**: Test on real devices with different iOS versions
+6. **Monitor metrics**: Track opt-in rates and ad performance post-iOS 14.5
+7. **Stay compliant**: Follow Apple's Human Interface Guidelines for ATT
+8. **Prepare for rejections**: Have documentation ready if Apple requests clarification