Skip to content

Commit 4ea9eba

Browse files
LarkoooLarkooo
authored
Add Capacitor session example (#2355)
Adds a Capacitor-based session example and wires it into the workspace. Updates session handling to normalize redirect payloads and align executeFromOutside behavior across runtimes. Includes docs and Node example tweaks for consistency.
1 parent eec2cc7 commit 4ea9eba

32 files changed

+1766
-56
lines changed

‎.tool-versions‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
scarb 2.9.4
22
starknet-foundry 0.38.3
3-
nodejs v20.11.1
3+
nodejs 22.22.0

‎examples/capacitor/README.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Cartridge + Capacitor Session Example
2+
3+
This example shows how to create and use a Controller session inside a
4+
Capacitor app. It uses the web session provider and opens the authorization
5+
URL in the system browser on native platforms.
6+
7+
## Setup
8+
9+
From the repo root:
10+
11+
```bash
12+
pnpm install
13+
```
14+
15+
Run the web version:
16+
17+
```bash
18+
pnpm -C examples/capacitor dev
19+
```
20+
21+
Build for Capacitor:
22+
23+
```bash
24+
pnpm -C examples/capacitor build
25+
```
26+
27+
Initialize native projects (first time):
28+
29+
```bash
30+
pnpm -C examples/capacitor exec -- cap add ios
31+
pnpm -C examples/capacitor exec -- cap add android
32+
```
33+
34+
Sync updates after builds:
35+
36+
```bash
37+
pnpm -C examples/capacitor exec -- cap sync
38+
```
39+
40+
## Live reload on device
41+
42+
The Capacitor CLI expects the dev server on port 3000 by default. This example
43+
configures Vite to use port 3000, so just run:
44+
45+
```bash
46+
pnpm -C examples/capacitor dev
47+
pnpm -C examples/capacitor exec -- cap run ios -l --external
48+
```
49+
50+
## Deep link setup (required for session redirect)
51+
52+
The session flow redirects back to the app using the custom scheme
53+
`cartridge-session://session`.
54+
55+
### iOS
56+
57+
1. Open the iOS project: `pnpm -C examples/capacitor exec -- cap open ios`
58+
2. In Xcode, select the App target → **Info** → **URL Types**
59+
3. Add a new URL type with **URL Schemes** set to `cartridge-session`
60+
61+
### Android
62+
63+
Add an intent filter for the custom scheme in
64+
`android/app/src/main/AndroidManifest.xml`:
65+
66+
```xml
67+
<intent-filter>
68+
<action android:name=\"android.intent.action.VIEW\" />
69+
<category android:name=\"android.intent.category.DEFAULT\" />
70+
<category android:name=\"android.intent.category.BROWSABLE\" />
71+
<data android:scheme=\"cartridge-session\" android:host=\"session\" />
72+
</intent-filter>
73+
```
74+
75+
## Notes
76+
77+
- The provider opens the session URL with `window.open`. In native builds we
78+
intercept it with `@capacitor/browser` to ensure the system browser opens.
79+
- After authorizing the session in the browser, return to the app to complete
80+
the flow.

‎examples/capacitor/capacitor.config.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { CapacitorConfig } from "@capacitor/cli";
2+
3+
const config: CapacitorConfig = {
4+
appId: "gg.cartridge.controller.capacitor",
5+
appName: "Cartridge Session",
6+
webDir: "dist",
7+
};
8+
9+
export default config;

‎examples/capacitor/index.html‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>Cartridge Session + Capacitor</title>
7+
<style>
8+
:root {
9+
font-family: "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
10+
color: #101827;
11+
background: #f6f7fb;
12+
}
13+
body {
14+
margin: 0;
15+
padding: 32px;
16+
}
17+
.card {
18+
max-width: 720px;
19+
background: #fff;
20+
border-radius: 16px;
21+
padding: 24px;
22+
box-shadow: 0 10px 30px rgba(16, 24, 39, 0.08);
23+
}
24+
h1 {
25+
margin: 0 0 12px 0;
26+
font-size: 22px;
27+
}
28+
p {
29+
margin: 0 0 16px 0;
30+
color: #4b5563;
31+
line-height: 1.5;
32+
}
33+
button {
34+
border: 0;
35+
border-radius: 10px;
36+
padding: 12px 16px;
37+
font-weight: 600;
38+
cursor: pointer;
39+
margin-right: 10px;
40+
}
41+
#connect {
42+
background: #2563eb;
43+
color: white;
44+
}
45+
#execute {
46+
background: #10b981;
47+
color: white;
48+
}
49+
#status {
50+
margin-top: 16px;
51+
padding: 12px;
52+
border-radius: 10px;
53+
background: #f3f4f6;
54+
font-size: 13px;
55+
white-space: pre-wrap;
56+
}
57+
.hint {
58+
font-size: 12px;
59+
color: #6b7280;
60+
}
61+
</style>
62+
</head>
63+
<body>
64+
<div class="card">
65+
<h1>Capacitor Session Example</h1>
66+
<p>
67+
Registers a Controller session and uses it to submit a test transfer on
68+
Sepolia.
69+
</p>
70+
<button id="connect">Connect Session</button>
71+
<button id="execute" disabled>Execute Transfer</button>
72+
<div id="status">Idle</div>
73+
<p class="hint">
74+
On mobile, a browser window will open for authorization. After approval,
75+
return to the app to continue.
76+
</p>
77+
</div>
78+
<script type="module" src="/src/main.ts"></script>
79+
</body>
80+
</html>

‎examples/capacitor/ios/.gitignore‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
App/build
2+
App/Pods
3+
App/output
4+
App/App/public
5+
DerivedData
6+
xcuserdata
7+
8+
# Cordova plugins for Capacitor
9+
capacitor-cordova-ios-plugins
10+
11+
# Generated Config files
12+
App/App/capacitor.config.json
13+
App/App/config.xml

0 commit comments

Comments
 (0)