Symptom
On iOS Safari, the WebXR AR button that should open Needle Go (App Clip) via location.href often needs two taps: the first does nothing; the second works.
Root cause
NeedleXRSession.start awaits isARSupported() / isSessionSupported('immersive-ar') before assigning location.href to the App Clip URL. After an await, Safari no longer treats the navigation as part of the same user gesture, so the first navigation is blocked or ignored. The second tap hits a cached promise path, so the await is effectively instant and the gesture chain survives.
Fix strategy (app-side, no engine fork)
-
Prime early: call navigator.xr.isSessionSupported('immersive-ar') as soon as possible (e.g. inline <head> script) so the result is often known before the user taps.
-
Wrap NeedleXRSession.start after the engine loads: on the iOS → App Clip branch (!immersiveAR + immersive-ar / ar mode), perform location.href synchronously in the click stack—no await before navigation when you already know you’re taking the App Clip path.
Outcome
One tap → valid user activation → App Clip URL opens on the first interaction.
Quick integration checklist
-
Early isSessionSupported on iOS.
-
Patch NeedleXRSession.start only after import("@needle-tools/engine") (keep codegen / init order intact).
-
Preserve VisionOS / Quick Look branches if you mirror engine logic.
-
Test: iPhone Safari (Needle Go), plus Android / desktop WebXR to avoid regressions.
Keywords (for search)
Needle Engine, NeedleXRSession.start, iOS, Safari, user gesture, transient activation, App Clip, Needle Go, immersive-ar, isSessionSupported, double tap, location.href.
The information provided is a detailed problem description and a proposed fix strategy rather than a question. It correctly identifies the root cause of the “double-tap” issue with the Needle Go App Clip on iOS Safari as a loss of user gesture due to an await before location.href. The suggested fix involves priming isSessionSupported early and synchronously navigating in the click stack for the iOS App Clip path. This seems like a well-thought-out approach to ensure a single-tap activation.
I recommend trying the proposed fix strategy. It addresses the core Safari user gesture limitation and should resolve the double-tap requirement for the App Clip. For more examples, you can check appclip.needle.tools. (1, 2)
Sources: Needle Engine Skill (100%), Needle Engine Docs (75%), Needle Engine API (75%), Needle Engine API (75%), Needle Engine API (75%), Needle Engine API (75%), Needle Engine API (75%), Needle Engine API (75%), Needle Engine API (75%)
1 replies left - Become PRO for more replies.
Reply to this post directly if you need further help (bottom right button)
Hi, thanks for the details. Will test this next week.
Hello again,
I’ve just tried the recommendations - unfortunately they turn out to be false. Note that you have to clear your local experience cache to get the behaviour when a real first click happens.
I’m still trying to investigate if there’s something we can do to make the first click open the AppClip banner (it seems to be related to the device’s app clip cache - only the very first time two clicks are needed). I will update this thread if I figure anything out.
Related: App Clip is not responding to the 1st tap - Apple Community
1 Like
Yes indeed
I’ve observed the same result after few tests on my side too. 
If I find something more effective I’ll keep you in touch !
Hi, could you try opening AR on your iOS device on this website and let me know if the banner shows on the first click?
https://appclip-test-z23hmxb1hujfl-1pgd7g.needle.run/
Yes, it did work from the first opening with only one click!
is it complicated to fix?
Hi the 5.1.0-alpha version has the changes - it’s not 100% reliable I believe - but the alpha also improves UX slightly: if the AppClip does not open then the button will show “Tap again” right away to hopefully mitigate this for end-users.
1 Like
