@bacons/apple-targets 0.1.16 → 0.1.18

package/README.md

@@ -405,43 +405,91 @@ let index = defaults?.string(forKey: "myKey")
 
 This plugin makes use of my proprietary Xcode parsing library, [`@bacons/xcode`](https://github.com/evanbacon/xcode). It's mostly typed, very untested, and possibly full of bugs––however, it's still 10x nicer than the alternative.
 
-## Generated App Intents
+## App Clips
 
-You can make any type of App Intent that you'd like with this plugin. However, the majority of app intents simply launch a URL (specifically a universal link for the same app). Expo Router apps have automatic deep linking and websites, meaning you can get to universal links pretty easily. As such, I've built in support for generating link-opening app intents from JSON.
+App Clips leverage the true power of Expo Router, enabling you to link a website and native app to just instantly open the native app on iOS. They're pretty hard to get working though.
 
-These actions will show up in the control center, siri suggestions, Shortcuts, and can be added to the bottom of the lock screen in iOS 18.
+Here are a few notes from my experience building https://pillarvalley.expo.app (open on iOS to test).
 
-```js
+Build the app first, then the website. You can always instantly update the website if it's wrong. This includes the AASA, and metadata.
+
+You may need [this RN patch](https://github.com/facebook/react-native/pull/47000) to get your project working, otherwise it'll crash when launched from Test Flight. Alternatively, you can add App Clip experiences in App Store Connect and it'll launch as expected.
+
+After running prebuild, open the project in Xcode and navigate to the signing tab for each target, this'll ensure the first version of codesigning is absolutely correct. We'll need to adjust EAS Build to ensure it can do this too.
+
+Ensure your App Clip does not have `expo-updates` installed, otherwise it'll fail to build with some cryptic error about React missing in the AppDelegate.
+
+Ensure all the build numbers are the same across the `CURRENT_PROJECT_VERSION` and `CFBundleVersion` (Info.plist) otherwise the app will fail to build.
+
+Ensure you add a `public/.well-known/apple-app-site-association` file to your website and deploy it to the web (`eas deploy --prod`). Here's [an example](https://github.com/EvanBacon/pillar-valley/blob/d5ab82ae04f519310acf4b31aad8d9e22eb3747d/public/.well-known/apple-app-site-association#L27-L29).
+
+The value will be `<Apple Team ID>.<App Clip Bundle ID>`:
+
+```
 {
-  intents: [
-    {
-      // Label that will show up in the control center.
-      label: "Bacon",
-      // Name of an SF Symbol (no custom icons are supported).
-      icon: "laurel.leading",
-      // Universal link to open.
-      url: "https://pillarvalley.netlify.app/settings",
-      // Auxiliary data
-      displayName: "Open Bacon AI",
-      description: "Launch the Bacon AI app.",
-    },
-  ];
+  "appclips": {
+    "apps": ["QQ57RJ5UTD.com.evanbacon.pillarvalley.clip"]
+  }
 }
 ```
 
-You can add multiple intents, they'll be generated during prebuild to the `[target]/_shared/generated-intents.swift` file. This file will have a comment block in it like:
+Add the website URL to your App Clip entitlements (not the main entitlements). Here's an example with `https://pillarvalley.expo.app`:
 
-```swift
-// TODO: These must be added to the WidgetBundle manually. They need to be linked outside of the _shared folder.
-// @main
-// struct exportWidgets: WidgetBundle {
-//     var body: some Widget {
-//         widgetControl0()
-//         widgetControl1()
-//     }
-// }
+```xml
+<key>com.apple.developer.associated-domains</key>
+<array>
+  <string>appclips:pillarvalley.expo.app</string>
+</array>
+```
+
+If this isn't done, then your App Clip will only be able to be launched from the default App Store URL: `https://appclip.apple.com/id?p=com.evanbacon.pillarvalley.clip` (where your App Clip bundle ID will be the ID in the URL).
+
+You should handle redirection from this default URL too with a [`app/+native-intent.ts`](https://docs.expo.dev/router/advanced/native-intent/) file:
+
+```ts
+export function redirectSystemPath({ path }: { path: string }): string {
+  try {
+    // Handle App Clip default page redirection.
+    // If path matches https://appclip.apple.com/id?p=com.evanbacon.pillarvalley.clip (with any query parameters), then redirect to `/` path.
+    const url = new URL(path);
+    if (url.hostname === "appclip.apple.com") {
+      // Redirect to the root path and make the original URL available as a query parameter (optional).
+      return "/?ref=" + encodeURIComponent(path);
+    }
+    return path;
+  } catch {
+    return path;
+  }
+}
+```
+
+You should use `expo-linking` to get URLs related to the App Clip as the upstream React Native Linking has some issues handling App Clips.
+
+When you publish an App Clip, the binary will take about 5 minutes to show up in the App Store (after it's approved) but the App Clip will take more like 25 minutes to show up in your website.
+
+You also need to add some meta tags to your website. These need to run fast so I recommend putting them in your `app/+html.tsx` file:
+
+```js
+<meta
+  name="apple-itunes-app"
+  content={
+    "app-id=1336398804, app-clip-bundle-id=com.evanbacon.pillarvalley.clip, app-clip-display=card"
+  }
+/>
 ```
 
-You should copy the generated intents into your main `WidgetBundle` struct.
+You should also add the `og:image` property using `expo-router/head`. [Learn more](https://developer.apple.com/documentation/appclip/supporting-invocations-from-your-website-and-the-messages-app). It seems like an absolute path to a png image that is `1200×630` in dimensions ([based on this](https://developer.apple.com/library/archive/technotes/tn2444/_index.html)).
+
+```js
+<Head>
+  {/* Required for app clips: */}
+  {/* https://developer.apple.com/documentation/appclip/supporting-invocations-from-your-website-and-the-messages-app */}
+  <meta property="og:image" content="https://pillarvalley.expo.app/og.png" />
+</Head>
+```
+
+You also need a `1800x1200` image for the App Store Connect image preview, so make both of these images around the same time.
+
+Launch App Clips from Test Flight to test deep linking. It doesn't seem like there's any reasonable way to test launching from your website in development. I got this to work once by setting up a local experience in my app's "Settings > Developer" screen, then installing the app, opening the website, deleting the app, then installing the App Clip without the app. You'll mostly need to go with God on this one.
 
-This system is subject to change with the default intended behavior to be that anywhere a SF Symbol can be used to launch a deep link should be populated by this feature.
+You can generate codes using the CLI tool [download here](https://developer.apple.com/download/all/?q=%22app%20clip%22).

package/build/config.d.ts

@@ -59,6 +59,7 @@ export type Entitlements = Partial<{
     "com.apple.developer.driverkit.transport.hid": boolean;
     "com.apple.developer.driverkit.family.audio": boolean;
     "com.apple.developer.shared-with-you": boolean;
+    "com.apple.developer.associated-domains": string[];
 }>;
 export type Config = {
     /**

package/build/withWidget.js

@@ -51,7 +51,7 @@ function kebabToCamelCase(str) {
     });
 }
 const withWidget = (config, props) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     prebuildLogQueue.add(() => warnOnce((0, chalk_1.default) `\nUsing experimental Config Plugin {bold @bacons/apple-targets} that is subject to breaking changes.`));
     // TODO: Magically based on the top-level folders in the `ios-widgets/` folder
     if (props.icon && !/https?:\/\//.test(props.icon)) {
@@ -74,11 +74,54 @@ const withWidget = (config, props) => {
     if (entitlementsJson) {
         // Apply default entitlements that must be present for a target to work.
         const applyDefaultEntitlements = (entitlements) => {
-            var _a, _b;
+            var _a, _b, _c, _d, _e, _f;
             if (props.type === "clip") {
                 entitlements["com.apple.developer.parent-application-identifiers"] = [
                     `$(AppIdentifierPrefix)${config.ios.bundleIdentifier}`,
                 ];
+                // Try to extract the linked website from the original associated domains:
+                const associatedDomainsKey = "com.apple.developer.associated-domains";
+                // If the target doesn't explicitly define associated domains, then try to use the main app's associated domains.
+                if (!entitlements[associatedDomainsKey]) {
+                    const associatedDomains = (_b = (_a = config.ios) === null || _a === void 0 ? void 0 : _a.associatedDomains) !== null && _b !== void 0 ? _b : (_d = (_c = config.ios) === null || _c === void 0 ? void 0 : _c.entitlements) === null || _d === void 0 ? void 0 : _d["com.apple.developer.associated-domains"];
+                    if (!associatedDomains ||
+                        !Array.isArray(associatedDomains) ||
+                        associatedDomains.length === 0) {
+                        warnOnce((0, chalk_1.default) `{yellow [${widget}]} Apple App Clip may require the associated domains entitlement but none were found in the Expo config.\nExample:\n${JSON.stringify({
+                            ios: {
+                                associatedDomains: [`applinks:placeholder.expo.app`],
+                            },
+                        }, null, 2)}`);
+                    }
+                    else {
+                        // Associated domains are found:
+                        // "applinks:pillarvalley.expo.app",
+                        // "webcredentials:pillarvalley.expo.app",
+                        // "activitycontinuation:pillarvalley.expo.app"
+                        const sanitizedUrls = associatedDomains
+                            .map((url) => {
+                            return (url
+                                .replace(/^(appclips|applinks|webcredentials|activitycontinuation):/, "")
+                                // Remove trailing slashes
+                                .replace(/\/$/, "")
+                                // Remove http/https
+                                .replace(/^https?:\/\//, ""));
+                        })
+                            .filter(Boolean);
+                        const unique = [...new Set(sanitizedUrls)];
+                        if (unique.length) {
+                            warnOnce((0, chalk_1.default) `{gray [${widget}]} Apple App Clip expo-target.config.js missing associated domains entitlements in the target config. Using the following defaults:\n${JSON.stringify({
+                                entitlements: {
+                                    [associatedDomainsKey]: [
+                                        `appclips:${unique[0] || "mywebsite.expo.app"}`,
+                                    ],
+                                },
+                            }, null, 2)}`);
+                            // Add anyways
+                            entitlements[associatedDomainsKey] = unique.map((url) => `appclips:${url}`);
+                        }
+                    }
+                }
                 // NOTE: This doesn't seem to be required anymore (Oct 12 2024):
                 // entitlements["com.apple.developer.on-demand-install-capable"] = true;
             }
@@ -89,7 +132,7 @@ const withWidget = (config, props) => {
             !hasDefinedAppGroupsManually &&
                 // And the target is part of a predefined list of types that benefit from app groups that match the main app...
                 target_1.SHOULD_USE_APP_GROUPS_BY_DEFAULT[props.type]) {
-                const mainAppGroups = (_b = (_a = config.ios) === null || _a === void 0 ? void 0 : _a.entitlements) === null || _b === void 0 ? void 0 : _b[APP_GROUP_KEY];
+                const mainAppGroups = (_f = (_e = config.ios) === null || _e === void 0 ? void 0 : _e.entitlements) === null || _f === void 0 ? void 0 : _f[APP_GROUP_KEY];
                 if (Array.isArray(mainAppGroups) && mainAppGroups.length > 0) {
                     // Then set the target app groups to match the main app.
                     entitlements[APP_GROUP_KEY] = mainAppGroups;
@@ -177,22 +220,32 @@ const withWidget = (config, props) => {
     const mainAppBundleId = config.ios.bundleIdentifier;
     const bundleId = ((_d = props.bundleIdentifier) === null || _d === void 0 ? void 0 : _d.startsWith("."))
         ? mainAppBundleId + props.bundleIdentifier
-        : (_e = props.bundleIdentifier) !== null && _e !== void 0 ? _e : `${mainAppBundleId}.${getSanitizedBundleIdentifier(targetName)}`;
+        : (_e = props.bundleIdentifier) !== null && _e !== void 0 ? _e : `${mainAppBundleId}.${props.type === "clip"
+            ? // Use a more standardized bundle identifier for App Clips.
+                "clip"
+            : getSanitizedBundleIdentifier(targetName)}`;
+    const deviceFamilies = ((_f = config.ios) === null || _f === void 0 ? void 0 : _f.isTabletOnly)
+        ? ["tablet"]
+        : ((_g = config.ios) === null || _g === void 0 ? void 0 : _g.supportsTablet)
+            ? ["phone", "tablet"]
+            : ["phone"];
     (0, withXcodeChanges_1.withXcodeChanges)(config, {
         configPath: props.configPath,
         name: targetName,
         cwd: "../" +
             path_1.default.relative(config._internal.projectRoot, path_1.default.resolve(props.directory)),
-        deploymentTarget: (_f = props.deploymentTarget) !== null && _f !== void 0 ? _f : DEFAULT_DEPLOYMENT_TARGET,
+        deploymentTarget: (_h = props.deploymentTarget) !== null && _h !== void 0 ? _h : DEFAULT_DEPLOYMENT_TARGET,
         bundleId,
         icon: props.icon,
-        hasAccentColor: !!((_g = props.colors) === null || _g === void 0 ? void 0 : _g.$accent),
+        orientation: config.orientation,
+        hasAccentColor: !!((_j = props.colors) === null || _j === void 0 ? void 0 : _j.$accent),
+        deviceFamilies,
         // @ts-expect-error: who cares
-        currentProjectVersion: ((_h = config.ios) === null || _h === void 0 ? void 0 : _h.buildNumber) || 1,
+        currentProjectVersion: ((_k = config.ios) === null || _k === void 0 ? void 0 : _k.buildNumber) || 1,
         frameworks: (0, target_1.getFrameworksForType)(props.type).concat(props.frameworks || []),
         type: props.type,
         teamId: props.appleTeamId,
-        exportJs: (_j = props.exportJs) !== null && _j !== void 0 ? _j : 
+        exportJs: (_l = props.exportJs) !== null && _l !== void 0 ? _l : 
         // Assume App Clips are used for React Native.
         props.type === "clip",
     });

package/build/withXcodeChanges.d.ts

@@ -16,5 +16,8 @@ export type XcodeSettings = {
     exportJs?: boolean;
     /** File path to the extension config file. */
     configPath: string;
+    orientation?: "default" | "portrait" | "landscape";
+    deviceFamilies?: DeviceFamily[];
 };
+export type DeviceFamily = "phone" | "tablet";
 export declare const withXcodeChanges: ConfigPlugin<XcodeSettings>;

package/build/withXcodeChanges.js

@@ -441,7 +441,7 @@ function createSafariConfigurationList(project, { name, cwd, bundleId, deploymen
     });
     return configurationList;
 }
-function createAppClipConfigurationList(project, { name, cwd, bundleId, deploymentTarget, currentProjectVersion, hasAccentColor, }) {
+function createAppClipConfigurationList(project, { name, cwd, bundleId, deploymentTarget, currentProjectVersion, hasAccentColor, orientation, deviceFamilies, }) {
     // TODO: Unify AppIcon and AccentColor logic
     const dynamic = {
         CURRENT_PROJECT_VERSION: currentProjectVersion,
@@ -469,15 +469,14 @@ function createAppClipConfigurationList(project, { name, cwd, bundleId, deployme
         PRODUCT_NAME: "$(TARGET_NAME)",
         SWIFT_EMIT_LOC_STRINGS: "YES",
         SWIFT_VERSION: "5.0",
-        TARGETED_DEVICE_FAMILY: "1,2",
+        ...getDeviceFamilyBuildSettings(deviceFamilies),
     };
     const infoPlist = {
         GENERATE_INFOPLIST_FILE: "YES",
         INFOPLIST_KEY_UIApplicationSceneManifest_Generation: "YES",
         INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents: "YES",
         INFOPLIST_KEY_UILaunchScreen_Generation: "YES",
-        INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad: "UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight",
-        INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone: "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight",
+        ...getOrientationBuildSettings(orientation),
     };
     // @ts-expect-error
     const common = {
@@ -518,6 +517,42 @@ function createAppClipConfigurationList(project, { name, cwd, bundleId, deployme
     });
     return configurationList;
 }
+function getOrientationBuildSettings(orientation) {
+    // Try to align the orientation with the main app.
+    if (orientation === "landscape") {
+        return {
+            INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone: "UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight",
+            INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad: "UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight",
+        };
+    }
+    else if (orientation === "portrait") {
+        return {
+            INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone: "UIInterfaceOrientationPortrait",
+            INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad: "UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown",
+        };
+    }
+    return {
+        INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone: "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight",
+        INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad: "UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight",
+    };
+}
+function getDeviceFamilyBuildSettings(deviceFamilies) {
+    if (!deviceFamilies) {
+        return {
+            TARGETED_DEVICE_FAMILY: "1,2",
+        };
+    }
+    const families = [];
+    if (deviceFamilies.includes("phone")) {
+        families.push(1);
+    }
+    if (deviceFamilies.includes("tablet")) {
+        families.push(2);
+    }
+    return {
+        TARGETED_DEVICE_FAMILY: families.join(","),
+    };
+}
 function createConfigurationList(project, { name, cwd, bundleId, deploymentTarget, currentProjectVersion, }) {
     const debugBuildConfig = xcode_1.XCBuildConfiguration.create(project, {
         name: "Debug",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacons/apple-targets",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Generate Apple Targets with Expo Prebuild",
   "main": "build/ExtensionStorage.js",
   "types": "build/ExtensionStorage.d.ts",