@iwsdk/create 0.5.2 → 1.0.0-rc.0
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/dist/cli.js +7223 -215
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
- package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
- package/dist/guidance/claude/.claude/settings.json +6 -2
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/CLAUDE.md +2 -141
- package/dist/guidance/codex/.codex/config.toml +1 -1
- package/dist/guidance/common/AGENTS.md +96 -37
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/public/ui/welcome.uikitml +0 -19
- package/dist/template/common/src/robot.ts +5 -0
- package/dist/template/common/vite.config.ts +18 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
- package/dist/template/common-js/src/robot.js +5 -0
- package/dist/template/common-js/vite.config.js +18 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +8 -1
- package/package.json +8 -7
- package/scripts/verify-release-ready.mjs +25 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
- /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# Packaging a Quest APK with bubblewrap
|
|
2
|
+
|
|
3
|
+
`@meta-quest/bubblewrap-cli` wraps a live PWA into a signed Android APK — a
|
|
4
|
+
Trusted Web Activity that loads `<DOMAIN>` in a full-screen web view. It is a
|
|
5
|
+
wrapper: your files are not inside the APK, which is why the origin must already
|
|
6
|
+
be live and why web fixes never need a rebuild.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npm i -g @meta-quest/bubblewrap-cli # bin: bubblewrap, requires Node >= 18
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Prerequisites — one interactive step, then scriptable
|
|
13
|
+
|
|
14
|
+
On first run bubblewrap has no JDK or Android SDK and offers to install its own
|
|
15
|
+
into `~/.bubblewrap`, behind `inquirer` prompts that include an Android SDK
|
|
16
|
+
licence confirmation. **An agent cannot answer these.** Have the developer run
|
|
17
|
+
this once in a real terminal:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
bubblewrap doctor
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Accept the JDK and SDK installs. It writes `~/.bubblewrap/config.json` with
|
|
24
|
+
`jdkPath` and `androidSdkPath`; every later command is non-interactive. If they
|
|
25
|
+
already have a JDK 17 and an Android SDK, `bubblewrap updateConfig --jdkPath …
|
|
26
|
+
--androidSdkPath …` points at those instead.
|
|
27
|
+
|
|
28
|
+
Locate the tools dynamically rather than hard-coding versions:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
KT=$(find ~/.bubblewrap/jdk -path '*/bin/keytool' | head -1)
|
|
32
|
+
BT=$(ls -d ~/.bubblewrap/android_sdk/build-tools/* | sort -V | tail -1)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## init is interactive — use the scripted path
|
|
36
|
+
|
|
37
|
+
`bubblewrap init` generates `twa-manifest.json` and the Gradle project through a
|
|
38
|
+
wizard (host, name, packageId, version, display, colors, icon, **App Mode**,
|
|
39
|
+
signing key). It needs a real TTY and has no value flags to bypass the prompts.
|
|
40
|
+
|
|
41
|
+
- **Developer at a terminal:** `bubblewrap init --manifest=https://<DOMAIN>/manifest.webmanifest --metaquest`
|
|
42
|
+
and answer the prompts. `--metaquest` is what surfaces the Quest-specific
|
|
43
|
+
questions, including App Mode.
|
|
44
|
+
- **Agent, or any non-TTY caller:** skip `init`. Hand-write
|
|
45
|
+
`twa-manifest.json` as below, then run `update` and `build`, which are both
|
|
46
|
+
non-interactive.
|
|
47
|
+
|
|
48
|
+
Work in a directory **outside** the web tree — `twa/` next to the app, never
|
|
49
|
+
inside `public/` or anywhere that gets published.
|
|
50
|
+
|
|
51
|
+
## Step 1 — The signing key: pause and ask
|
|
52
|
+
|
|
53
|
+
**Stop and ask the developer which key to use before building anything.** This
|
|
54
|
+
is not a detail to default. The key is permanent: every future update must be
|
|
55
|
+
signed with the same keystore, alias, and `packageId`, and a published Store
|
|
56
|
+
listing is already bound to one. There is no recovery from a lost key — only a
|
|
57
|
+
new Store entry under a new package name.
|
|
58
|
+
|
|
59
|
+
**(A) Existing keystore.** Ask for the file path, the alias, and the store and
|
|
60
|
+
key passwords, and use them as-is. Required when updating an app that is already
|
|
61
|
+
published. Reusing one keystore across several apps is normal and fine.
|
|
62
|
+
|
|
63
|
+
**(B) Generate a new one** — only when there is nothing to reuse. Create it
|
|
64
|
+
outside the deployable web tree, and tell the developer to back it up:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
"$KT" -genkeypair -v -keystore twa/android.keystore \
|
|
68
|
+
-alias android -keyalg RSA -keysize 2048 -validity 10000 \
|
|
69
|
+
-storepass <PW> -keypass <PW> -dname "CN=<App>, O=<Org>, C=US"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Either way, read the certificate SHA-256 now — step 4 needs it:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
"$KT" -list -v -keystore <keystore> -alias <alias> \
|
|
76
|
+
-storepass <PW> -keypass <PW> | grep -i SHA256
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Step 2 — twa-manifest.json
|
|
80
|
+
|
|
81
|
+
Field names and types come from the `TwaManifest` class in
|
|
82
|
+
`@meta-quest/bubblewrap-core`; treat that as authoritative if something here
|
|
83
|
+
looks stale.
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"packageId": "com.<org>.<app>",
|
|
88
|
+
"applicationId": "<HORIZON_APP_ID or 0>",
|
|
89
|
+
"host": "<DOMAIN>",
|
|
90
|
+
"name": "Full App Name",
|
|
91
|
+
"launcherName": "App",
|
|
92
|
+
"display": "standalone",
|
|
93
|
+
"orientation": "landscape",
|
|
94
|
+
"themeColor": "#0a0418",
|
|
95
|
+
"backgroundColor": "#06010f",
|
|
96
|
+
"startUrl": "/",
|
|
97
|
+
"iconUrl": "https://<DOMAIN>/icons/icon-512.png",
|
|
98
|
+
"maskableIconUrl": "https://<DOMAIN>/icons/icon-512-maskable.png",
|
|
99
|
+
"webManifestUrl": "https://<DOMAIN>/manifest.webmanifest",
|
|
100
|
+
"signingKey": { "path": "<abs>/twa/android.keystore", "alias": "android" },
|
|
101
|
+
"appVersion": "1",
|
|
102
|
+
"appVersionName": "1",
|
|
103
|
+
"appVersionCode": 1,
|
|
104
|
+
"fallbackType": "customtabs",
|
|
105
|
+
"features": {},
|
|
106
|
+
"isMetaQuest": true,
|
|
107
|
+
"horizonOSAppMode": "immersive",
|
|
108
|
+
"fingerprints": [],
|
|
109
|
+
"minSdkVersion": 23
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The four fields that actually decide whether this works:
|
|
114
|
+
|
|
115
|
+
- **`isMetaQuest`** — defaults to `false`. Left unset, you get a plain Android
|
|
116
|
+
TWA with no Quest behavior at all.
|
|
117
|
+
- **`horizonOSAppMode`** — `"immersive"` or `"2D"`, validated against exactly
|
|
118
|
+
those two strings, **defaulting to `"immersive"`** when absent or misspelled.
|
|
119
|
+
A 2D app that omits it inherits the wrong mode silently.
|
|
120
|
+
- **`packageId`** — permanent, paired with the signing key. Choose it once.
|
|
121
|
+
- **`applicationId`** — the numeric Horizon App ID. `"0"` builds and sideloads
|
|
122
|
+
fine (no in-app purchases); set the real id before any Store upload.
|
|
123
|
+
|
|
124
|
+
`signingKey.path` should be absolute — a relative path resolves against the
|
|
125
|
+
Gradle project directory, not your shell's.
|
|
126
|
+
|
|
127
|
+
## Step 3 — Build
|
|
128
|
+
|
|
129
|
+
`update` regenerates the Gradle project from the manifest and bumps the version;
|
|
130
|
+
`build` compiles and signs. Passwords are read from the environment — there are
|
|
131
|
+
no password CLI flags.
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
cd twa
|
|
135
|
+
export BUBBLEWRAP_KEYSTORE_PASSWORD=<PW> BUBBLEWRAP_KEY_PASSWORD=<PW>
|
|
136
|
+
bubblewrap update && bubblewrap build
|
|
137
|
+
# → app-release-signed.apk + app-release-bundle.aab
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Verify what you actually built before shipping it:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
"$BT/aapt" dump badging app-release-signed.apk | grep -iE '^package:|APP_MODE|OCULUS'
|
|
144
|
+
"$BT/apksigner" verify --print-certs app-release-signed.apk | grep -i SHA-256
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The package name, app mode, and app id must be what you intended, and the
|
|
148
|
+
signer's SHA-256 must equal the keystore's from step 1. If they differ, the
|
|
149
|
+
build picked up a different key — asset links will fail and the app will not
|
|
150
|
+
launch.
|
|
151
|
+
|
|
152
|
+
Upload `app-release-signed.apk` to the Store; the `.aab` is not used by the
|
|
153
|
+
Horizon pipeline.
|
|
154
|
+
|
|
155
|
+
## Step 4 — Digital Asset Links
|
|
156
|
+
|
|
157
|
+
The TWA verifies at launch that the origin vouches for this exact package and
|
|
158
|
+
certificate. If verification fails, Horizon shows *"will not launch"* — there is
|
|
159
|
+
no partial or degraded mode.
|
|
160
|
+
|
|
161
|
+
`public/.well-known/assetlinks.json`:
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
[
|
|
165
|
+
{
|
|
166
|
+
"relation": ["delegate_permission/common.handle_all_urls"],
|
|
167
|
+
"target": {
|
|
168
|
+
"namespace": "android_app",
|
|
169
|
+
"package_name": "com.<org>.<app>",
|
|
170
|
+
"sha256_cert_fingerprints": ["3B:06:…:8B"]
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
]
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The fingerprint is the colon-separated uppercase hex from step 1. List one
|
|
177
|
+
object per package if several apps share the origin, and publish the same file
|
|
178
|
+
on every `additional_trusted_origins` host.
|
|
179
|
+
|
|
180
|
+
This is the **second hosting handoff**. Rebuild and publish through the
|
|
181
|
+
`iwsdk-hosting` skill, then verify the content, not just the status code:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
npm run build
|
|
185
|
+
# …publish…
|
|
186
|
+
curl -s https://<DOMAIN>/.well-known/assetlinks.json
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Changing `applicationId` or `horizonOSAppMode` does not change this file — the
|
|
190
|
+
package name and certificate are unchanged, so no republish is needed for a
|
|
191
|
+
mode fix.
|
|
192
|
+
|
|
193
|
+
## Sideload and test
|
|
194
|
+
|
|
195
|
+
Test on device before uploading. This is the only place the immersive auto-enter
|
|
196
|
+
path can be verified, since `getDigitalGoodsService` does not exist off-device.
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
adb install -r app-release-signed.apk
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Scaffolded IWSDK projects also register the `metavr` MCP server, which can
|
|
203
|
+
manage the connected Quest. Launch from the Library, not from `adb shell am
|
|
204
|
+
start` — launching from the Library is what exercises the real install path.
|
|
205
|
+
|
|
206
|
+
What to look for: the immersive app should enter VR with no visible 2D page and
|
|
207
|
+
no URL bar; a 2D app should open as a windowed panel. Anything else, go to
|
|
208
|
+
[`troubleshooting.md`](troubleshooting.md).
|
|
209
|
+
|
|
210
|
+
## Security
|
|
211
|
+
|
|
212
|
+
- The keystore and its passwords never enter `public/`, `dist/`, or version
|
|
213
|
+
control. Confirm after each publish:
|
|
214
|
+
`curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/android.keystore`
|
|
215
|
+
→ 404.
|
|
216
|
+
- If a keystore was ever published, treat it as compromised: generate a new key
|
|
217
|
+
under a new `packageId`, since the old pairing is permanent.
|
|
218
|
+
- Back up the keystore, alias, and passwords together. They are only useful as a
|
|
219
|
+
set.
|
package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Web App Manifest and Icons
|
|
2
|
+
|
|
3
|
+
Both modes need a valid, installable web app manifest and PNG icons, live on
|
|
4
|
+
`<DOMAIN>` **before** `bubblewrap update` runs — it fetches them over the
|
|
5
|
+
network and fails or silently falls back if they are missing.
|
|
6
|
+
|
|
7
|
+
The scaffolded app ships neither: `public/` has no manifest, and `index.html`
|
|
8
|
+
has a placeholder `<link rel="icon" href="data:," />`. Both are added here.
|
|
9
|
+
|
|
10
|
+
## The manifest
|
|
11
|
+
|
|
12
|
+
`public/manifest.webmanifest` — Vite copies `public/` verbatim into `dist/`, so
|
|
13
|
+
it is served at `/manifest.webmanifest` with no further wiring.
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"name": "Full App Name",
|
|
18
|
+
"short_name": "App",
|
|
19
|
+
"description": "One sentence shown at install time.",
|
|
20
|
+
"start_url": "/",
|
|
21
|
+
"scope": "/",
|
|
22
|
+
"display": "standalone",
|
|
23
|
+
"orientation": "landscape",
|
|
24
|
+
"background_color": "#06010f",
|
|
25
|
+
"theme_color": "#0a0418",
|
|
26
|
+
"icons": [
|
|
27
|
+
{ "src": "/icons/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
|
|
28
|
+
{ "src": "/icons/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
|
|
29
|
+
{ "src": "/icons/icon-512-maskable.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
|
|
30
|
+
]
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
| Field | Why it matters here |
|
|
35
|
+
| ----- | ------------------- |
|
|
36
|
+
| `name` / `short_name` | `short_name` is the launcher label; keep it under ~12 characters or it truncates |
|
|
37
|
+
| `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment |
|
|
38
|
+
| `display` | `standalone` for both modes; `browser` forces a URL bar |
|
|
39
|
+
| `background_color` | painted before first frame — match the app's clear color or launch flashes white |
|
|
40
|
+
| `theme_color` | colors the custom tab bar on a 2D panel; add `theme_color_dark` if the app is dark-first |
|
|
41
|
+
| `icons` | at minimum 192 and 512 `any`, plus one 512 `maskable` |
|
|
42
|
+
|
|
43
|
+
`bubblewrap` seeds `twa-manifest.json` from these values, so getting them right
|
|
44
|
+
now avoids hand-correcting them in two places later.
|
|
45
|
+
|
|
46
|
+
## Link it in `index.html`
|
|
47
|
+
|
|
48
|
+
Replace the placeholder icon line in the scaffolded `<head>`:
|
|
49
|
+
|
|
50
|
+
```html
|
|
51
|
+
<link rel="manifest" href="/manifest.webmanifest" />
|
|
52
|
+
<meta name="theme-color" content="#0a0418" />
|
|
53
|
+
<link rel="icon" href="/icons/icon-192.png" />
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use absolute `/`-rooted paths here even though `vite.config.*` sets
|
|
57
|
+
`base: './'`. The relative base is for hashed bundle assets; the manifest and
|
|
58
|
+
icons are referenced by the platform from a known URL, and a relative path
|
|
59
|
+
resolves differently depending on the entry route.
|
|
60
|
+
|
|
61
|
+
## Generating icons
|
|
62
|
+
|
|
63
|
+
There is no ImageMagick or PIL to rely on. Use `sharp` — the scaffold already
|
|
64
|
+
pins a working version via `overrides`:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npm i -D sharp
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Write an SVG and rasterize each size:
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
// scripts/icons.mjs — run with `node scripts/icons.mjs`
|
|
74
|
+
import sharp from 'sharp';
|
|
75
|
+
import { mkdir } from 'node:fs/promises';
|
|
76
|
+
|
|
77
|
+
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
|
|
78
|
+
<defs>
|
|
79
|
+
<radialGradient id="g" cx="50%" cy="40%" r="70%">
|
|
80
|
+
<stop offset="0%" stop-color="#7c4dff"/>
|
|
81
|
+
<stop offset="100%" stop-color="#06010f"/>
|
|
82
|
+
</radialGradient>
|
|
83
|
+
</defs>
|
|
84
|
+
<rect width="512" height="512" fill="url(#g)"/>
|
|
85
|
+
<!-- glyph goes here -->
|
|
86
|
+
</svg>`;
|
|
87
|
+
|
|
88
|
+
await mkdir('public/icons', { recursive: true });
|
|
89
|
+
const png = (size, out) =>
|
|
90
|
+
sharp(Buffer.from(svg)).resize(size, size).png().toFile(out);
|
|
91
|
+
|
|
92
|
+
await png(512, 'public/icons/icon-512.png');
|
|
93
|
+
await png(192, 'public/icons/icon-192.png');
|
|
94
|
+
await png(512, 'public/icons/icon-512-maskable.png');
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Two constraints that produce visible defects when ignored:
|
|
98
|
+
|
|
99
|
+
- **Prefer radial/linear gradients over blur filters.** `sharp`'s SVG rasterizer
|
|
100
|
+
renders Gaussian blur poorly; glows come out banded or clipped.
|
|
101
|
+
- **The maskable icon must be full-bleed and opaque** — no transparency, no
|
|
102
|
+
rounded corners, and keep the glyph inside the middle ~80% safe zone. The
|
|
103
|
+
platform applies its own mask, so transparent or pre-rounded edges show as
|
|
104
|
+
chipped corners on the launcher.
|
|
105
|
+
|
|
106
|
+
The `any` and `maskable` icons can be the same artwork only if that artwork is
|
|
107
|
+
already full-bleed. If the `any` icon has transparent padding, generate two.
|
|
108
|
+
|
|
109
|
+
## Subpath hosting
|
|
110
|
+
|
|
111
|
+
Serving from `https://<DOMAIN>/<path>/` changes two manifest fields:
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
"start_url": "/<path>/",
|
|
115
|
+
"scope": "/<path>/"
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Icon `src` values can stay `/`-rooted if the icons are at the origin root, but
|
|
119
|
+
it is less error-prone to make them relative to the scope (`icons/icon-512.png`)
|
|
120
|
+
and let the manifest URL resolve them.
|
|
121
|
+
|
|
122
|
+
`assetlinks.json` is unaffected by this and must still be at the **origin
|
|
123
|
+
root** — see `iwsdk-hosting` §5.
|
|
124
|
+
|
|
125
|
+
## Multi-origin 2D apps
|
|
126
|
+
|
|
127
|
+
If a 2D panel app legitimately navigates across origins, list them so they stay
|
|
128
|
+
in scope instead of bouncing to the browser:
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
"additional_trusted_origins": ["https://other.example"]
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Every listed origin must also serve `/.well-known/assetlinks.json` with the same
|
|
135
|
+
package name and certificate fingerprint. A missing one does not error — the
|
|
136
|
+
origin just falls out of scope at runtime.
|
|
137
|
+
|
|
138
|
+
## Verify before packaging
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
npm run build
|
|
142
|
+
for u in /manifest.webmanifest /icons/icon-192.png /icons/icon-512.png /icons/icon-512-maskable.png; do
|
|
143
|
+
printf '%s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
|
|
144
|
+
done
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
All 200. The manifest must be `application/manifest+json` — `text/plain` means
|
|
148
|
+
the host has no mapping for `.webmanifest`; fix it per
|
|
149
|
+
`iwsdk-hosting/references/existing-hosts.md`.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Uploading to the Meta Horizon Store
|
|
2
|
+
|
|
3
|
+
Uploads go through Meta's `ovr-platform-util`. The same command handles
|
|
4
|
+
immersive and 2D builds — nothing about the upload differs by app mode.
|
|
5
|
+
|
|
6
|
+
## Before uploading
|
|
7
|
+
|
|
8
|
+
- The app exists in the [Developer Dashboard](https://developer.oculus.com/manage/)
|
|
9
|
+
and you have its numeric **App ID**. `applicationId` in `twa-manifest.json`
|
|
10
|
+
must be that id, not `"0"` — rebuild if it is still the placeholder.
|
|
11
|
+
- The APK is signed with the app's permanent key, and asset links are live.
|
|
12
|
+
- The build has been sideloaded and launched on a headset. Store review is slow;
|
|
13
|
+
catching a wrong app mode here costs minutes instead of days.
|
|
14
|
+
|
|
15
|
+
## Get the tool
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
# macOS
|
|
19
|
+
curl -L -o ovr-platform-util \
|
|
20
|
+
"https://www.oculus.com/download_app/?id=1462426033810370&access_token=OC%7C1462426033810370%7C"
|
|
21
|
+
chmod +x ./ovr-platform-util && ./ovr-platform-util version
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Windows and Linux builds are linked from the Dashboard under Distribution →
|
|
25
|
+
Upload. On macOS, Gatekeeper may quarantine the binary on first run — the
|
|
26
|
+
developer clears it in System Settings → Privacy & Security, or with
|
|
27
|
+
`xattr -d com.apple.quarantine ./ovr-platform-util`.
|
|
28
|
+
|
|
29
|
+
Use the upload utility described here for this Store submission workflow.
|
|
30
|
+
|
|
31
|
+
## Authentication
|
|
32
|
+
|
|
33
|
+
Two options — **ask the developer for one, never invent or guess a value:**
|
|
34
|
+
|
|
35
|
+
| Credential | Where | Flag |
|
|
36
|
+
| ---------- | ----- | ---- |
|
|
37
|
+
| App Secret | Dashboard → your app → **API** tab | `--app-secret` |
|
|
38
|
+
| User token | Dashboard → Account → Generate token | `--token` |
|
|
39
|
+
|
|
40
|
+
Treat either as a secret: pass it on the command line or through an environment
|
|
41
|
+
variable, never into a file under `public/`, and never into version control. If
|
|
42
|
+
one is pasted into the conversation, do not echo it back in later output.
|
|
43
|
+
|
|
44
|
+
## Upload
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
./ovr-platform-util upload-quest-build \
|
|
48
|
+
--app-id <HORIZON_APP_ID> \
|
|
49
|
+
--app-secret <SECRET> \
|
|
50
|
+
--apk app-release-signed.apk \
|
|
51
|
+
--channel ALPHA \
|
|
52
|
+
--age-group MIXED_AGES \
|
|
53
|
+
--notes "Short description of this build" \
|
|
54
|
+
--disable-progress-bar
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
| Flag | Required | Values |
|
|
58
|
+
| ---- | -------- | ------ |
|
|
59
|
+
| `--app-id` | yes | numeric Horizon App ID |
|
|
60
|
+
| `--apk` | yes | path to `app-release-signed.apk` |
|
|
61
|
+
| `--channel` | yes | `ALPHA` / `BETA` / `RC` for testing, `STORE` for production |
|
|
62
|
+
| `--age-group` | yes | `TEENS_AND_ADULTS` / `MIXED_AGES` / `CHILDREN` |
|
|
63
|
+
| `--app-secret` or `--token` | yes | one of the two |
|
|
64
|
+
| `--notes` | no | release notes |
|
|
65
|
+
| `--disable-progress-bar` | no | use it in agent/CI contexts; the animated bar floods the log |
|
|
66
|
+
|
|
67
|
+
Start on `ALPHA`. Promote to `STORE` from the Dashboard once the build has been
|
|
68
|
+
tested by real users on the channel.
|
|
69
|
+
|
|
70
|
+
A successful upload prints a **Build ID** and a `…/test-results/` URL. Report
|
|
71
|
+
both back to the developer — the test-results page is where automated VRC
|
|
72
|
+
checks land.
|
|
73
|
+
|
|
74
|
+
## The blocker you should expect first
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
must first agree to our Developer Distribution Agreement
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Nearly every organization's first upload fails this way. An **org admin** must
|
|
81
|
+
sign the DDA once at:
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
https://developer.oculus.com/manage/organizations/<ORG_ID>/legal-documents/
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
This is a legal action only the developer can take. **Pause, explain, and wait**
|
|
88
|
+
— then retry the identical command; nothing about the build needs to change.
|
|
89
|
+
|
|
90
|
+
## Other responses worth recognizing
|
|
91
|
+
|
|
92
|
+
| Message | Meaning |
|
|
93
|
+
| ------- | ------- |
|
|
94
|
+
| Quest 1 not supported | harmless warning; Quest 1 is end-of-life |
|
|
95
|
+
| Signature does not match previous build | the APK was signed with a different key than the published app — reuse the original keystore |
|
|
96
|
+
| Version code must be higher | bump `appVersionCode` in `twa-manifest.json`, `bubblewrap update && bubblewrap build`, re-upload |
|
|
97
|
+
| App ID not found / unauthorized | `--app-id` and the secret belong to different apps, or the secret was regenerated |
|
|
98
|
+
|
|
99
|
+
## After the upload
|
|
100
|
+
|
|
101
|
+
Store metadata — listing copy, screenshots, store art, age rating, VRC
|
|
102
|
+
compliance — is handled in the Dashboard, not by this tool. Uploading a build
|
|
103
|
+
does not submit it for review; that is a separate Dashboard action once a build
|
|
104
|
+
is promoted to the `STORE` channel.
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
Failure modes across the whole pipeline. Most present on device as one of four
|
|
4
|
+
symptoms, so start there.
|
|
5
|
+
|
|
6
|
+
| Symptom on the headset | Most likely cause | Section |
|
|
7
|
+
| ---------------------- | ----------------- | ------- |
|
|
8
|
+
| "will not launch" | asset links | [Launch](#launch-failures) |
|
|
9
|
+
| Stuck on a loading screen | `horizonOSAppMode: "immersive"` on a 2D app | [App mode](#app-mode-failures) |
|
|
10
|
+
| Opens with a browser URL bar | `horizonOSAppMode: "2D"` on an immersive app | [App mode](#app-mode-failures) |
|
|
11
|
+
| Opens flat, no URL bar, never enters VR | auto-enter code missing or not firing | [App mode](#app-mode-failures) |
|
|
12
|
+
| Blank / white / error page | the origin is unreachable from the device | [Origin](#origin-failures) |
|
|
13
|
+
|
|
14
|
+
Before diagnosing, establish which layer is wrong. A **web** bug is fixed by
|
|
15
|
+
republishing `<DOMAIN>`; a **native** bug needs a new APK and a new upload.
|
|
16
|
+
Read the built APK rather than guessing:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
"$BT/aapt" dump badging app-release-signed.apk | grep -iE '^package:|APP_MODE|OCULUS'
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## App mode failures
|
|
23
|
+
|
|
24
|
+
### 2D app stuck on a loading screen
|
|
25
|
+
|
|
26
|
+
`horizonOSAppMode` is `"immersive"`, so Horizon waits for a WebXR session that
|
|
27
|
+
never starts. Note the field **defaults to `immersive`** when absent or
|
|
28
|
+
misspelled, so an omitted field looks identical.
|
|
29
|
+
|
|
30
|
+
Set `"horizonOSAppMode": "2D"`, then `bubblewrap update && bubblewrap build` and
|
|
31
|
+
re-upload. Asset links do not change.
|
|
32
|
+
|
|
33
|
+
### Immersive app shows a URL bar
|
|
34
|
+
|
|
35
|
+
`horizonOSAppMode` is `"2D"`. Set `"immersive"`, rebuild, re-upload.
|
|
36
|
+
|
|
37
|
+
### Immersive app opens flat with no URL bar
|
|
38
|
+
|
|
39
|
+
The mode is right; the session is never requested. Check, in order:
|
|
40
|
+
|
|
41
|
+
1. The auto-enter block is present in `src/index.ts` **inside** the
|
|
42
|
+
`World.create(...).then(...)` callback — placed before the world resolves,
|
|
43
|
+
`world` is undefined and the `.catch` swallows it.
|
|
44
|
+
2. The queried mode matches `iwsdk.config.json`. An AR app must query
|
|
45
|
+
`isSessionSupported('immersive-ar')`; querying `immersive-vr` returns `false`
|
|
46
|
+
and the app stays flat with no error.
|
|
47
|
+
3. The deployed bundle actually contains it —
|
|
48
|
+
`curl -s https://<DOMAIN>/assets/index-*.js | grep -c getDigitalGoodsService`.
|
|
49
|
+
A forgotten republish is the most common answer.
|
|
50
|
+
|
|
51
|
+
This is a web bug: republish `<DOMAIN>`, relaunch the app. No rebuild.
|
|
52
|
+
|
|
53
|
+
### Auto-enter works on device but breaks the browser
|
|
54
|
+
|
|
55
|
+
The `getDigitalGoodsService` gate was removed or inverted. In a tab, the app
|
|
56
|
+
should keep its normal Enter-XR button; auto-requesting a session without a user
|
|
57
|
+
gesture there fails with a security error.
|
|
58
|
+
|
|
59
|
+
## Launch failures
|
|
60
|
+
|
|
61
|
+
### "will not launch"
|
|
62
|
+
|
|
63
|
+
Asset-link verification failed. Check all four in order:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
curl -s https://<DOMAIN>/.well-known/assetlinks.json
|
|
67
|
+
"$BT/apksigner" verify --print-certs app-release-signed.apk | grep -i SHA-256
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
1. **The file is reachable** — a 404 means the host stripped the dotfolder. See
|
|
71
|
+
`iwsdk-hosting/references/existing-hosts.md`; do not relocate the file, the
|
|
72
|
+
path is fixed.
|
|
73
|
+
2. **`package_name` matches `packageId`** in `twa-manifest.json`, exactly.
|
|
74
|
+
3. **`sha256_cert_fingerprints` matches the APK signer**, comparing hex bytes —
|
|
75
|
+
the two tools differ in case and colon placement, and that difference is not
|
|
76
|
+
the problem.
|
|
77
|
+
4. **It is served as JSON, not HTML.** A SPA catch-all route that returns
|
|
78
|
+
`index.html` for unknown paths will answer 200 with the wrong body. Check the
|
|
79
|
+
body, not the status code.
|
|
80
|
+
|
|
81
|
+
On a multi-origin 2D app, every `additional_trusted_origins` host needs the
|
|
82
|
+
file too.
|
|
83
|
+
|
|
84
|
+
### Signature mismatch on update
|
|
85
|
+
|
|
86
|
+
The build was signed with a different keystore than the published app. Reuse the
|
|
87
|
+
original keystore, alias, and passwords — there is no way to re-sign a published
|
|
88
|
+
app with a new key. A lost keystore means a new `packageId` and a new Store
|
|
89
|
+
entry.
|
|
90
|
+
|
|
91
|
+
## Origin failures
|
|
92
|
+
|
|
93
|
+
### Blank, white, or error page after launch
|
|
94
|
+
|
|
95
|
+
The device cannot load `<DOMAIN>`. Usually one of:
|
|
96
|
+
|
|
97
|
+
- **The hashed Vercel per-deploy URL was used** instead of the canonical alias —
|
|
98
|
+
it returns 401 under deployment protection. Fix `host`/`webManifestUrl` in
|
|
99
|
+
`twa-manifest.json`, rebuild, re-upload.
|
|
100
|
+
- **Deployment protection is on** for the whole project. A TWA cannot
|
|
101
|
+
authenticate through it; it must be disabled.
|
|
102
|
+
- **The origin is internal-only** and unreachable from the headset's network.
|
|
103
|
+
- **Certificate problems** — a self-signed or expired cert fails silently in the
|
|
104
|
+
web view.
|
|
105
|
+
|
|
106
|
+
Confirm from a machine on the same network as the headset:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### App loads but assets 404
|
|
113
|
+
|
|
114
|
+
Usually a subpath deployment with `start_url`/`scope` still set to `/`. Set them
|
|
115
|
+
to `/<path>/` and republish. The scaffolded `base: './'` handles the bundle
|
|
116
|
+
paths already, so if bundles load and only `public/` assets 404, look for a
|
|
117
|
+
publish that missed those files.
|
|
118
|
+
|
|
119
|
+
## Packaging failures
|
|
120
|
+
|
|
121
|
+
### bubblewrap hangs or exits without doing anything
|
|
122
|
+
|
|
123
|
+
It is waiting on an `inquirer` prompt with no TTY — either `init`, or the
|
|
124
|
+
first-run JDK/Android SDK install. Have the developer run `bubblewrap doctor`
|
|
125
|
+
once in a real terminal, then use the scripted path (`update` + `build`) rather
|
|
126
|
+
than `init`.
|
|
127
|
+
|
|
128
|
+
### Build fails with a keystore or password error
|
|
129
|
+
|
|
130
|
+
Passwords come only from `BUBBLEWRAP_KEYSTORE_PASSWORD` and
|
|
131
|
+
`BUBBLEWRAP_KEY_PASSWORD`; there are no CLI flags. Confirm both are exported in
|
|
132
|
+
the same shell as the build, that `signingKey.path` is absolute, and that
|
|
133
|
+
`signingKey.alias` matches the keystore's actual alias:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
"$KT" -list -keystore <keystore> -storepass <PW>
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### bubblewrap update fails fetching the manifest
|
|
140
|
+
|
|
141
|
+
`update` reads `webManifestUrl` over the network. The manifest must be live and
|
|
142
|
+
200 at that exact URL — not merely present in a local `dist/`.
|
|
143
|
+
|
|
144
|
+
### Wrong icon in the launcher
|
|
145
|
+
|
|
146
|
+
`iconUrl` and `maskableIconUrl` are fetched at `update` time and baked into the
|
|
147
|
+
APK. Changing the icon on the host later does nothing; rebuild and re-upload.
|
|
148
|
+
|
|
149
|
+
## Upload failures
|
|
150
|
+
|
|
151
|
+
### "must first agree to our Developer Distribution Agreement"
|
|
152
|
+
|
|
153
|
+
The most common first-time blocker. An org admin signs it once at
|
|
154
|
+
`https://developer.oculus.com/manage/organizations/<ORG_ID>/legal-documents/`.
|
|
155
|
+
Pause, ask, then retry the identical command.
|
|
156
|
+
|
|
157
|
+
### Version code must be higher
|
|
158
|
+
|
|
159
|
+
Bump `appVersionCode` in `twa-manifest.json`, then `bubblewrap update &&
|
|
160
|
+
bubblewrap build`. `update` also bumps it on its own, so this usually means an
|
|
161
|
+
earlier build was uploaded from a different working directory.
|
|
162
|
+
|
|
163
|
+
## Security incidents
|
|
164
|
+
|
|
165
|
+
### The keystore is reachable on the public host
|
|
166
|
+
|
|
167
|
+
It was generated inside the web tree and published. Move it out, republish,
|
|
168
|
+
confirm the URL 404s, and treat the key as compromised — generate a new one
|
|
169
|
+
under a new `packageId`, since the key/package pairing is permanent.
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/android.keystore # want 404
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### An app secret was committed or published
|
|
176
|
+
|
|
177
|
+
Regenerate it in the Dashboard (API tab) immediately; the old value stays valid
|
|
178
|
+
until you do.
|