Embedded components #2193

gimenete-stripe · 2025-10-31T11:34:22Z

Summary

This PR adds support for Connect embedded components. In particular it adds support for 3 components:

Account onboarding
Payments
Payouts

New components can easily be added.

Most of the work is done using just React Native but I need to use native code for a couple of things:

Handling "secure webviews"
Rendering the navigation bar to match the look and feel of the system (e.g. liquid glass) when opening the onboarding embedded component, which needs to be shown in a modal.

Question: this API is not ready for GA yet. How do we prevent users to think it's production ready? Should I add an unstable_ prefix or a PrivatePreview suffix to the API or something like that?

Motivation

https://docs.google.com/document/d/1tEm_mtsbHgbyhBoctYGLjmmLth0nI4b24osTIxN8_gM/edit?usp=sharing

Testing

I tested this manually
I added automated tests

I updated the backend to have an additional endpoint to return a client secret for the embedded components and added 3 screens to the example app.

Documentation

Select one:

I have added relevant documentation for my changes.
This PR does not result in any developer-facing changes.

src/connect/EmbeddedComponent.tsx

example/src/screens/ConnectScreen.tsx

src/connect/EmbeddedComponent.tsx

maragues-stripe

I focused on the Android part

android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt

android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt

maragues-stripe · 2025-11-25T13:39:26Z

android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt

+        val uri = android.net.Uri.parse(url)
+        val builder =
+          androidx.browser.customtabs.CustomTabsIntent
+            .Builder()
+
+        // Set toolbar color for better UX
+        builder.setShowTitle(true)
+        builder.setUrlBarHidingEnabled(true)
+
+        val customTabsIntent = builder.build()


nit: You can probably move this outside of runOnUiThread

maragues-stripe · 2025-11-25T13:45:38Z

example/android/build.gradle

+                if (manifestFile.exists()) {
+                    def manifest = manifestFile.text
+
+                    // Add launchMode="singleTask"


MainActivity with launchMode=singleTask will destroy all activities that previously existed on top of it.

Is that what we want?

In any case, can't we define a standard AndroidManifest.xml file, instead of doing this?

launchMode=singleTask is necessary for deep linking with React Navigation:
https://reactnavigation.org/docs/deep-linking/#setup-on-android

And deep linking is necessary for using "secure webviews" (implemented with chrome tabs on Android) to return back to the app.

And we can't use AndroidManifest.xml file, instead of modifying the manifest in the build.gradle?

example/android/build.gradle

src/connect/Components.tsx

Co-authored-by: maragues-stripe <[email protected]>

Resolved conflicts in: - android/build.gradle: Used master version with stripeVersion variable - ios/StripeSdkImpl.swift: Kept both authentication session properties and proper spacing - example/package.json: Used master versions (React Native 0.81.0, React 19.1.0) - example/ios/Podfile.lock: Used master version - example/yarn.lock: Used master version - yarn.lock: Used master version 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Committed-By-Agent: claude

SwiftLint auto-formatted iOS files after merge. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Committed-By-Agent: claude

Fixed three compilation errors: 1. NavigationBarView.kt: Use UIManagerHelper.getSurfaceId() instead of direct surfaceId access 2. NavigationBarView.kt: Cast context to ThemedReactContext for proper type 3. StripeSdkModule.kt: Add missing androidx.browser.customtabs.CustomTabsIntent import 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Committed-By-Agent: claude

Added androidx.browser:browser:1.8.0 as an implementation dependency to support the openAuthenticatedWebView functionality that uses CustomTabsIntent for Android. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Committed-By-Agent: claude

cttsai-stripe

Question: this API is not ready for GA yet. How do we prevent users to think it's production ready? Should I add an unstable_ prefix or a PrivatePreview suffix to the API or something like that?

We have standard annotations for native Android and iOS but do not set up one for RN yet. https://trailhead.corp.stripe.com/docs/mobile-sdk/payments/releasing-non-ga-apis-in-the-mobile-sdks.
I'll discuss with our team to see how we should deal with private preview on RN.

cttsai-stripe · 2025-12-05T19:27:57Z

android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt

nit: Could we add tests to prevent regression in a follow-up PRs? I think unit tests and e2e tests would be helpful.

Sure. Although it's hard to test these things because they depend on an external service I can add tests in a follow-up PR.

Also, I'm building an example app focused on embedded components that uses a different backend that allows testing multiple merchants in this other PR. It's for manual testing but it covers everything.

cttsai-stripe · 2025-12-05T19:30:15Z

src/connect/EmbeddedComponent.tsx

+          callbacks?.[functionName]?.(value);
+        }
+      } else if (message.type === 'openAuthenticatedWebView') {
+        const { url, id } = message.data as { id: string; url: string };


Should we validate the url?

That can be a good sanity check. Done here.

cttsai-stripe · 2025-12-05T19:33:15Z

src/connect/EmbeddedComponent.tsx

+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', (nextAppState) => {
+      if (
+        appState.current.match(/inactive|background/) &&
+        nextAppState === 'active'
+      ) {
+        if (pendingAuthWebViewPromise.current) {
+          const { id, callback } = pendingAuthWebViewPromise.current;
+          pendingAuthWebViewPromise.current = null;
+          callback(id, null);
+        }
+      }
+
+      appState.current = nextAppState;
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, []);


How does it work? Some opinions from claude:

Race condition: AppState change might fire before deep link listener captures URL

Always resolves with null: Doesn't actually pass the deep link URL to the callback

No timeout: Promise could hang indefinitely if deep link never arrives

Also:
The AppState subscription in useEffect is removed on cleanup, but:

If EmbeddedComponent unmounts during auth flow, pendingAuthWebViewPromise.current is orphaned

No cleanup of authenticationSession in iOS on unmount

Recommendation: Add cleanup in useEffect return:

subscription.remove(); // Cancel pending auth sessions if (Platform.OS === 'ios') { NativeStripeSdk.cancelAuthenticatedWebView?.(); } pendingAuthWebViewPromise.current = null; };

Feel free to ignore comments from claude if those do not make sense.

Cleaning up the promise is a good idea. Done here 👍

cttsai-stripe · 2025-12-05T19:39:44Z

src/connect/EmbeddedComponent.tsx

+const DEVELOPMENT_URL =
+  Platform.OS === 'android' ? 'http://10.0.2.2:3001' : 'http://localhost:3001';
+const PRODUCTION_URL = 'https://connect-js.stripe.com';
+const BASE_URL = DEVELOPMENT_MODE ? DEVELOPMENT_URL : PRODUCTION_URL;


Looks like DEVELOPMENT_MODE is always false

Yep, this can be set to true while developing to switch to using a local server for the webview URLs and for enabling the debug mode in the webview.

Happy to leave a comment or make this configurable in a different way.

Removed the New Architecture delegate pattern from NavigationBarManager to make it compatible with both Old and New Architecture builds. The delegate pattern requires codegen-generated classes that are only available in New Architecture. Since NavigationBar is a simple component with only one prop, it doesn't need the delegate pattern. Fixes the Old Architecture build error: - Unresolved reference 'NavigationBarManagerDelegate' - Unresolved reference 'NavigationBarManagerInterface' 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Committed-By-Agent: claude

gimenete-stripe · 2025-12-05T21:43:53Z

@cttsai-stripe thanks for the review!! 🙏

I'll discuss with our team to see how we should deal with private preview on RN.

Cool 👍 Thanks again! 🙇

Embedded components

db0fa9f

gimenete-stripe mentioned this pull request Oct 31, 2025

Add support for Account Onboarding #2087

Closed

4 tasks

gimenete-stripe commented Oct 31, 2025

View reviewed changes

src/connect/EmbeddedComponent.tsx Outdated Show resolved Hide resolved

example/src/screens/ConnectScreen.tsx Outdated Show resolved Hide resolved

src/connect/EmbeddedComponent.tsx Outdated Show resolved Hide resolved

gimenete-stripe and others added 21 commits November 4, 2025 18:43

Make react-native-webview optional and load it dynamically

070f198

Extract types from @stripe/connect-js

e4f2e69

Custom font

c32af78

Use a modal for the onboarding component

8f4d601

Merge branch 'master' into gimenete/embedded-components

9f32ca6

Update podfile.lcok

5ea7e9b

Hide "overrides" from public interface

e62cd98

Change initialization API. Add toggles to switch appearance and locale

7d03d7a

Remove some alerts

29f09f9

Implement secure webviews

e2a597b

Implement secure webviews

c8654e2

Merge branch 'master' into gimenete/embedded-components

f1acd01

Add endpoint to server

91f52cc

Improvements for Android

8e58819

Extract callback

a6e2c87

Trying to fix deep linking on Android

146b31c

Native navigation bar

3120ef3

Native navigation bar

ef8630a

Small changes

2001d48

Remember previous screen

3066e48

Merge branch 'master' into gimenete/embedded-components

f41b48e

gimenete-stripe marked this pull request as ready for review November 25, 2025 12:12

gimenete-stripe requested review from a team as code owners November 25, 2025 12:12

maragues-stripe reviewed Nov 25, 2025

View reviewed changes

gimenete-stripe and others added 2 commits November 25, 2025 22:02

Apply suggestions from code review

6f9688b

Co-authored-by: maragues-stripe <[email protected]>

Make onCloseButtonPress a constant

c3c69f9

gimenete-stripe mentioned this pull request Dec 1, 2025

Stripe connect example #2236

Draft

4 tasks

gimenete-stripe and others added 6 commits December 3, 2025 22:17

Make the onboarding component have a fully native modal

2c83eb9

Changes in colors

a246d95

Apply linter auto-fixes from merge

175cdd6

SwiftLint auto-formatted iOS files after merge. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Committed-By-Agent: claude

cttsai-stripe reviewed Dec 5, 2025

View reviewed changes

gimenete-stripe and others added 3 commits December 5, 2025 22:27

Validate URL before opening authenticated webview

184d030

Clean up promise in useEffect

22f5f51

Embedded components #2193

Are you sure you want to change the base?

Embedded components #2193

Uh oh!

Conversation

gimenete-stripe commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Testing

Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maragues-stripe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gimenete-stripe Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cttsai-stripe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gimenete-stripe commented Dec 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gimenete-stripe commented Oct 31, 2025 •

edited

Loading

gimenete-stripe Nov 25, 2025 •

edited

Loading