# iOS Share Extension Setup Instructions

**Date:** 2025-01-27  
**Purpose:** Step-by-step instructions for setting up the iOS Share Extension in Xcode

## Prerequisites

- Xcode installed
- iOS project already set up with Capacitor
- Access to Apple Developer account (for App Groups)

## Step 1: Create Share Extension Target

1. Open `ios/App/App.xcodeproj` in Xcode
2. In the Project Navigator, select the **App** project (top-level item)
3. Click the **+** button at the bottom of the Targets list
4. Select **iOS** → **Share Extension**
5. Click **Next**
6. Configure:
   - **Product Name:** `TimeSafariShareExtension`
   - **Bundle Identifier:** `app.timesafari.shareextension` (must match main app's bundle ID with `.shareextension` suffix)
   - **Language:** Swift
7. Click **Finish**

## Step 2: Configure Share Extension Files

The following files have been created in `ios/App/TimeSafariShareExtension/`:

- `ShareViewController.swift` - Main extension logic
- `Info.plist` - Extension configuration

**Verify these files exist and are added to the Share Extension target.**

## Step 3: Configure App Groups

App Groups allow the Share Extension and main app to share data.

### For Main App Target:

1. Select the **App** target in Xcode
2. Go to **Signing & Capabilities** tab
3. Click **+ Capability**
4. Select **App Groups**
5. Click **+** to add a new group
6. Enter: `group.app.timesafari`
7. Ensure it's checked/enabled

### For Share Extension Target:

1. Select the **TimeSafariShareExtension** target
2. Go to **Signing & Capabilities** tab
3. Click **+ Capability**
4. Select **App Groups**
5. Click **+** to add a new group
6. Enter: `group.app.timesafari` (same as main app)
7. Ensure it's checked/enabled

**Important:** Both targets must use the **exact same** App Group identifier.

## Step 4: Configure Share Extension Info.plist

The `Info.plist` file should already be configured, but verify:

1. Select `TimeSafariShareExtension/Info.plist` in Xcode
2. Ensure it contains:
   - `NSExtensionPointIdentifier` = `com.apple.share-services`
   - `NSExtensionPrincipalClass` = `$(PRODUCT_MODULE_NAME).ShareViewController`
   - `NSExtensionActivationSupportsImageWithMaxCount` = `1`

## Step 5: Add ShareImageBridge to Main App

1. The file `ios/App/App/ShareImageBridge.swift` has been created
2. Ensure it's added to the **App** target (not the Share Extension target)
3. In Xcode, select the file and check the **Target Membership** in the File Inspector

## Step 6: Build and Test

1. Select the **App** scheme (not the Share Extension scheme)
2. Build and run on a device or simulator
3. Open Photos app
4. Select an image
5. Tap **Share** button
6. Look for **TimeSafari Share** in the share sheet
7. Select it
8. The app should open and navigate to the shared photo view

## Step 7: Troubleshooting

### Share Extension doesn't appear in share sheet

- Verify the Share Extension target builds successfully
- Check that `Info.plist` is correctly configured
- Ensure the extension's bundle identifier follows the pattern: `{main-app-bundle-id}.shareextension`
- Clean build folder (Product → Clean Build Folder)

### App Group access fails

- Verify both targets have the same App Group identifier
- Check that App Groups capability is enabled for both targets
- Ensure you're signed in with a valid Apple Developer account
- For development, you may need to enable App Groups in your Apple Developer account

### Shared image not appearing

- Check Xcode console for errors
- Verify `ShareViewController.swift` is correctly implemented
- Ensure the deep link `timesafari://shared-photo` is being handled
- Check that the native bridge method is being called

### Build errors

- Ensure Swift version matches between targets
- Check that all required frameworks are linked
- Verify deployment targets match between main app and extension

## Step 8: Native Bridge Implementation (TODO)

Currently, the JavaScript code needs a way to call the native `getSharedImageData()` method. This requires one of:

1. **Option A:** Create a minimal Capacitor plugin
2. **Option B:** Use Capacitor's existing bridge mechanisms
3. **Option C:** Expose the method via a custom URL scheme parameter

The current implementation in `main.capacitor.ts` has a placeholder that needs to be completed.

## Next Steps

After the Share Extension is set up and working:

1. Complete the native bridge implementation to read from App Group
2. Test end-to-end flow: Share image → Extension stores → App reads → Displays
3. Implement Android version
4. Add error handling and edge cases

## References

- [Apple Share Extensions Documentation](https://developer.apple.com/documentation/social)
- [App Groups Documentation](https://developer.apple.com/documentation/xcode/configuring-app-groups)
- [Capacitor Native Bridge](https://capacitorjs.com/docs/guides/building-plugins)