Diogo Izele

2026-11-18 · 10 min read

Bridging a Legacy AppDelegate to UIScene on Xcode 27

iOSUIKitNative

I was validating a third-party attribution SDK integration in a large, long-lived iOS app, building it locally with Xcode 27. The project compiled, the binary came out as usual, and the app closed during launch.

The app still ran on the classic UIApplicationDelegate life cycle. Its Objective-C AppDelegate owned the window, built the splash screen in code, and did most of the startup work in application:didFinishLaunchingWithOptions: and applicationDidBecomeActive:. It had never adopted scenes. What follows is the minimal bridge that let me run it locally, the quieter problem that bridge created, and what it still leaves uncovered. It's a workaround for validating an integration, not a migration to the scene life cycle.

Why does it build but not launch?#

UIKit has been warning about this since iOS 18.4. Apple's TN3187 lists the console messages, and on iOS 26 an app without scenes logs: "UIScene lifecycle will soon be required. Failure to adopt will result in an assert in the future."

The same technote sets the deadline. In the next major release following iOS 26, the scene life cycle is required when building with the latest SDK; otherwise, the app won't launch. Xcode 27 ships that SDK, so a clean build is followed by an app that doesn't start.

The distinction matters when debugging. It isn't a compiler error, and it isn't something the attribution SDK requires. The build succeeds, and it's UIKit that enforces scene adoption once the binary runs. With a new SDK in the change set, it's the natural first suspect, but it had nothing to do with this crash.

Adopting scenes also doesn't mean supporting multiple windows. TN3187 says that supporting multiple scenes is encouraged, but only adoption of the scene life cycle is required. The app kept a single scene, with UIApplicationSupportsMultipleScenes set to false.

What scenes change is the split of responsibilities. The app delegate still handles process launch and global setup, such as configuring third-party SDKs in didFinishLaunchingWithOptions:. The UI moves to a scene delegate: UIKit creates a scene, connects it to the app and sends UI life-cycle events, including activation, to that delegate. Both problems in this note came from that second half.

Giving the scene a window#

The first fix had two parts: tell UIKit which class handles the scene, and give that class a window bound to the scene UIKit creates.

Registration lives in the Info.plist under UIApplicationSceneManifest. This is the shape of the entry, reconstructed from the keys involved rather than copied from the project:

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>SceneDelegateProxy</string>
            </dict>
        </array>
    </dict>
</dict>

SceneDelegateProxy is a small scene delegate added for this bridge. The project had two Info.plist files, one of them for a local debug setup, and each one needed the manifest. The app delegate also returned the same configuration in code from application:configurationForConnectingSceneSession:options:, using the role of the session UIKit passed in.

Those aren't two separate requirements. TN3187 presents the manifest as the simplest way to configure scenes, and the delegate method as the option for apps that don't declare the configuration in the Info.plist or need to choose it dynamically. For a single static scene, the manifest can be enough on its own.

Once the scene is registered, UIKit calls scene:willConnectToSession:options: on the delegate, and that's where the window has to be created. Since the splash screen is built in code, this follows the programmatic pattern TN3187 shows. An illustrative version:

- (void)scene:(UIScene *)scene
    willConnectToSession:(UISceneSession *)session
                 options:(UISceneConnectionOptions *)connectionOptions API_AVAILABLE(ios(13.0)) {
    if (![scene isKindOfClass:[UIWindowScene class]]) {
        return;
    }

    UIWindow *window = [[UIWindow alloc] initWithWindowScene:(UIWindowScene *)scene];
    window.rootViewController = [[SplashViewController alloc] init];
    [window makeKeyAndVisible];

    self.window = window;
    [AppDelegate sharedDelegate].window = window;
}

The call that matters is initWithWindowScene:. It isn't initWithFrame: with the screen bounds under another name: it creates the window and associates it with the scene UIKit just connected, so the window becomes part of that scene's windows. The app delegate's old splash setup still has an initWithFrame: fallback, and that fallback doesn't replace this step.

The last line is a project adaptation, not something Apple requires. In the old life cycle, the app delegate's window property was how the rest of the code reached the window, and legacy code still does that. Assigning the same instance there means those call sites find the window that belongs to the scene.

The breakpoint that never hit#

With the window in place, the app got past launch, and the next problem was quieter. The app wraps the SDK in a small helper with two steps: configure, called from didFinishLaunchingWithOptions:, and start, triggered from the app delegate's applicationDidBecomeActive:. After adopting scenes, configure ran at launch, but a breakpoint in start never hit.

Apple's reference for applicationDidBecomeActive: explains it: if the app uses scenes, "UIKit will not call this method," and the replacement is sceneDidBecomeActive:. The first version of the scene delegate only implemented the window callback. There was a path to show the UI, but none that reached the legacy activation routine, so nothing inside applicationDidBecomeActive: ran. That accounts for the missing breakpoint without suspecting a defect in the SDK.

This is the less visible cost of adopting scenes. The launch crash announces itself. A delegate method that stops being called produces no crash and, in this case, no warning: the code just doesn't run, and you only notice when something downstream depended on it.

One detail helps when auditing for this. Apple's docs state that UIKit posts UIApplicationDidBecomeActiveNotification whether or not the app uses scenes, so code that observes the notification keeps working. What goes silent is the delegate method.

Forwarding activation to the legacy method#

The second fix implements sceneDidBecomeActive: in the scene delegate and calls the old method from there:

- (void)sceneDidBecomeActive:(UIScene *)scene API_AVAILABLE(ios(13.0)) {
    [[AppDelegate sharedDelegate] applicationDidBecomeActive:[UIApplication sharedApplication]];
}

UIKit calls the scene delegate, and the scene delegate calls the legacy method as a plain Objective-C message send. The old life cycle doesn't come back: UIKit still never calls the app delegate's activation method, the proxy does it by hand. Because it calls the whole method, it also brings back everything else that lived there, such as icon configuration, loading intents and activating the location manager, not just the SDK's start.

I kept this change in the local workaround, out of the official delivery. Its purpose was to validate the SDK integration without rewriting the app delegate, so the change is limited to this one method.

When verifying it, two levels of evidence are easy to blur. A breakpoint in the helper's start confirms that the forwarding works. A breakpoint on the actual SDK call, inside the helper's asynchronous block, confirms that execution reached the SDK. Neither proves that an event arrived at the vendor's backend, which has to be checked on the vendor's side.

Put together, the launch and activation paths before and after the bridge look like this:

graph TD subgraph Before["Before: app delegate life cycle"] K1[UIKit] --> F1["application:didFinishLaunchingWithOptions:"] K1 --> A1["applicationDidBecomeActive:"] F1 --> C1["SDK configure, window and splash"] A1 --> S1["SDK start and other activation work"] end subgraph After["After: minimal scene bridge"] K2[UIKit] --> F2["application:didFinishLaunchingWithOptions:"] K2 --> W2["scene:willConnectToSession:options:"] K2 --> D2["sceneDidBecomeActive:"] F2 --> C2["SDK configure"] W2 --> V2["Window bound to the scene, splash"] D2 -->|"plain message send"| A2["applicationDidBecomeActive:"] A2 --> S2["SDK start and other activation work"] end

A crash the bridge couldn't fix#

Adopting scenes also surfaced a second crash that the proxy had no way to address. The console showed an NSObjectNotAvailableException, saying explicitly that UIAlertView isn't available to scene-based apps. UIKit's message for this case reads UIAlertView is deprecated and unavailable for UIScene based applications, please use UIAlertController!, and the stack trace pointed at an older internal component that still showed an alert with UIAlertView.

UIAlertView has been deprecated since iOS 9, but the call only became fatal once the app adopted scenes. The fix was to replace it with UIAlertController, presented from a view controller of the window. The presenting part is the real change: UIAlertView displayed itself through show, while UIAlertController is a view controller and needs another one to present it.

No bridge solves this kind of problem, because it isn't a missing callback. Scene adoption makes some legacy APIs unavailable at run time, and the migration reveals them one crash at a time. Searching the codebase, including third-party code, for UIAlertView before adopting scenes is cheaper than finding each call that way.

What the bridge doesn't cover#

The scene delegate forwards exactly one event. It doesn't implement sceneWillResignActive:, sceneDidEnterBackground:, sceneWillEnterForeground:, scene:openURLContexts: or scene:continueUserActivity:. Apple points each of the matching app delegate methods to these scene delegate replacements, the same way it does for activation, so any legacy logic in the app delegate's resign-active, background, foreground, URL and user-activity methods isn't running. Apple's reference also marks those methods, and applicationDidBecomeActive: itself, as deprecated since iOS 26.

The forwarded event has its own catch. sceneDidBecomeActive: isn't a cold-launch hook: it runs again whenever the scene becomes active, for example when the app comes back from the background. The forward preserves the old behavior only as far as applicationDidBecomeActive: tolerates repeated calls, so anything in it that assumes a single run needs a second look.

A real migration means going through every transition and deciding explicitly what belongs to each scene, what stays global in the app delegate, and what must run only once. The bridge makes none of those decisions. It moves one call to a place where UIKit still delivers it, which was enough to validate an SDK integration on Xcode 27 and not much more.

If you're about to build an older app with the latest SDK, start with a list rather than the manifest: every UIApplicationDelegate method the app implements and what each one does. Once the manifest is in place, each method on that list is either moved, forwarded or silently skipped, and, as the missing breakpoint showed, UIKit won't tell you which.