一个教会 Claude Code 使用 WebViewGold JavaScript 桥接的 Agent Skill

.claude/skills/webviewgold-bridge/
├── SKILL.md            rules, scheme table, patterns (loads with the skill)
├── platform-notes.md   iOS vs Android differences and native switches (loads on demand)
└── templates/
    └── native.ts       helper module Claude copies into src/lib/

---
name: webviewgold-bridge
description: Adds or debugs native iOS and Android features in this web app through the WebViewGold JavaScript bridge (URL schemes such as registerpush://, bioauth://, qrcode://, shareapp://, getonesignalplayerid://, rateapp://). Use when a task involves push notifications, Face ID, Touch ID or fingerprint login, QR or barcode scanning, the share sheet, haptics or vibration, saving images, app rating, the app version, opening app settings, or any behavior that must differ inside the native app.
---

# WebViewGold JavaScript bridge

This web app also ships as native iOS and Android apps built with WebViewGold. The apps load
the production URL in a WKWebView (iOS) or an Android WebView. Native features are triggered
by navigating to a URL scheme. Results come back as injected global variables or as calls to
global functions. There is no SDK to install and nothing to bundle.

## Rules
1. Detect the app with isNativeApp() from src/lib/native.ts. If that file does not exist,
   copy templates/native.ts from this skill. Never write a second user agent check.
2. Trigger schemes only through callNative(), callNativeQuietly() or callAndRead(). Every
   call needs a browser fallback: the web equivalent, or hide the control. No dead buttons.
3. Use only the schemes in the table below. For anything else, read the feature page under
   https://www.webviewgold.com/docs/iOS/ or https://www.webviewgold.com/docs/android/
   (full text: https://www.webviewgold.com/llms-full.txt). If it is not documented, tell
   the user it is not supported. Never invent a scheme, parameter or variable name.
4. iOS processes only one location change per script run. For several data calls at once
   use multiapicall://getonesignalplayerid,getappversion (comma-separated, no spaces; it
   works on Android too). Fire haptics on iOS through callNativeQuietly().
5. Injected variables arrive asynchronously. Read them with readInjected() or callAndRead(),
   never synchronously right after the call.
6. A scheme for a feature that is switched off in the native project does nothing. When you
   add a feature, list the native settings the user must enable (see platform-notes.md).
   Never edit signing, certificates, provisioning profiles or keystore settings.
7. Biometric success is a UI gate only. Sensitive actions still need a server-side check.

## Scheme reference
| Feature | Call | Result |
|---|---|---|
| Push permission prompt | registerpush:// | System permission dialog |
| Push permission status | checkNativePushPermissions:// | window.nativePushEnabled (true or false) |
| App settings | settingsapp:// | Opens the system settings of the app |
| OneSignal subscription ID | getonesignalplayerid:// | window.onesignalplayerid |
| Firebase push ID | getfirebaseplayerid:// | window.firebaseplayerid |
| Local notification | sendlocalpushmsg://push.send?s=SECONDS=msg!MESSAGE&!#TITLE&!#URL | Shown after SECONDS |
| Cancel local notifications | sendlocalpushmsg://push.send.cancel | Removes all scheduled ones |
| Biometrics | bioauth:// | iOS calls onBioAuthSuccess(), onBioAuthFailure(errorCode, errorMessage) or onBioAuthUnavailable() |
| QR code | qrcode:// | The scanned URL opens in the app |
| Barcode | barcodescanner:// | window.barcodescanresult |
| Share sheet | shareapp://message?=TEXT&url=URL | Native share dialog |
| Haptics | lighthaptic:// heavyhaptic:// successhaptic:// warninghaptic:// errorhaptic:// | Vibration; mediumhaptic:// is iOS only |
| Save image | savethisimage://?url=IMAGE_URL | Saved to the photo library |
| Rating | rateapp:// | System review dialog; the system decides whether it appears |
| App version | getappversion:// | window.versionNumber and window.bundleNumber |

## Patterns
- Push: ask after onboarding or a first success, never on the first screen. Explain in one
  sentence what we will send, then call registerpush://. In settings, use pushEnabled() and
  offer settingsapp:// when push is off. Save onesignalplayerid on the user profile via our API.
- Share: always encodeURIComponent TEXT and URL; share() in native.ts does it.
- QR codes: encode URLs on our own domain, because the scanned URL loads inside the app.
- Rating: only after a positive moment (order completed, task finished). Never at launch and
  never in exchange for a reward.
- Version: hide UI that older app builds cannot support by checking appVersion().

## Before you finish
- Every native call sits behind isNativeApp() and has a browser fallback.
- Your summary lists each scheme you used, the native switches to enable (platform-notes.md)
  and any platform-specific limits.
- Remind the user to test inside the real app on a device: push and biometrics cannot be
  tested in a desktop browser.

# Platform notes for the WebViewGold bridge

## User agent token
- iOS: Config.swift, useragent_iphone and useragent_ipad
- Android: Config.java, USER_AGENT
- Value: a normal mobile user agent string, a space, then WebViewGoldApp

## Push (OneSignal)
- iOS: kPushEnabled and oneSignalID in Config.swift. Set askforpushpermissionatfirstrun to
  false when the web app asks later with registerpush://. The App ID needs the Push
  Notifications and App Groups capabilities.
- Android: PUSH_ENABLED in Config.java, ONE_SIGNAL_APP_ID in app/build.gradle.
- Firebase instead of OneSignal: getfirebaseplayerid:// and window.firebaseplayerid.

## Variables without a call
- iOS autoInjectVariable, Android AUTO_INJECT_VARIABLES: values such as the push ID and the
  app version are injected automatically. readInjected() works either way.

## Biometrics
- iOS: add "Privacy - Face ID Usage Description" to Info.plist. Callbacks:
  onBioAuthSuccess(), onBioAuthFailure(errorCode, errorMessage), onBioAuthUnavailable().
- Android: the system BiometricPrompt, which may fall back to PIN or pattern. The Android
  docs describe the prompt but not the three callbacks: test on a device before relying on
  them, and keep a fallback.
- enableBioMetricAuth (both platforms) is a separate app lock on every launch and is
  independent of bioauth://.

## Camera features (qrcode://, barcodescanner://)
- iOS: camera usage description in Info.plist; qrcodelinks in Config.swift decides where
  scanned URLs open.
- Android: requireCamera and QR_CODE_URL_OPTIONS in Config.java.

## Haptics
- mediumhaptic:// exists on iOS only. Use lighthaptic:// or heavyhaptic:// on Android.

## Downloads
- savethisimage://?url=... saves an image. Other files download natively by extension:
  extentionARY (Config.swift) and downloadableExtension (Config.java).

## Rating
- rateapp:// shows the system review dialog, which the system rate-limits.
  iOS alternative: showcustomrateappdialog and ratemyappurl in Config.swift.

## Documentation
- iOS: https://www.webviewgold.com/docs/iOS/
- Android: https://www.webviewgold.com/docs/android/
- Full text for agents: https://www.webviewgold.com/llms-full.txt

// templates/native.ts
// Copied into src/lib/native.ts by the webviewgold-bridge skill.
// The only file that knows how the web app detects the WebViewGold apps.

// Set in Config.swift (useragent_iphone, useragent_ipad) and Config.java (USER_AGENT)
const TOKEN = "WebViewGoldApp";

export function isNativeApp(): boolean {
  return typeof navigator !== "undefined" && navigator.userAgent.includes(TOKEN);
}

export function isAndroidApp(): boolean {
  return isNativeApp() && /Android/i.test(navigator.userAgent);
}

export function isIOSApp(): boolean {
  return isNativeApp() && !isAndroidApp();
}

// Navigate to a scheme. Returns false in normal browsers so callers can fall back.
export function callNative(scheme: string): boolean {
  if (!isNativeApp()) return false;
  window.location.href = scheme;
  return true;
}

// Fire-and-forget call through a temporary iframe, so it does not cancel a
// navigation in progress (the technique from the WebViewGold iOS haptics docs).
export function callNativeQuietly(scheme: string): boolean {
  if (!isNativeApp()) return false;
  const frame = document.createElement("iframe");
  frame.style.display = "none";
  frame.src = scheme;
  document.body.appendChild(frame);
  frame.remove();
  return true;
}

// Poll for a global variable the app injects (onesignalplayerid, nativePushEnabled ...)
export function readInjected<T = unknown>(name: string, timeoutMs = 3000): Promise<T> {
  return new Promise((resolve, reject) => {
    const started = Date.now();
    const tick = () => {
      const value = (window as any)[name];
      if (value !== undefined) return resolve(value as T);
      if (Date.now() - started > timeoutMs) return reject(new Error(name + " was not injected"));
      setTimeout(tick, 100);
    };
    tick();
  });
}

// Call a scheme and read a fresh result; clears a stale value first.
export async function callAndRead<T = unknown>(scheme: string, name: string, timeoutMs = 3000): Promise<T | null> {
  if (!isNativeApp()) return null;
  try { delete (window as any)[name]; } catch { /* variable not deletable, keep polling */ }
  window.location.href = scheme;
  return readInjected<T>(name, timeoutMs).catch(() => null);
}

export type Haptic = "light" | "heavy" | "success" | "warning" | "error";

export function haptic(kind: Haptic): void {
  const scheme = kind + "haptic://";
  if (isIOSApp()) callNativeQuietly(scheme);
  else callNative(scheme);
}

export function share(text: string, url: string): boolean {
  return callNative("shareapp://message?=" + encodeURIComponent(text) + "&url=" + encodeURIComponent(url));
}

export function pushEnabled(): Promise<boolean | null> {
  return callAndRead<boolean>("checkNativePushPermissions://", "nativePushEnabled", 2000);
}

export function appVersion(): Promise<string | null> {
  return callAndRead<string>("getappversion://", "versionNumber", 2000);
}