141 lines
4.8 KiB
Markdown
141 lines
4.8 KiB
Markdown
# 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.share`
|
|
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.share` (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)
|
|
|