Add README for stand-alone-example

apps/stand-alone-example/README.md

@@ -0,0 +1,207 @@
+# Using A Vehicle-App Stand-Alone with React Native
+
+This example focuses on launching a vehicle app in stand-alone mode, i.e.
+directly on the CarPlay- or AndroidAuto-client without having the React
+Native app running on the phone.
+
+For setup, follow the steps outlined in the regular example app (which syncs
+the CarPlay-screens with the phone app screens), then pay attention to the
+changes required for the stand-alone setup outlined in this app.
+
+## iOS / CarPlay
+
+Independently of whether the app was started on the phone (PhoneScene) or on
+the CarPlay-client (CarScene), the first code to run natively will always be
+the AppDelegates `application:didFinishLaunchingWithOptions:` method.
+A React Native app usually calls the super-method in its AppDelegate, which is
+implemented in React Native's own `RCTAppDelegate`. The problem with this is
+that `RCTAppDelegate` assumes a phone usage and creates a
+`rootViewController` along with a window for the app to be displayed in.
+This leads to problems when launching the app on the CarPlay-client first,
+since CarPlay does not require a rootViewController or a window to display
+its views.
+
+The key to solving this problem is to split the app initialization logic
+into PhoneScene and CarScene (which are both subclasses of `UIResponder`)
+and only run the code required to set up the React Native bridge in the
+AppDelegate. We can achieve this by not calling the super-method in
+`application:didFinishLaunchingWithOptions:` but instead create and call a
+custom init method. Here's how:
+
+### 1. Add RCTAppSetupUtils to your BridgingHeader
+
+To be able to call app setup utilities provided by React Native in your
+AppDelegate-implementation, you need to add an import for `RCTAppSetupUtils`
+in your `BridgingHeader.h`:
+
+```objc
+#import <React/RCTAppSetupUtils.h>
+```
+
+### 2. Adjust your AppDelegate
+
+In `AppDelegate.swift`, delete your calls to
+`super.application(application, didFinishLaunchingWithOptions: launchOptions)`
+and `createRootView` and instead create a new method`initAppFromScene`.
+This method will be called from your scenes for app initialization.
+In it, replicate the `application:didFinishLaunchingWithOptions:` method
+from `RCTAppDelegate`except for the `rootViewController` and window creation.
+
+Here is an example implementation based on the `RCTAppDelegate`
+implementation in React Native version 0.71.13:
+
+```swift
+// ios/AppDelegate.swift
+
+@main
+class AppDelegate: RCTAppDelegate {
+
+ var rootView: UIView?;
+ var concurrentRootEnabled = true;
+
+ static var shared: AppDelegate { return UIApplication.shared.delegate as! AppDelegate }
+
+ override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
+ moduleName = "YourModuleName"
+ return true
+ }
+
+ func initAppFromScene(connectionOptions: UIScene.ConnectionOptions?) {
+ // If bridge has already been initiated by another scene, there's nothing to do here
+ if (self.bridge != nil) {
+ return;
+ }
+
+ let enableTM = false;
+#if RCT_NEW_ARCH_ENABLED
+ enableTM = self.turboModuleEnabled;
+#endif
+
+ let application = UIApplication.shared;
+ RCTAppSetupPrepareApp(application, enableTM);
+
+ if (self.bridge == nil) {
+ self.bridge = super.createBridge(
+ with: self,
+ launchOptions: self.connectionOptionsToLaunchOptions(connectionOptions: connectionOptions)
+ )
+ }
+
+#if RCT_NEW_ARCH_ENABLED
+ _contextContainer = UnsafeMutablePointer<ContextContainer>.allocate(capacity: 1)
+ _contextContainer?.initialize(to: ContextContainer())
+ _reactNativeConfig = UnsafeMutablePointer<EmptyReactNativeConfig>.allocate(capacity: 1)
+ _reactNativeConfig?.initialize(to: EmptyReactNativeConfig())
+ _contextContainer?.pointee.insert("ReactNativeConfig", _reactNativeConfig)
+ self.bridgeAdapter = RCTSurfacePresenterBridgeAdapter(bridge: self.bridge, contextContainer: _contextContainer)
+ self.bridge?.surfacePresenter = self.bridgeAdapter?.surfacePresenter
+#endif
+
+ let initProps = self.prepareInitialProps();
+ self.rootView = self.createRootView(with: self.bridge, moduleName: self.moduleName, initProps: initProps)
+
+ if #available(iOS 13.0, *) {
+ self.rootView!.backgroundColor = UIColor.systemBackground
+ } else {
+ self.rootView!.backgroundColor = UIColor.white
+ }
+ }
+
+ /**
+ Convert ConnectionOptions to LaunchOptions
+ When Scenes are used, the launchOptions param in "didFinishLaunchingWithOptions" is always null, and the expected data is provided through SceneDelegate's ConnectionOptions instead but in a different format
+ */
+ func connectionOptionsToLaunchOptions(connectionOptions: UIScene.ConnectionOptions?) -> [UIApplication.LaunchOptionsKey: Any] {
+ var launchOptions: [UIApplication.LaunchOptionsKey: Any] = [:];
+
+ if let options = connectionOptions {
+ if options.notificationResponse != nil {
+ launchOptions[UIApplication.LaunchOptionsKey.remoteNotification] = options.notificationResponse?.notification.request.content.userInfo;
+ }
+
+ if !options.userActivities.isEmpty {
+ let userActivity = options.userActivities.first;
+ let userActivityDictionary = [
+ "UIApplicationLaunchOptionsUserActivityTypeKey": userActivity?.activityType as Any,
+ "UIApplicationLaunchOptionsUserActivityKey": userActivity!
+ ] as [String : Any];
+ launchOptions[UIApplication.LaunchOptionsKey.userActivityDictionary] = userActivityDictionary;
+ }
+ }
+
+ return launchOptions;
+ }
+```
+
+### 2. Adjust the Phone Scene
+
+In `PhoneScene.swift`, initialize the app for running on the phone.
+This of course needs to work like before, since adding
+CarPlay should not affect your regular app in any way.
+
+Here, after calling the new `initAppFromScene`-method with the
+connectionOptions provided to the scene, add the rest of the phone-app
+initialization logic from `RCTAppDelegate`:
+Create a new `rootViewController` for the AppDelegate's `rootView`, create a
+window with the `windowScene` and set the `rootViewController` as the
+windows `rootViewController`.
+Finally, make the window key and visible:
+
+```swift
+// ios/PhoneScene.swift
+import Foundation
+import UIKit
+import SwiftUI
+
+class PhoneSceneDelegate: UIResponder, UIWindowSceneDelegate {
+ var window: UIWindow?
+ func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
+ guard let appDelegate = (UIApplication.shared.delegate as? AppDelegate) else { return }
+ guard let windowScene = (scene as? UIWindowScene) else { return }
+
+ appDelegate.initAppFromScene(connectionOptions: connectionOptions)
+
+ let rootViewController = UIViewController()
+ rootViewController.view = appDelegate.rootView;
+
+ let window = UIWindow(windowScene: windowScene)
+ window.rootViewController = rootViewController
+ self.window = window
+ window.makeKeyAndVisible()
+ }
+}
+```
+
+### 3. Adjust the Car Scene
+
+In `CarScene.swift`, make sure to also call the new
+`initAppFromScene`-method (this time without connectionOptions) in
+order to initialize the React Native setup, bridge and `rootView` creation.
+This will launch your app as a headless React Native application in the
+background, which will initialize your react-native-carplay-code.
+
+```swift
+// ios/CarScene.swift
+
+import Foundation
+import CarPlay
+
+class CarSceneDelegate: UIResponder, CPTemplateApplicationSceneDelegate {
+ func templateApplicationScene(_ templateApplicationScene: CPTemplateApplicationScene,
+ didConnect interfaceController: CPInterfaceController) {
+ guard let appDelegate = (UIApplication.shared.delegate as? AppDelegate) else { return }
+
+ appDelegate.initAppFromScene(connectionOptions: nil)
+
+ RNCarPlay.connect(with: interfaceController, window: templateApplicationScene.carWindow);
+ }
+
+ func templateApplicationScene(_ templateApplicationScene: CPTemplateApplicationScene, didDisconnectInterfaceController interfaceController: CPInterfaceController) {
+ RNCarPlay.disconnect()
+ }
+}
+```
+
+## Android / AndroidAuto
+
+### TODO: Add AndroidAuto Stand-Alone Example with documentation