LaunchParams.targetURL — Eigenschaft · JavaScript-Referenz

Signatur

LaunchParams.targetURL

Beschreibung

Die Eigenschaft targetURL des LaunchParams-Objekts enthält die URL, mit der eine installierte Progressive Web App (PWA) gestartet wurde. Das kann zum Beispiel ein Link sein, den das Betriebssystem an die App weitergibt, eine Shortcut-URL aus dem Manifest oder die start_url.

Sinnvoll ist sie vor allem zusammen mit dem Manifest-Feld launch_handler und dem Modus "client_mode": "focus-existing" (oder "navigate-existing"). Im Modus focus-existing navigiert der Browser das bestehende Fenster nicht zur neuen URL. Die App muss die URL daher selbst aus targetURL lesen und passend reagieren, etwa eine bestimmte Ansicht öffnen, statt die ganze Seite neu zu laden.

An das LaunchParams-Objekt kommt man nur über den Callback von window.launchQueue.setConsumer(). Wurde die App ohne Navigation gestartet, etwa nur über eine File Handling-Dateiöffnung, kann targetURL null sein. Ob die Datei-Übergabe allein auslöst, hängt vom Einzelfall ab.

Rückgabewert

Typ

string | null

Beschreibung

Die absolute Ziel-URL des Starts als String. Gab es keine Ziel-URL, ist der Wert null.

Beispiele

Ziel-URL beim Start auslesen

if ('launchQueue' in window) {
  window.launchQueue.setConsumer((launchParams) => {
    console.log('Gestartet mit:', launchParams.targetURL);
  });
}

Gestartet mit: https://example.com/app/?view=inbox

Bestehendes Fenster per Routing aktualisieren (focus-existing)

// manifest.json: "launch_handler": { "client_mode": "focus-existing" }
const showView = (name, id) => {
  document.querySelector('#title').textContent = `${name}${id ? ' #' + id : ''}`;
};

if ('launchQueue' in window) {
  window.launchQueue.setConsumer(({ targetURL }) => {
    if (!targetURL) return;
    const url = new URL(targetURL);
    // Nur URLs der eigenen Origin verarbeiten
    if (url.origin !== location.origin) return;
    const view = url.searchParams.get('view') ?? 'start';
    const id = url.searchParams.get('id');
    showView(view, id);
    history.replaceState(null, '', url.pathname + url.search);
  });
}

Fallback ohne Launch-Handler-Unterstützung

const getLaunchUrl = () =>
  new Promise((resolve) => {
    if (!('launchQueue' in window)) {
      resolve(location.href); // normale Navigation
      return;
    }
    window.launchQueue.setConsumer((params) => {
      resolve(params.targetURL ?? location.href);
    });
  });

const launchUrl = await getLaunchUrl();
console.log(new URL(launchUrl).pathname);

/app/

// Wichtig · Fallstricke

Experimentell: Die Eigenschaft gehört zur Launch Handler API und wird bisher nur von Chromium-Browsern (Chrome, Edge ab Version 102) unterstützt. Prüfe die Unterstützung immer vorher mit 'launchQueue' in window.
Nur in installierten PWAs sinnvoll. In einem normalen Browser-Tab wird der Consumer in der Regel nicht mit Start-Parametern aufgerufen.
Sie ist schreibgeschützt. Zuweisungen werden stillschweigend ignoriert, im Strict Mode lösen sie einen TypeError aus.
Der Wert kann null sein, etwa bei einem Start nur über Dateiübergabe. Prüfe ihn daher vor new URL().
Sicherheit: Behandle die URL als nicht vertrauenswürdige Eingabe. Query-Parameter nie ungeprüft per innerHTML ausgeben, sonst droht XSS. Die Origin sollte vor der Verarbeitung geprüft werden.
setConsumer() sollte möglichst früh aufgerufen werden. Starts, die vorher eintreffen, werden zwar gepuffert, bei jedem weiteren Start ruft der Browser den Consumer aber erneut auf.

Siehe auch

LaunchParams.files AudioParam.maxValue AudioParam.value Touch.target AudioParam.minValue