Skip to content

Commit 247d5b0

Browse files
riderxriderx
authored
Merge pull request #892 from Cap-go/codex/native-build-without-live-updates
docs: add native build testing guide
2 parents 67ee748 + 51449a5 commit 247d5b0

4 files changed

Lines changed: 107 additions & 63 deletions

File tree

‎apps/docs/src/content/docs/docs/live-updates/index.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,12 @@ See the [Deploying Live Updates](/docs/getting-started/deploy/) guide for more d
9999
Customize how and when updates are downloaded and applied in your app.
100100
</Card>
101101
</a>
102+
103+
<a href="/docs/live-updates/testing-native-builds-without-live-updates/">
104+
<Card title="Test Native Builds" icon="approve-check-circle">
105+
Verify a native binary without a downloaded live update masking its bundled web assets.
106+
</Card>
107+
</a>
102108
<a href="/docs/live-updates/differentials/">
103109
<Card title="Fast Updates" icon="starlight">
104110
Learn how to use fast updates to speed up the update process.

‎apps/docs/src/content/docs/docs/live-updates/testing-native-builds-without-live-updates.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: "Test Native Builds Without Live Updates"
3+
description: "Verify the web assets bundled in a native build without receiving a previously deployed live update."
4+
sidebar:
5+
order: 5
6+
---
7+
8+
import { Aside, Steps } from '@astrojs/starlight/components';
9+
10+
When testing a new native binary, make sure it starts from the web assets bundled in that binary—not from a previously downloaded live update. Use one or combine the safeguards below.
11+
12+
## 1. Bump the Native Baseline Version
13+
14+
Set `CapacitorUpdater.version` from the version used for your native release, and increase it for every native build. A newer native baseline makes the installed binary distinct from older bundles and, with the default `resetWhenUpdate: true`, removes downloaded bundles when the newer native app is installed.
15+
16+
```typescript
17+
import type { CapacitorConfig } from '@capacitor/cli';
18+
import pkg from './package.json';
19+
20+
const config: CapacitorConfig = {
21+
plugins: {
22+
CapacitorUpdater: {
23+
// Keep this aligned with, and increase it for, every native build.
24+
version: pkg.version,
25+
autoUpdate: 'atBackground',
26+
},
27+
},
28+
};
29+
30+
export default config;
31+
```
32+
33+
For example, a binary built with `version: '1.4.1'` has a higher native baseline than an existing `1.4.0` bundle. Do not reuse a native version when you need to verify the bundled assets.
34+
35+
## 2. Block Emulator and Development-Build Updates in the Console
36+
37+
Open your app in the Capgo console, go to **Channels**, select the channel used by the build, and open the **Information** tab. Turn **off** both **Allow development build** and **Allow Emulators**.
38+
39+
<figure>
40+
<img src="/native-build-live-updates-channel-settings.webp" alt="Capgo channel Information tab showing the Allow development build and Allow Emulators settings" loading="lazy" width="1536" height="1200" />
41+
<figcaption>These controls are in the channel Information tab. Disable both highlighted settings to keep development builds and emulators on their bundled web assets.</figcaption>
42+
</figure>
43+
44+
<Aside type="caution">
45+
The screenshot shows where to find the settings; its highlighted toggles are enabled. Turn both toggles off for a channel that must not deliver live updates to development builds or emulators.
46+
</Aside>
47+
48+
This channel policy blocks update delivery only for the selected build types. Production-signed physical devices can still receive updates according to the channel's other settings.
49+
50+
## 3. Enable Live Updates Only in Native CI Builds
51+
52+
For teams that want local, emulator, and developer builds to be safe by default, make live updates opt-in through an environment variable. The config below disables update checks unless `CAPGO_LIVE_UPDATES` is exactly `true`:
53+
54+
```typescript
55+
import type { CapacitorConfig } from '@capacitor/cli';
56+
import pkg from './package.json';
57+
58+
const liveUpdatesEnabled = process.env.CAPGO_LIVE_UPDATES === 'true';
59+
60+
const config: CapacitorConfig = {
61+
appId: 'com.example.app',
62+
appName: 'Example App',
63+
plugins: {
64+
CapacitorUpdater: {
65+
// Bump package.json for every native build.
66+
version: pkg.version,
67+
// Local builds are off; native CI explicitly enables live updates.
68+
autoUpdate: liveUpdatesEnabled ? 'atBackground' : false,
69+
},
70+
},
71+
};
72+
73+
export default config;
74+
```
75+
76+
Set the variable only in the CI step that synchronizes and builds the native app:
77+
78+
```yaml
79+
- run: CAPGO_LIVE_UPDATES=true npx cap sync
80+
- run: ./build-native-app.sh
81+
```
82+
83+
Run `npx cap sync` after setting the variable because Capacitor copies this configuration into the native projects during sync. Without the variable, local builds and emulator builds keep `autoUpdate: false` and do not check for live updates.
84+
85+
## Quick Checklist
86+
87+
<Steps>
88+
89+
1. Increase the version used by `CapacitorUpdater.version` for the native binary.
90+
2. Disable **Allow development build** and **Allow Emulators** on the channel when testing those build types.
91+
3. Build locally without `CAPGO_LIVE_UPDATES`.
92+
4. Set `CAPGO_LIVE_UPDATES=true` only before `npx cap sync` in the native CI job that should receive live updates.
93+
94+
</Steps>
95+
96+
## Related
97+
98+
- [Channels](/docs/live-updates/channels/) — Channel routing and policies.
99+
- [Update Behavior](/docs/live-updates/update-behavior/) — When updates are checked and applied.
100+
- [Version Targeting](/docs/live-updates/version-targeting/) — Keep bundles compatible with native versions.

‎apps/docs/src/content/docs/docs/live-updates/update-behavior.mdx‎

Lines changed: 1 addition & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -124,69 +124,7 @@ Learn more in the [Delta (manifest) Updates documentation](/docs/live-updates/di
124124

125125
## Test a Native Build Without Live Updates
126126

127-
When testing a new native binary, make sure the app starts from the web assets bundled in that binary instead of a previously downloaded live update. You can use one or combine several of the following safeguards.
128-
129-
### 1. Bump the Native Baseline Version
130-
131-
Set `CapacitorUpdater.version` from the version used for your native release, and increase it for every native build. A newer native baseline makes the installed binary distinct from older bundles and, with the default `resetWhenUpdate: true`, removes downloaded bundles when the newer native app is installed.
132-
133-
```typescript
134-
import type { CapacitorConfig } from '@capacitor/cli';
135-
import pkg from './package.json';
136-
137-
const config: CapacitorConfig = {
138-
plugins: {
139-
CapacitorUpdater: {
140-
// Keep this aligned with, and increase it for, every native build.
141-
version: pkg.version,
142-
autoUpdate: 'atBackground',
143-
},
144-
},
145-
};
146-
147-
export default config;
148-
```
149-
150-
For example, a binary built with `version: '1.4.1'` has a higher native baseline than an existing `1.4.0` bundle. Do not reuse a native version when you need to verify the bundled assets.
151-
152-
### 2. Block Updates for Emulators and Development Builds
153-
154-
In the channel used by the app, disable **Allow emulator devices** and **Allow development builds**. The updater then does not deliver that channel's bundles to simulators/emulators or development-signed native builds. This is useful when those builds should always use their bundled web assets.
155-
156-
### 3. Enable Live Updates Only in Native CI Builds
157-
158-
For teams that want local, emulator, and developer builds to be safe by default, make live updates opt-in through an environment variable. The config below disables update checks unless `CAPGO_LIVE_UPDATES` is exactly `true`:
159-
160-
```typescript
161-
import type { CapacitorConfig } from '@capacitor/cli';
162-
import pkg from './package.json';
163-
164-
const liveUpdatesEnabled = process.env.CAPGO_LIVE_UPDATES === 'true';
165-
166-
const config: CapacitorConfig = {
167-
appId: 'com.example.app',
168-
appName: 'Example App',
169-
plugins: {
170-
CapacitorUpdater: {
171-
// Bump package.json for every native build.
172-
version: pkg.version,
173-
// Local builds are off; native CI explicitly enables live updates.
174-
autoUpdate: liveUpdatesEnabled ? 'atBackground' : false,
175-
},
176-
},
177-
};
178-
179-
export default config;
180-
```
181-
182-
Set the variable only in the CI step that synchronizes and builds the native app:
183-
184-
```yaml
185-
- run: CAPGO_LIVE_UPDATES=true npx cap sync
186-
- run: ./build-native-app.sh
187-
```
188-
189-
Run `npx cap sync` after setting the variable because Capacitor copies this configuration into the native projects during sync. Without the variable, local builds and emulator builds keep `autoUpdate: false` and do not check for live updates.
127+
See [Test Native Builds Without Live Updates](/docs/live-updates/testing-native-builds-without-live-updates/) for the native-version, channel-policy, and CI configuration safeguards.
190128

191129
```typescript
192130
import { CapacitorConfig } from '@capacitor/cli';

‎apps/web/public/native-build-live-updates-channel-settings.webp‎

28.1 KB
Loading

0 commit comments

Comments
 (0)