feat(mobile): continue media screens with Apple Handoff

This commit is contained in:
joshuafhiggins committed 2026-11-05 16:53:42 -05:00 Verified
1 parent 01a7325975
commit 1f4c196584
10 files changed
+227 -2

No files matched your search

+31
View File
@@ -42,3 +42,34 @@ Native sharing supplies media titles and artwork through iOS link metadata and A
thumbnail, while sharing the original HTTPS URL. Receiving apps control whether
they display previews. If artwork cannot load, the URL is still shared. Existing
builds without the native sharing module fall back to URL-only sharing.
### Apple Handoff
The native app advertises the current album, artist, or playlist screen using
`NSUserActivity`, with the custom activity type `<bundle identifier>.media`.
Leaving these screens or signing out invalidates the activity. Only the media
route and source server address travel with it, with no playback, queue, tokens,
or web URL. Receiving compares the source with the configured server and uses
the existing navigation and sign-in flow. A missing or different configured
server shows "This activity belongs to a different oTunes server." Setup is
never prefilled or switched by Handoff.
This repository has one UIKit-based Expo app, not a separate AppKit or Mac
Catalyst target. On macOS this implementation covers the iPhone/iPad app running
on Apple silicon, if the signed app is made available there. The same native
subscriber publishes and receives on that runtime. Intel Macs and a standalone
AppKit app are not supported by this app architecture.
Install a new native build on each device. Apps must be signed with the same
Apple developer Team ID and declare the same activity type. Variants deliberately
use different activity types so development, preview, and production do not
continue each other's activities. Self-hosters need no associated domains, AASA
files, per-server signing configuration, or web Handoff. Server addresses are
used only for comparison on receipt.
Apple also requires nearby devices signed into the same Apple Account, Handoff
enabled, and Wi-Fi and Bluetooth enabled. See Apple's
[Handoff implementation requirements](https://developer.apple.com/documentation/foundation/implementing-handoff-in-your-app).
Verify on physical devices in both directions, including a cold launch, signed-out
receipt, a different configured server, and leaving a media screen. A simulator
or a TypeScript check cannot establish that cross-device Handoff works.
+4
View File
@@ -36,6 +36,10 @@ export default ({ config }: ConfigContext): ExpoConfig => {
...config.ios,
bundleIdentifier: `${config.ios!.bundleIdentifier}${suffix}`,
icon: `./assets/${composer}.icon`,
infoPlist: {
...config.ios?.infoPlist,
NSUserActivityTypes: [`com.abunchofknowitalls.otunes${suffix}.media`],
},
},
android: {
...config.android,
+5 -2
View File
@@ -1,6 +1,9 @@
import { loadServerConfig, parseServerHostname } from "@/lib/server-config"
import { secureGetItem } from "@/lib/auth-storage"
import { rememberIncomingMediaLink } from "@/lib/incoming-media-link"
import {
isMediaRoute,
rememberIncomingMediaLink,
} from "@/lib/incoming-media-link"
import { showError } from "@/lib/toast"
export async function redirectSystemPath({
@@ -28,7 +31,7 @@ export async function redirectSystemPath({
target.username ||
target.password ||
new URL(server.serverUrl).origin !== target.origin ||
!/^\/(album|artist|playlist)\/[a-zA-Z0-9_-]+$/.test(target.pathname)
!isMediaRoute(target.pathname)
) {
return "/"
}
+3
View File
@@ -9,6 +9,8 @@ import { Toaster } from "@/components/ui/toaster"
import { ConvexAppProvider } from "@/contexts/convex-app"
import { ServerConfigProvider, useServerConfig } from "@/contexts/server-config"
import { HandoffBridge } from "@/components/handoff-bridge"
const navigationTheme = {
...DarkTheme,
colors: { ...DarkTheme.colors, background: "#000", card: "#000" },
@@ -56,6 +58,7 @@ export default function RootLayout() {
<ConvexAppProvider>
<StatusBar style={isDark ? "light" : "dark"} />
<ThemeProvider value={navigationTheme}>
<HandoffBridge />
<RootNavigator />
</ThemeProvider>
<Toaster />
+81
View File
@@ -0,0 +1,81 @@
import { useConvexAuth } from "@convex-dev/auth/react"
import { requireOptionalNativeModule, type NativeModule } from "expo"
import { usePathname } from "expo-router"
import { useEffect } from "react"
import { Platform } from "react-native"
import { useServerConfig } from "@/contexts/server-config"
import {
isMediaRoute,
rememberIncomingMediaLink,
} from "@/lib/incoming-media-link"
import { showError } from "@/lib/toast"
type Activity = { server: string; route: string }
declare class HandoffModule extends NativeModule<{ onActivity: () => void }> {
takeActivity(): Promise<Activity | null>
publish(server: string | null, route: string | null): Promise<void>
}
const handoff =
Platform.OS === "ios"
? requireOptionalNativeModule<HandoffModule>("Handoff")
: null
export function HandoffBridge() {
const { config, isLoading } = useServerConfig()
const auth = useConvexAuth()
const pathname = usePathname()
useEffect(() => {
if (!handoff || isLoading) return
let active = true
async function receive() {
const activity = await handoff!.takeActivity()
if (!active || !activity) return
try {
const source = new URL(activity.server)
if (!config || source.origin !== new URL(config.serverUrl).origin) {
showError("This activity belongs to a different oTunes server.")
return
}
if (
!["http:", "https:"].includes(source.protocol) ||
source.username ||
source.password ||
!isMediaRoute(activity.route)
)
return
rememberIncomingMediaLink(
`/(app)/(tabs)/home${activity.route}`,
source.origin
)
} catch {
// Ignore malformed activities without navigating or changing servers.
}
}
const subscription = handoff.addListener("onActivity", () => {
void receive()
})
void receive()
return () => {
active = false
subscription.remove()
}
}, [config, isLoading])
useEffect(() => {
if (!handoff) return
const route = pathname.replace(/^\/(home|search|library)/, "")
const canPublish = config && auth?.isAuthenticated && isMediaRoute(route)
void handoff.publish(
canPublish ? config.serverUrl : null,
canPublish ? route : null
)
return () => {
void handoff.publish(null, null)
}
}, [config, auth?.isAuthenticated, pathname])
return null
}
+5
View File
@@ -28,3 +28,8 @@ export function rememberIncomingMediaLink(path: string, serverOrigin: string) {
pendingLink = { path, serverOrigin }
for (const listener of listeners) listener()
}
// Shared by native links and Handoff. Only concrete media screens are routable.
export function isMediaRoute(path: string) {
return /^\/(album|artist|playlist)\/[a-zA-Z0-9_-]+$/.test(path)
}
@@ -0,0 +1,7 @@
{
"platforms": ["apple"],
"apple": {
"modules": ["HandoffModule"],
"appDelegateSubscribers": ["HandoffAppDelegateSubscriber"]
}
}
@@ -0,0 +1,16 @@
Pod::Spec.new do |s|
s.name = 'Handoff'
s.version = '1.0.0'
s.summary = 'Native media screen Handoff for oTunes'
s.description = s.summary
s.license = { :type => 'MIT' }
s.author = 'oTunes'
s.homepage = 'https://otunes.abunchofknowitalls.com'
s.platforms = { :ios => '16.4' }
s.swift_version = '5.9'
s.source = { :git => '' }
s.static_framework = true
s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
s.dependency 'ExpoModulesCore'
s.source_files = '**/*.swift'
end
@@ -0,0 +1,70 @@
import ExpoModulesCore
import UIKit
// Retain the latest continuation until JS is mounted, including cold launches.
private enum HandoffState {
static var activity: NSUserActivity?
static var pending: [String: String]?
static var notify: (() -> Void)?
static var activityType: String {
"\(Bundle.main.bundleIdentifier!).media"
}
}
public final class HandoffAppDelegateSubscriber: ExpoAppDelegateSubscriber {
public func application(
_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
guard userActivity.activityType == HandoffState.activityType,
let server = userActivity.userInfo?["server"] as? String,
let route = userActivity.userInfo?["route"] as? String
else { return false }
HandoffState.pending = ["server": server, "route": route]
HandoffState.notify?()
return true
}
}
public final class HandoffModule: Module {
public func definition() -> ModuleDefinition {
Name("Handoff")
Events("onActivity")
OnStartObserving {
HandoffState.notify = { [weak self] in self?.sendEvent("onActivity") }
if HandoffState.pending != nil { HandoffState.notify?() }
}
OnStopObserving { HandoffState.notify = nil }
AsyncFunction("takeActivity") { () -> [String: String]? in
defer { HandoffState.pending = nil }
return HandoffState.pending
}.runOnQueue(.main)
AsyncFunction("publish") { (server: String?, route: String?) in
HandoffState.activity?.invalidate()
HandoffState.activity = nil
guard let server, let route else { return }
let activity = NSUserActivity(activityType: HandoffState.activityType)
activity.title = "oTunes"
activity.userInfo = ["server": server, "route": route]
activity.requiredUserInfoKeys = ["server", "route"]
activity.isEligibleForHandoff = true
activity.isEligibleForSearch = false
activity.isEligibleForPublicIndexing = false
HandoffState.activity = activity
activity.becomeCurrent()
}.runOnQueue(.main)
OnDestroy {
DispatchQueue.main.async {
HandoffState.activity?.invalidate()
HandoffState.activity = nil
HandoffState.notify = nil
}
}
}
}
+5
View File
@@ -0,0 +1,5 @@
{
"name": "otunes-handoff",
"version": "1.0.0",
"private": true
}