@returningai/react-native-widget-sdk 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- Allows native iOS HTML-string WebView origins (`about:srcdoc`, `applewebdata://`)
|
|
6
|
+
in `originWhitelist`, navigation policy, and `onMessage` gating. Expo Go still
|
|
7
|
+
reports `about:blank`; RN CLI / WKWebView on iOS 26 reports `about:srcdoc`,
|
|
8
|
+
which previously blocked the shell and timed out ready.
|
|
9
|
+
|
|
3
10
|
## 0.1.0
|
|
4
11
|
|
|
5
12
|
- Preserves JSON types and structure in custom-data session fingerprints (EC-04).
|
package/README.md
CHANGED
|
@@ -1,54 +1,34 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @returningai/react-native-widget-sdk
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
CLI and Expo apps.
|
|
3
|
+
[](https://www.npmjs.com/package/@returningai/react-native-widget-sdk)
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
WebView only the exchanged short-lived access token. It supports custom
|
|
8
|
-
`rai-custom-widget` bundle and page content; first-class web elements are not
|
|
9
|
-
mobile APIs.
|
|
5
|
+
Embed ReturningAI custom product widgets in React Native CLI and Expo apps.
|
|
10
6
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
crossed; the SDK collection buffer stays within the configured limit. Transport
|
|
14
|
-
buffers and individual incoming chunks are outside that allocation guarantee.
|
|
15
|
-
The standard React Native fetch polyfill buffers before returning its Response,
|
|
16
|
-
so its fallback size check happens after allocation. A hard native transport
|
|
17
|
-
memory cap is not currently guaranteed (EC-12); oversized responses are rejected.
|
|
7
|
+
The SDK authenticates in JavaScript and gives the WebView only a short-lived
|
|
8
|
+
access token. Hosts custom `rai-custom-widget` bundle and page content.
|
|
18
9
|
|
|
19
|
-
##
|
|
10
|
+
## Install
|
|
20
11
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
12
|
+
```bash
|
|
13
|
+
npm install @returningai/react-native-widget-sdk react-native-webview
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Peer dependencies:
|
|
25
17
|
|
|
26
|
-
-
|
|
27
|
-
- React **^19.2**
|
|
18
|
+
- `react` **^19.2**
|
|
28
19
|
- `react-native` **^0.86**
|
|
29
20
|
- `react-native-webview` **^16**
|
|
30
21
|
- Node.js **22.13+**
|
|
31
|
-
- **Dev client** (`expo run:*`) — **Expo Go is unsupported** for embeds
|
|
32
|
-
- Loyalty sample enables **New Architecture**; Old Arch is not certified
|
|
33
22
|
|
|
34
|
-
|
|
35
|
-
|
|
23
|
+
Expo hosts need SDK **57** and a **dev client** (`expo run:ios` /
|
|
24
|
+
`expo run:android`). Expo Go is not supported.
|
|
36
25
|
|
|
37
|
-
|
|
38
|
-
`packages/ios`. A public npm release is deferred. Publish / local `file:` notes:
|
|
39
|
-
[`docs/publishing/react-native.md`](../../docs/publishing/react-native.md).
|
|
26
|
+
Install Web Crypto before the widget loads:
|
|
40
27
|
|
|
41
|
-
|
|
28
|
+
- Expo: `expo-crypto`
|
|
29
|
+
- React Native CLI: `react-native-get-random-values`
|
|
42
30
|
|
|
43
|
-
|
|
44
|
-
auth, version-1 bridge, navigation policy, coordinator, controller, the
|
|
45
|
-
`react-native-webview` surface, the Expo Loyalty App, Jest fake-driver
|
|
46
|
-
loopback, Chromium generated-shell TTI, and Jest hot-path CPU budgets are in.
|
|
47
|
-
|
|
48
|
-
Do not put `accessId`, `accessKey`, or embed tokens in the app, HTML, bridge,
|
|
49
|
-
`injectedJavaScript`, or WebView URLs. `reload()` replays the in-memory HTML
|
|
50
|
-
shell with the content-origin `baseUrl`; it never calls native
|
|
51
|
-
`WebView.reload()`.
|
|
31
|
+
## Usage
|
|
52
32
|
|
|
53
33
|
```tsx
|
|
54
34
|
import {
|
|
@@ -58,11 +38,13 @@ import {
|
|
|
58
38
|
} from "@returningai/react-native-widget-sdk";
|
|
59
39
|
|
|
60
40
|
const configuration = ReturningAIWidgetConfiguration.customBundle({
|
|
61
|
-
widgetId: "
|
|
41
|
+
widgetId: "YOUR_WIDGET_ID",
|
|
62
42
|
bundleUrl: "https://widgets.example/custom-widget/bundle/store/widget.js",
|
|
63
43
|
clientOrigin: "https://mobile-client.example",
|
|
64
44
|
});
|
|
65
45
|
|
|
46
|
+
const controller = new ReturningAIWidgetController();
|
|
47
|
+
|
|
66
48
|
<ReturningAIWidget
|
|
67
49
|
configuration={configuration}
|
|
68
50
|
embedTokenProvider={async () => hostMintedEmbedToken}
|
|
@@ -73,39 +55,27 @@ const configuration = ReturningAIWidgetConfiguration.customBundle({
|
|
|
73
55
|
/>;
|
|
74
56
|
```
|
|
75
57
|
|
|
76
|
-
|
|
58
|
+
`clientOrigin` must be the exact HTTPS origin allowlisted for the widget in
|
|
59
|
+
ReturningAI.
|
|
77
60
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
npm install
|
|
81
|
-
npx expo start
|
|
82
|
-
```
|
|
61
|
+
Mint embed tokens on **your** backend. Do not put `accessId`, `accessKey`, or
|
|
62
|
+
embed tokens in the app, HTML, bridge, `injectedJavaScript`, or WebView URLs.
|
|
83
63
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
Client recipe (go-live checklist, pin `runtimeUrl`, crypto polyfill):
|
|
87
|
-
[`docs/guides/client-integration.md`](../../docs/guides/client-integration.md).
|
|
88
|
-
Loyalty samples use unpkg **latest**.
|
|
64
|
+
Pin `runtimeUrl` in production. The default is unpkg
|
|
65
|
+
`@returningai/widget-sdk` latest.
|
|
89
66
|
|
|
90
|
-
##
|
|
67
|
+
## Controller
|
|
91
68
|
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
npm run format:check
|
|
69
|
+
```ts
|
|
70
|
+
await controller.reload();
|
|
71
|
+
await controller.retry();
|
|
72
|
+
await controller.updateTheme("dark");
|
|
73
|
+
await controller.logout();
|
|
74
|
+
await controller.invalidate();
|
|
99
75
|
```
|
|
100
76
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
generated HTML shell, and hot-path CPU budgets. Expo dev-client WebView TTI
|
|
107
|
-
lives in `examples/react-native/loyalty_app` (`npm run loopback-tti:ios` /
|
|
108
|
-
`loopback-tti:android`) and uses real `ReturningAIWidget` + `react-native-webview`
|
|
109
|
-
against a localhost loopback fixture (MOB-44). TTI waits for `rai-ready` only,
|
|
110
|
-
uses a generous 20-second budget, and prints `benchmark webview_cold_ready` /
|
|
111
|
-
`webview_reload_ready` samples. Expo Go and live CDN TTI are out of scope.
|
|
77
|
+
`reload()` replays the in-memory HTML shell. It does not call native
|
|
78
|
+
`WebView.reload()`.
|
|
79
|
+
|
|
80
|
+
On `rai-session-expired`, return a freshly minted embed token from
|
|
81
|
+
`embedTokenProvider`. Call `invalidate()` when the host user signs out.
|
package/package.json
CHANGED
|
@@ -56,7 +56,7 @@ export class ReturningAINavigationPolicy {
|
|
|
56
56
|
*/
|
|
57
57
|
decide(uri: URL, isMainFrame: boolean): ReturningAINavigationAction {
|
|
58
58
|
const scheme = uri.protocol.replace(/:$/, "").toLowerCase();
|
|
59
|
-
if (
|
|
59
|
+
if (isHtmlShellNavigation(uri, scheme)) {
|
|
60
60
|
return ReturningAINavigationAction.allow;
|
|
61
61
|
}
|
|
62
62
|
|
|
@@ -87,3 +87,18 @@ export class ReturningAINavigationPolicy {
|
|
|
87
87
|
return ReturningAINavigationAction.reject;
|
|
88
88
|
}
|
|
89
89
|
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* iOS `loadHTMLString:baseURL:` may navigate to `about:blank`, `about:srcdoc`,
|
|
93
|
+
* or `applewebdata://` instead of the content-origin HTTPS URL.
|
|
94
|
+
*/
|
|
95
|
+
function isHtmlShellNavigation(uri: URL, scheme: string): boolean {
|
|
96
|
+
if (scheme === "applewebdata") {
|
|
97
|
+
return true;
|
|
98
|
+
}
|
|
99
|
+
if (scheme !== "about") {
|
|
100
|
+
return false;
|
|
101
|
+
}
|
|
102
|
+
const href = uri.href.toLowerCase();
|
|
103
|
+
return href === "about:blank" || href === "about:srcdoc";
|
|
104
|
+
}
|
package/src/packageInfo.ts
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
*/
|
|
14
14
|
export const RETURNING_AI_REACT_NATIVE_PACKAGE = {
|
|
15
15
|
/** Semver of `@returningai/react-native-widget-sdk`. */
|
|
16
|
-
version: "0.1.
|
|
16
|
+
version: "0.1.1",
|
|
17
17
|
/** Documented Expo SDK major this package targets. */
|
|
18
18
|
expoSdk: 57,
|
|
19
19
|
/** Documented React Native minor this package targets. */
|
|
@@ -89,6 +89,11 @@ export function normalizeReturningAIOrigin(origin: string): string {
|
|
|
89
89
|
return origin.trim().replace(/\/+$/, "").toLowerCase();
|
|
90
90
|
}
|
|
91
91
|
|
|
92
|
+
function isHtmlShellDocumentUrl(sourceUrl: string): boolean {
|
|
93
|
+
const url = sourceUrl.toLowerCase();
|
|
94
|
+
return url === "about:blank" || url === "about:srcdoc" || url.startsWith("applewebdata:");
|
|
95
|
+
}
|
|
96
|
+
|
|
92
97
|
/**
|
|
93
98
|
* Strict main-frame origin equality check for bridge message acceptance.
|
|
94
99
|
* @param isMainFrame - Must be true
|
|
@@ -112,7 +117,8 @@ export function shouldAcceptReturningAIWebMessage(
|
|
|
112
117
|
/**
|
|
113
118
|
* RN-specific gate for delivering `onMessage` payloads to the coordinator.
|
|
114
119
|
* When no expected origin is configured, delivery is allowed (fail-open only then).
|
|
115
|
-
* iOS may report `about:blank` for HTML
|
|
120
|
+
* iOS may report `about:blank`, `about:srcdoc`, or `applewebdata://` for HTML
|
|
121
|
+
* with a content-origin baseUrl; envelope identity still gates.
|
|
116
122
|
* @param input.sourceUrl - `nativeEvent.url` from react-native-webview
|
|
117
123
|
* @param input.expectedOrigin - Expected origin from configuration
|
|
118
124
|
* @returns True when the message should be decoded
|
|
@@ -128,9 +134,9 @@ export function shouldDeliverReturningAIWebMessage(input: {
|
|
|
128
134
|
if (sourceUrl === undefined || sourceUrl.length === 0) {
|
|
129
135
|
return false;
|
|
130
136
|
}
|
|
131
|
-
//
|
|
132
|
-
// content-origin baseUrl. Envelope identity still gates
|
|
133
|
-
if (sourceUrl
|
|
137
|
+
// Native iOS WKWebView reports about:blank, about:srcdoc, or applewebdata
|
|
138
|
+
// for HTML loaded with a content-origin baseUrl. Envelope identity still gates.
|
|
139
|
+
if (isHtmlShellDocumentUrl(sourceUrl)) {
|
|
134
140
|
return true;
|
|
135
141
|
}
|
|
136
142
|
try {
|
|
@@ -4,19 +4,23 @@
|
|
|
4
4
|
* Layer: webview
|
|
5
5
|
* Role: Returns allowed origin patterns for the WebView; debug adds localhost/127.0.0.1 HTTP entries.
|
|
6
6
|
* Does not decide navigation allow/delegate/reject (navigation policy does).
|
|
7
|
-
* Security: Production whitelist is HTTPS + about
|
|
7
|
+
* Security: Production whitelist is HTTPS + HTML-shell about:/applewebdata URLs.
|
|
8
8
|
* See also: navigation/ReturningAINavigationPolicy.ts, ReturningAIWidget.tsx
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
|
+
/** Origins used when iOS loads `source={{ html, baseUrl }}` (not a real navigation). */
|
|
12
|
+
const htmlShellOrigins = ["about:blank", "about:srcdoc", "applewebdata://*"] as const;
|
|
13
|
+
|
|
11
14
|
/**
|
|
12
15
|
* Builds the `originWhitelist` patterns for `react-native-webview`.
|
|
13
|
-
* Production allows HTTPS
|
|
16
|
+
* Production allows HTTPS plus HTML-string shell origins; debug also allows localhost HTTP.
|
|
17
|
+
* Native iOS WKWebView (not Expo Go) may report `about:srcdoc` for `loadHTMLString`.
|
|
14
18
|
* @param debug - Configuration debug flag
|
|
15
19
|
* @returns Origin pattern list for the WebView prop
|
|
16
20
|
*/
|
|
17
21
|
export function returningAIOriginWhitelist(debug: boolean): string[] {
|
|
18
22
|
if (debug) {
|
|
19
|
-
return ["https://*", "http://localhost*", "http://127.0.0.1*",
|
|
23
|
+
return ["https://*", "http://localhost*", "http://127.0.0.1*", ...htmlShellOrigins];
|
|
20
24
|
}
|
|
21
|
-
return ["https://*",
|
|
25
|
+
return ["https://*", ...htmlShellOrigins];
|
|
22
26
|
}
|