Erstellen von QR-Codes für das App-Routing mit benutzerdefinierten Parametern

Wie verknüpft man benutzerdefinierte Parameter beim Erstellen von QR-Codes? Die Verknüpfung benutzerdefinierter Parameter für das App-Routing erfordert das Anhängen strukturierter URL-Abfrageschlüssel an den Link einer gehosteten Landingpage, das Erfassen dieser Schlüssel über eine Web-Integrationsschicht sowie das Weiterleiten der validierten Nutzdaten an native Navigationscontroller beim direkten Aufwachen der App oder beim Start nach der Installation.

Das In-App-Routing über QR-Codes ist eine Client-Server-Navigationsarchitektur, die strukturierte Zielparameter in die URL eines zweidimensionalen Barcodes einbettet. Indem diese Parameter bei installierter Anwendung über direkte Betriebssystem-Deep-Links oder bei einer neu aus einem App-Store installierten Anwendung über plattformunterstützte verzögerte Wiederherstellung aufgelöst werden, können Entwicklungsteams Nutzer direkt zu bestimmten In-App-Ansichten anstelle der Standard-Startansicht leiten.

Architekturübersicht: Erstellen von QR-Codes für die Wiederherstellung von App-Ansichten

Das Problem der Absprünge auf dem Startbildschirm: Warum generische Store-Weiterleitungen hochgradig zielgerichtete Nutzerreisen unterbrechen

Physische QR-Codes werden häufig in zielbezogenen Umgebungen eingesetzt: Ein Käufer scannt ein Regaletikett, um Produktspezifikationen anzuzeigen, ein Gast scannt einen Tischaufsteller, um aus einer bestimmten Menükategorie zu bestellen, oder ein Spieler scannt einen Einladungsbarcode, um einer Multiplayer-Spiellobby beizutreten. Wenn der Barcode einen generischen App-Store-Link oder eine unparametrisierte Domain codiert, geht die Absicht des Nutzers beim Übergang vom physischen Scan zur Laufzeit der nativen Anwendung verloren.

Beim Start der Anwendung wird der Nutzer auf den standardmäßigen Startbildschirm der obersten Ebene geleitet. Die erzwungene manuelle Navigation durch komplexe Kategoriebäume, erneute Suchanfragen oder die Eingabe von Raumkennungen erzeugt erheblichen kognitiven und mechanischen Aufwand. Die Wiederherstellung von In-App-Ansichten behebt diesen Absprung, indem der Zielzustand in der QR-Code-URL codiert und diese Zielansicht im nativen Client programmgesteuert rekonstruiert wird.

Mechanik des Dual-State-Routings: Direktes Aufwachen im Vergleich zu verzögerter Ansichtswiederherstellung

Wenn ein Nutzer einen QR-Code für das App-Routing scannt, befindet sich das Mobilgerät in einem von zwei Installationszuständen. Eine vollständige Routing-Architektur handhabt beide Lebenszyklen über separate technische Pfade:

• Direktes Aufwachen (Anwendung bereits installiert): Wenn die Zielanwendung bereits auf dem Gerätevorausgesetzt ist, löst das Scannen des QR-Codes einen Betriebssystem-Deep-Link aus – konkret Apple Universal Links unter iOS oder Android App Links unter Android. Beide Mechanismen erfordern die Bereitstellung kryptografisch verifizierter Domain-Zuordnungsdateien: iOS erfordert eine apple-app-site-association-Datei (AASA) in Kombination mit einer Xcode-Berechtigung für Associated Domains, während Android eine Digital Asset Links-Datei /.well-known/assetlinks.json erfordert, die zum SHA-256-Fingerabdruck des Signaturzertifikats der Anwendung und den verifizierten Manifest-Intent-Filtern passt. Nach der Verifizierung weckt das Betriebssystem die Anwendung auf und leitet den URI direkt an den Lebenszyklus-Delegierten des Clients weiter.
• Verzögerte Wiederherstellung von Ansichten (Anwendung nicht installiert): Wenn die Anwendung nicht vorhanden ist, wird der Nutzer über eine intermediäre Web-Landingpage zum App-Store der Plattform geleitet. Da das native Binärprogramm noch nicht installiert ist, um einen Betriebssystem-Intent zu empfangen, müssen die Routing-Parameter vor der Store-Weiterleitung bereitgestellt und beim ersten Start der Anwendung (Kaltstart an Tag 0) nach Abschluss der Installation wiederhergestellt werden.

Plattformspezifische Wiederherstellungsgrenzen: Google Play Install Referrer, iOS Universal Links und SDK-Adapter

Nachdem ein Nutzer eine Anwendung aus einem App-Store installiert hat, hängt die Wiederherstellung von Empfehlungs- und Routing-Parametern von der Plattform und dem von der Anwendung oder dem Attribution-SDK implementierten Mechanismus ab. Die Übergabe eines route- oder id-Parameters über eine Web-URL garantiert für sich allein nicht, dass der Parameter eine App-Store-Installation überlebt:

Android und Google Play: Die Google Play Install Referrer API kann unterstützte Empfehlungs-Metadaten bereitstellen, die mit einer Installation aus dem Play Store verknüpft sind. Dieser Mechanismus gilt speziell für Installationen, die über den offiziellen Google Play Store-Pfad abgeschlossen wurden, und nicht für beliebige APK-Sideloads von Drittanbietern oder alternative Stores. Die Anwendung muss die tatsächlichen Referrer-Nutzdaten konfigurieren und testen sowie sicherstellen, dass die erwarteten Parameter den Weiterleitungs- und Installationsablauf überstehen.
iOS und der App Store: Der Apple App Store überträgt beliebige Abfrageparameter von Web-Landingpages nicht automatisch in eine neu installierte Anwendungsbinärdatei. Universal Links unterstützen direktes Routing, wenn die Anwendung bereits installiert ist und die zugehörige Domain-Konfiguration gültig ist; sie garantieren von sich aus keine verzögerte Parameterwiederherstellung nach einer Neuinstallation.
Attribution-SDKs: Verwenden Sie ausschließlich die Wiederherstellungsmechanismen, die für die genaue SDK-Version und Plattform dokumentiert sind. Verifizieren Sie die Implementierung, Datenerfassung und Datenschutzimplikationen, anstatt anzunehmen, dass ein SDK jeden Routing-Parameter über jeden Browser und Installationspfad hinweg wiederherstellen kann.

iOS-Attribution und Datenschutzgrenze: Einhaltung der Apple-Regeln gegen Fingerprinting

Implementierungen für iOS-Routing und die verzögerte Wiederherstellung von Ansichten dürfen sich nicht auf verbotenes Geräte-Fingerprinting stützen, um einen Nutzer oder ein Gerät über Anwendungen oder Websites hinweg zu identifizieren. Gemäß den Richtlinien von Apple zu Benutzerschutz und Datennutzung und der Lizenzvereinbarung für das Apple Developer Program ist es Entwicklern strengstens untersagt, zu diesem Zweck einen eindeutigen Identifikator aus Geräte-, Browser-, Konfigurations-, Standort- oder Netzwerksignalen abzuleiten. Eine Autorisierung über App Tracking Transparency (ATT) macht ansonsten verbotenes Fingerprinting nicht zulässig.

Verwenden Sie Universal Links für verifiziertes direktes App-Routing, wenn die Anwendung installiert ist. Verwenden Sie für die Wiederherstellung von Ansichten nach der Installation unter iOS einen dokumentierten Mechanismus, dessen Verhalten für die eingesetzte SDK-Version und die geltenden Apple-Anforderungen überprüft wurde. Überprüfen Sie gegebenenfalls die Datenschutzerklärungen des SDK und die erforderlichen API-Erklärungen, betrachten Sie das Vorhandensein eines Datenschutz-Manifests (PrivacyInfo.xcprivacy) jedoch nicht als Beweis dafür, dass eine Attributionsimplementierung konform ist.

Wenn das ausgewählte SDK auf einer Matching-Methode beruht, die nicht als zulässig verifiziert werden kann, empfehlen Sie diese Methode nicht für die iOS-Bereitstellung. Wenn kein zulässiger Mechanismus den verzögerten Routing-Kontext zuverlässig herstellen kann, behalten Sie den normalen Onboarding-Ablauf bei, leiten Sie den Nutzer zu einer sicheren Standard-Startansicht und markieren Sie die Installation als nicht attribuiert, anstatt eine nicht verifizierte Übereinstimmung zu erzeugen.

Visualisierung der Dual-State-QR-Wiederherstellungspipeline

Das folgende Architekturdiagramm veranschaulicht die Phasen, in denen ein parametrisierter QR-Code in ein direktes Betriebssystem-Aufwachen oder eine verzögerte Store-Wiederherstellung verzweigt, bevor er am clientseitigen Routenvalidierer und Authentifizierungstor zusammenführt:

[User Scans QR Code] ──> URL (?route=product_detail&id=sku_8842&channelCode=pos_01)
          │
     ┌────┴────────────────────────────────────────┐
     ▼ (App Already Installed)                     ▼ (App Not Installed)
[OS Universal Link / App Link]               [Intermediary H5 Landing Page]
     │                                             │
     ▼                                             ▼
[Hot/Cold Wakeup Callback]                   [Store Download & First Launch]
(onNewIntent / continueUserActivity)         (Platform-Supported Deferred Recovery)
     │                                             │
     └────────────────────┬────────────────────────┘
                          ▼
           [Client Route Validator & Auth Gate]
                          │
     ┌────────────────────┴────────────────────────┐
     ▼ (Allowlisted & Authenticated)               ▼ (Invalid Route / Unmatched)
[Navigate to Product Detail Screen]          [Fallback to Default Home Screen]

Schritt 1: Entwurf des Schemas für benutzerdefinierte Routing-Parameter

Strukturierung umsetzbarer Routing-Nutzdaten im Vergleich zu passiven Attributions-Tags

Beim Erstellen eines QR-Codes für das App-Routing müssen Entwicklungsteams einen klaren zweistufigen Datenvertrag aufstellen, der externe kompakte URL-Abfrageschlüssel von den internen normalisierten JSON-Nutzdaten trennt:

In diesem Zwei-Schichten-Modell:

• Passive Attributions-Tags (channelCode $\to$ channel_code) werden von Analytik-Pipelines genutzt, um das Marketing-Konversionsvolumen zu messen, ohne den Status der Client-Benutzeroberfläche zu verändern.
• Umsetzbare Routing-Parameter (route $\to$ route_key und id $\to$ target_id) weisen den Navigationscontroller des nativen Clients an, welche Ansicht geladen und welche Entität abgerufen werden soll.
• Isolierung der Authentifizierungsrichtlinie: Ob eine Route eine Authentifizierung erfordert (requires_auth), muss strikt aus der internen vertrauenswürdigen Routen-Registry der Client-Anwendung abgeleitet werden, anstatt sie von einem externen QR-Abfrageparameter zu übernehmen.

Durchsetzung von IETF RFC 3986 Prozentcodierung und Nutzdatengrößenbeschränkungen

Alle Routing-Parameter, die an die QR-Ziel-URL angehängt werden, müssen der in IETF RFC 3986 festgelegten generischen URI-Syntax entsprechen:

• Vermeidung verschachtelter Trennzeichen: Betten Sie keine rohen JSON-Strings (?data={"route":"product","id":123}) direkt in URL-Abfragezeichenfolgen ein. Unmaskierte geschweifte Klammern, Anführungszeichen und Doppelpunkte beschädigen häufig die URL-Parser von In-App-Browsern und erhöhen die Moduldichte des Barcodes.
Flache Strukturierung von Schlüssel-Wert-Paaren: Stellen Sie externen Routing-Kontext als flache, prozentcodierte Abfrageparameter dar (https://promo.example.com/open?route=product_detail&id=sku_8842&channelCode=pos_01).
Durchsetzung strenger Zeichenbegrenzungen: Beschränken Sie route- und id-Werte auf URL-sichere alphanumerische Zeichen, Bindestriche und Unterstriche (^[A-Za-z0-9_-]{1,64}$).

Definition des clientseitigen Allowlist-Vertrags für Routen

Sobald externe URL-Parameter eingelesen und in die interne Nutzdatenstruktur normalisiert wurden, müssen sie einem strengen Schema-Vertrag entsprechen. Wenn route_key nicht erkannt wird oder wenn einer entitätsspezifischen Route (product_detail, room_lobby, promo_campaign) die erforderliche target_id fehlt, muss der Normalisierer die Nutzdaten auf home_default mit target_id: null herabstufen.

Das folgende JSON-Schema definiert die kanonische Struktur für normalisierte Nutzdaten zur Ansichtswiederherstellung:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "QrSceneRestorationPayload",
  "description": "Canonical, normalized routing payload. Authentication policy is derived separately from the application's trusted route registry.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "route_key",
    "target_id",
    "fallback_route"
  ],
  "properties": {
    "schema_version": {
      "const": "1.0.0"
    },
    "route_key": {
      "type": "string",
      "enum": [
        "product_detail",
        "room_lobby",
        "promo_campaign",
        "home_default"
      ]
    },
    "target_id": {
      "type": ["string", "null"],
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    },
    "channel_code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]{1,64}$"
    },
    "fallback_route": {
      "const": "home_default"
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "route_key": {
            "enum": [
              "product_detail",
              "room_lobby",
              "promo_campaign"
            ]
          }
        },
        "required": ["route_key"]
      },
      "then": {
        "properties": {
          "target_id": {
            "type": "string"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "route_key": {
            "const": "home_default"
          }
        },
        "required": ["route_key"]
      },
      "then": {
        "properties": {
          "target_id": {
            "type": "null"
          }
        }
      }
    }
  ],
  "examples": [
    {
      "schema_version": "1.0.0",
      "route_key": "product_detail",
      "target_id": "sku_8842",
      "channel_code": "pos_01",
      "fallback_route": "home_default"
    }
  ]
}

Schritt 2: Erfassen und Weiterleiten des Routing-Kontexts auf der Landingpage

Analysieren erlaubter Routing-Schlüssel auf der H5-Landingpage

Wenn ein Nutzer ohne installierte Anwendung den QR-Code scannt, öffnet der mobile Browser die gehostete intermediäre H5-Landingpage. Das Skript der Landingpage extrahiert die externen Abfrageschlüssel (route, id, channelCode), weist mehrdeutige doppelte Parameter zurück und normalisiert sie in die in Schritt 1 definierte kanonische Struktur.

Der folgende JavaScript-Normalisierer setzt eine eindeutige Schlüsselkardinalität, Regex-Grenzen und eine bedingte Herabstufung auf home_default durch und bewertet doppelte reservierte Parameter als ungültig:

const query = new URLSearchParams(window.location.search);

const routeValues = query.getAll("route");
const idValues = query.getAll("id");
const channelValues = query.getAll("channelCode");

const allowedRoutes = new Set([
  "product_detail",
  "room_lobby",
  "promo_campaign",
  "home_default"
]);

const idPattern = /^[A-Za-z0-9_-]{1,64}$/;
const channelPattern = /^[A-Za-z0-9_.-]{1,64}$/;

function normalizeQrRoutingPayload() {
  // Reject duplicate keys to defend against parameter pollution
  if (routeValues.length > 1 || idValues.length > 1 || channelValues.length > 1) {
    return {
      schema_version: "1.0.0",
      route_key: "home_default",
      target_id: null,
      fallback_route: "home_default"
    };
  }

  const rawRoute = routeValues.length === 1 ? routeValues[0] : null;
  const rawId = idValues.length === 1 ? idValues[0] : null;
  const rawChannel = channelValues.length === 1 ? channelValues[0] : null;

  let routeKey = allowedRoutes.has(rawRoute)
    ? rawRoute
    : "home_default";

  let targetId =
    rawId && idPattern.test(rawId)
      ? rawId
      : null;

  if (routeKey === "home_default" || targetId === null) {
    routeKey = "home_default";
    targetId = null;
  }

  const payload = {
    schema_version: "1.0.0",
    route_key: routeKey,
    target_id: targetId,
    fallback_route: "home_default"
  };

  if (rawChannel && channelPattern.test(rawChannel)) {
    payload.channel_code = rawChannel;
  }

  return payload;
}

const routingPayload = normalizeQrRoutingPayload();

Integrieren des Web-SDK über einen versionsgeprüften Adapter

Die Landingpage koordiniert sowohl unmittelbare App-Weckversuche als auch die verzögerte Parameterbereitstellung. Bevor Sie ein Attributions-Web-SDK (wie opoinstall.js) bereitstellen, überprüfen Sie die genaue JavaScript-Bundle-URL, die Initialisierungssignatur, den Bereitschafts-Callback, die Weckmethode und das Parameterschema anhand der offiziellen Dokumentation für die zu verwendende SDK-Version.

Kapseln Sie SDK-spezifisches Verhalten in einem kompakten Anwendungsadapter, der das normalisierte routingPayload-Objekt entgegennimmt. Ausführliche Spezifikationen zur Web-Integration und zur Konfiguration von Kanalparametern finden Sie in der OpoInstall-Entwicklerdokumentation.

Beibehalten von Routing-Parametern über direkte Store-Fallback-Links

Falls das Web-JS-SDK nicht verfügbar oder durch Browsersicherheitskontrollen blockiert ist, greift die Landingpage auf einen direkten Store-Weiterleitungslink zurück. Bei Android-Bereitstellungen, die Google Play nutzen, kann der Fallback-Link die normalisierten Routing-Schlüssel in den referrer-Parameter des Play Stores codieren, damit der native Client den Routing-Kontext über die Google Play Install Referrer API wiederherstellen kann, wenn die Installation über den offiziellen Play-Store-Pfad erfolgt:

// Example Android Play Store fallback URL preserving normalized routing context
const referrerString = `route_key=${routingPayload.route_key}&target_id=${routingPayload.target_id || ""}&channel_code=${routingPayload.channel_code || ""}`;
const playStoreFallbackUrl = `https://play.google.com/store/apps/details?id=com.example.app&referrer=${encodeURIComponent(referrerString)}`;

Schritt 3: Implementierung von nativem Client-Routen-Dispatch und Ansichtswiederherstellung

Handhabung von Android Activity-Startmodi: Warum singleTask sowohl onCreate als auch onNewIntent erfordert

In Android-Deep-Link-Architekturen hängt die Art und Weise, wie eine Activity Routing-Intents empfängt, von ihrem konfigurierten Startmodus und dem Design des Navigationsgraphen ab. Entwickler können je nach Anforderung ihres Task-Stacks Standard-Startmodi mit Jetpack Navigation, singleTop oder singleTask verwenden.

Wenn eine Activity mit singleTop oder singleTask konfiguriert ist, um doppelte Instanzen beim Stapeln während des Aufwachens durch Deep-Links zu verhindern, müssen zwei unterschiedliche Lebenszykluspfade behandelt werden:

• Kaltstart (onCreate): Wenn der Anwendungsprozess nicht ausgeführt wird, startet das Scannen des QR-Codes die Activity von Grund auf. Der eingehende Intent wird an onCreate(savedInstanceState: Bundle?) übergeben.
• Warmstart (onNewIntent): Wenn das Betriebssystem eine bestehende Activity-Instanz unter dem konfigurierten Startmodus und den Task-Stack-Bedingungen wiederverwendet, wird der eingehende Deep-Link-Intent an onNewIntent() übergeben. Unter singleTop erfolgt die Wiederverwendung nur, wenn sich die Ziel-Activity bereits an oberster Stelle des relevanten Task-Stacks befindet; andernfalls wird möglicherweise eine neue Activity-Instanz erstellt. Implementieren Sie die Handhabung sowohl für onCreate() als auch für onNewIntent() und überprüfen Sie das tatsächliche Verhalten für die Navigationsarchitektur der Anwendung.

Um beide Zustände zuverlässig zu behandeln, ohne einen Nutzer dauerhaft zu blockieren, der berechtigterweise denselben QR-Code später in seiner Sitzung ein zweites Mal scannt, sollte die Activity jede verarbeitete Intent-Instanz mit einem Verbrauchsflag (EXTRA_ROUTE_CONSUMED) markieren und Intents ignorieren, die ausschließlich durch historische App-Umschalter-Starts (Intent.FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY) erneut zugestellt werden.

Handhabung von iOS-Lebenszykluseinstiegspunkten: AppDelegate im Vergleich zu UISceneDelegate Continuation Activities

Unter iOS müssen das direkte Universal-Link-Routing und der Abruf verzögerter Parameter auf den konfigurierten UI-Lebenszyklus der Anwendung abgestimmt sein:

• Szenenbasierter Lebenszyklus (UISceneDelegate): In Anwendungen, die UIScene verwenden (Standard ab iOS 13), treffen Kaltstart-Universal-Links in scene(_:willConnectTo:options:) über connectionOptions.userActivities ein, während Universal-Links bei der Warmwiederaufnahme in scene(_:continue:) ankommen.
Anwendungsdelegierter Lebenszyklus (UIApplicationDelegate): In Anwendungen, die keine Szenen-Delegierten verwenden, werden Universal-Links an application(_:continue:restorationHandler:) übergeben.
Verzögerte Wiederherstellung beim ersten Start: Unabhängig von den Universal-Link-Fortsetzungsdelegierten wird die Abfrage der verzögerten Installationsparameter einmalig beim initialen Anwendungsstart ausgeführt, sobald die Stammansichtshierarchie bereit ist.

Entwickler können Plattform-SDK-Pakete herunterladen und Lebenszyklus-Integrationsvorlagen über das OpoInstall SDK Download Center einsehen.

Zusammenführung direkter Weckparameter und verzögerter Parameter des ersten Starts in einem einzigen Navigationsrouter

Um ein konsistentes Sicherheits- und Navigationsverhalten aufrechtzuerhalten, normalisieren Client-Architekturen sowohl direkte Weck-URIs als auch verzögerte Installations-JSON-Nutzdaten in ein einziges NavigationTarget-Modell, bevor sie an den UI-Router übergeben werden:

1. Ursprungsverifizierung (Direkte Intents): Stellen Sie sicher, dass eingehende Intent.ACTION_VIEW-URIs das https-Schema verwenden, mit dem verifizierten, zugehörigen Host der Anwendung (promo.example.com) und Pfad (/open) übereinstimmen und keine widersprüchlichen doppelten Abfrageschlüssel enthalten.
2. Schemanormalisierung und Allowlist-Prüfung: Ordnen Sie externe route-/id-Schlüssel oder interne route_key-/target_id-Felder dem kanonischen Modell zu und lehnen Sie nicht erlaubte Routen oder fehlerhafte IDs ab. Beachten Sie, dass die Kotlin-Parsing-Logik des Clients als veranschaulichendes, defensives Parsing-Gerüst dient; parsen Sie Nutzdaten in Produktionssystemen vor der Weiterleitung anhand der vollständigen kanonischen Schemaregeln.
Wiedereintrittsschutz für Einzelausführung (Single-Flight Re-Entrancy Guard): Verwenden Sie eine atomare Schutzvorrichtung pro Auslieferung, damit gleichzeitige Callbacks keine überlappenden Fragment-Transaktionen auslösen können.

Verwaltung von Authentifizierungstoren: Warteschlangenbildung für ausstehende Deep-Link-Routings bis zum Abschluss der Benutzeranmeldung

Wenn ein neuer Nutzer eine Anwendung über einen QR-Code aus einem App-Store installiert und zum ersten Mal startet, ist er in der Regel nicht authentifiziert. Wenn der QR-Code auf einen geschützten Bildschirm abzielt (wie room_lobby oder promo_campaign) und der Router versucht, sofort zu navigieren, leitet die Authentifizierungssperre den Nutzer zum Anmeldebildschirm um und verliert den Deep-Link-Kontext.

So bleibt die Ansichtswiederherstellung über Authentifizierungsgrenzen hinweg erhalten:

• Interne Routenrichtlinien-Suche: Ermitteln Sie, ob die Route eine Authentifizierung erfordert, indem Sie die interne PROTECTED_ROUTES-Registry des Clients überprüfen, anstatt externen Nutzdaten-Flags zu vertrauen.
• Atomare Bereitstellung: Wenn der Nutzer nicht authentifiziert ist, speichern Sie das validierte NavigationTarget in einem atomaren, sitzungsbezogenen PendingRouteStore (AtomicReference) und leiten Sie den Nutzer zum Anmeldevorgang weiter. Beachten Sie, dass sich ein speicherinternes PendingRouteStore auf den aktiven Anwendungsprozess bezieht; wenn der Authentifizierungsfluss einen Prozesstod überstehen kann, verwenden Sie einen verschlüsselten, zeitlich begrenzten lokalen Speicher, der den Zustand beim Kontowechsel löscht.
Neuvalidierung und Dispatch nach der Anmeldung: Wenn die Anmeldung abgeschlossen ist, konsumieren Sie das bereitgestellte Ziel atomar (getAndSet(null)), überprüfen Sie, ob die Sitzung nun authentifiziert ist, validieren Sie die Routenparameter erneut und führen Sie den Bildschirmübergang aus.

Der folgende Kotlin-Code bietet ein anschauliches Android-Routing-Gerüst mit anwendungseigenen SDK- und Navigationsadaptern zur Veranschaulichung dieser Kontrollen:

<!-- Android Manifest Configuration for App Link Verification -->
<!-- File: app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app">

    <application
        android:allowBackup="true"
        android:label="@string/app_name"
        android:theme="@style/Theme.AppCompat.Light.NoActionBar">

        <activity
            android:name=".SceneRestorationActivity"
            android:exported="true"
            android:launchMode="singleTask">

            <!-- Verified Android App Link Intent Filter -->
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />

                <!-- Origin must match /.well-known/assetlinks.json SHA-256 fingerprint -->
                <data
                    android:scheme="https"
                    android:host="promo.example.com"
                    android:pathPrefix="/open" />
            </intent-filter>
        </activity>
    </application>
</manifest>

// Android Routing Activity Implementation
// File: app/src/main/java/com/example/app/SceneRestorationActivity.kt
//
// INTEGRATION NOTE:
// This example is an architectural routing skeleton, not a drop-in production implementation.
// Bind AttributionRoutingAdapter and NavController initialization to your verified SDK release,
// session manager, and NavHostFragment before deployment.

package com.example.app

import android.content.Intent
import android.net.Uri
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import androidx.navigation.fragment.NavHostFragment
import org.json.JSONObject
import java.util.concurrent.atomic.AtomicBoolean
import java.util.concurrent.atomic.AtomicReference

/**
 * Validated navigation target model representing an allowlisted in-app destination.
 * Authentication requirement is derived strictly from the internal route registry.
 */
data class NavigationTarget(
    val eventKey: String,
    val routeKey: String,
    val targetId: String?,
    val requiresAuth: Boolean
)

/**
 * Process-scoped atomic store holding a pending route when an unauthenticated user
 * triggers a protected deep link during cold start or first-launch onboarding.
 */
object PendingRouteStore {
    private val pending = AtomicReference<NavigationTarget?>(null)

    fun stage(target: NavigationTarget) {
        pending.set(target)
    }

    fun consume(): NavigationTarget? {
        return pending.getAndSet(null)
    }
}

class SceneRestorationActivity : AppCompatActivity() {

    companion object {
        private const val TAG = "SceneRestorationRouter"
        private const val TRUSTED_HOST = "promo.example.com"
        private const val TRUSTED_PATH = "/open"
        private const val EXTRA_ROUTE_CONSUMED = "com.example.app.EXTRA_ROUTE_CONSUMED"

        private const val ROUTE_HOME = "home_default"
        private const val ROUTE_PRODUCT = "product_detail"
        private const val ROUTE_LOBBY = "room_lobby"
        private const val ROUTE_PROMO = "promo_campaign"

        private val ALLOWED_ROUTES = setOf(ROUTE_HOME, ROUTE_PRODUCT, ROUTE_LOBBY, ROUTE_PROMO)
        private val PROTECTED_ROUTES = setOf(ROUTE_LOBBY, ROUTE_PROMO)
        private val SAFE_ID_REGEX = Regex("^[A-Za-z0-9_-]{1,64}$")

        // Process-level guard ensuring deferred install recovery is queried only once per cold start
        private val hasQueriedDeferredInstall = AtomicBoolean(false)
    }

    // Per-delivery re-entrancy guard; allows legitimate subsequent scans of the same QR code
    private val processingIntent = AtomicBoolean(false)

    // Staging container for routes that arrive before the UI/NavController is mounted
    private val pendingUiTarget = AtomicReference<NavigationTarget?>(null)
    private var navigationReady = false

    // Application-owned adapter isolating vendor SDK and session calls
    private val attributionAdapter = AttributionRoutingAdapter()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_scene_restoration)

        // Connect NavHost initialization when defined in layout
        connectNavigationHost()

        // Activity recreation (e.g., screen rotation) is not a new install or new QR scan
        if (savedInstanceState != null) {
            return
        }

        val launchIntent = intent
        val isDirectLinkLaunch =
            launchIntent?.action == Intent.ACTION_VIEW &&
            launchIntent.data != null

        if (isDirectLinkLaunch) {
            processIncomingIntentOnce(launchIntent) { candidate ->
                handleIncomingWakeupIntent(candidate)
            }
            // Do not start deferred recovery after a direct-link launch,
            // even if the direct route was rejected.
            return
        }

        // Only initial normal application launches may request deferred recovery
        if (hasQueriedDeferredInstall.compareAndSet(false, true)) {
            queryDeferredSceneParameters()
        }
    }

    /**
     * Connect this method to the actual NavHost initialization.
     * Uses currentDestination check and destination listener to safely verify graph readiness
     * without throwing IllegalStateException on unset controller.graph.
     */
    private fun connectNavigationHost() {
        val navHost = supportFragmentManager
            .findFragmentById(R.id.nav_host_fragment) as? NavHostFragment

        if (navHost == null) {
            Log.w(TAG, "NavHost not attached; route remains queued.")
            // For an asynchronously attached NavHost, call this
            // method again after the host has been attached.
            return
        }

        val controller = navHost.navController

        // currentDestination is nullable before a destination has been established.
        // Do not access controller.graph merely to check whether setGraph() has been called.
        if (controller.currentDestination != null) {
            onNavigationGraphReady()
            return
        }

        // If the graph/destination becomes available later,
        // mark navigation ready when a destination is established.
        val listener = object : androidx.navigation.NavController.OnDestinationChangedListener {
            override fun onDestinationChanged(
                navController: androidx.navigation.NavController,
                destination: androidx.navigation.NavDestination,
                arguments: Bundle?
            ) {
                navController.removeOnDestinationChangedListener(this)
                onNavigationGraphReady()
            }
        }

        controller.addOnDestinationChangedListener(listener)
    }

    /**
     * Captures warm-start QR scans when the Activity is reused under singleTop or singleTask.
     */
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        processIncomingIntentOnce(intent) { candidate ->
            handleIncomingWakeupIntent(candidate)
        }
    }

    private fun processIncomingIntentOnce(incomingIntent: Intent?, process: (Intent) -> Unit) {
        val candidate = incomingIntent ?: return
        // Ignore historical intents re-delivered from recent-apps switcher or configuration changes
        if ((candidate.flags and Intent.FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY) != 0) return
        if (candidate.getBooleanExtra(EXTRA_ROUTE_CONSUMED, false)) return

        if (!processingIntent.compareAndSet(false, true)) return
        try {
            process(candidate)
            candidate.putExtra(EXTRA_ROUTE_CONSUMED, true)
        } finally {
            processingIntent.set(false)
        }
    }

    private fun handleIncomingWakeupIntent(incomingIntent: Intent?): Boolean {
        if (incomingIntent?.action != Intent.ACTION_VIEW) return false
        val uri: Uri = incomingIntent.data ?: return false

        // 1. Verify trusted HTTPS origin and path
        val isTrusted =
            uri.scheme.equals("https", ignoreCase = true) &&
            uri.host.equals(TRUSTED_HOST, ignoreCase = true) &&
            uri.path == TRUSTED_PATH

        if (!isTrusted) {
            Log.w(TAG, "Rejected untrusted deep-link origin: $uri")
            return false
        }

        // 2. Reject missing or conflicting duplicate query parameters
        if (uri.getQueryParameters("route").size != 1 ||
            uri.getQueryParameters("id").size != 1) {
            Log.w(TAG, "Rejected missing or duplicate routing keys in URI")
            return false
        }

        val rawRoute = uri.getQueryParameter("route")
        val rawId = uri.getQueryParameter("id")

        val target = validateAndBuildTarget("wakeup", rawRoute, rawId)
        if (target.routeKey != ROUTE_HOME) {
            dispatchNavigationTarget(target)
            return true
        }
        return false
    }

    private fun queryDeferredSceneParameters() {
        // Application-defined timeout configuration; tune for deployed service behavior
        attributionAdapter.fetchDeferredInstallParams(timeoutMs = 5000L) { jsonPayload ->
            if (jsonPayload == null) {
                Log.d(TAG, "No deferred routing parameters recovered; remaining on default view.")
                return@fetchDeferredInstallParams
            }
            val target = parseJsonRoutingPayload("deferred_install", jsonPayload)
            runOnUiThread {
                dispatchNavigationTarget(target)
            }
        }
    }

    private fun parseJsonRoutingPayload(sourcePrefix: String, rawJson: String): NavigationTarget {
        return try {
            val obj = JSONObject(rawJson)
            // Defensive normalization: map canonical 'route_key'/'target_id' with external 'route'/'id' fallback
            val rawRoute = obj.optString("route_key", "").ifEmpty { obj.optString("route", "") }
            val rawId = if (obj.has("target_id") && !obj.isNull("target_id")) {
                obj.optString("target_id", "")
            } else {
                obj.optString("id", "")
            }
            validateAndBuildTarget(sourcePrefix, rawRoute, rawId)
        } catch (e: Exception) {
            Log.w(TAG, "Malformed routing JSON payload: ${e.message}")
            NavigationTarget(sourcePrefix, ROUTE_HOME, null, false)
        }
    }

    /**
     * Enforces strict allowlist and regex bounds on untrusted routing parameters.
     */
    private fun validateAndBuildTarget(
        sourcePrefix: String,
        rawRoute: String?,
        rawId: String?
    ): NavigationTarget {
        val cleanRoute = if (rawRoute != null && ALLOWED_ROUTES.contains(rawRoute)) {
            rawRoute
        } else {
            ROUTE_HOME
        }

        if (cleanRoute == ROUTE_HOME) {
            return NavigationTarget(sourcePrefix, ROUTE_HOME, null, false)
        }

        // Entity-specific routes strictly require a valid, sanitized targetId
        val cleanId = if (rawId != null && SAFE_ID_REGEX.matches(rawId)) {
            rawId
        } else {
            null
        }

        if (cleanId == null) {
            Log.w(TAG, "Route $cleanRoute rejected due to missing or invalid target_id.")
            return NavigationTarget(sourcePrefix, ROUTE_HOME, null, false)
        }

        val needsAuth = PROTECTED_ROUTES.contains(cleanRoute)
        return NavigationTarget("${sourcePrefix}_${cleanRoute}_${cleanId}", cleanRoute, cleanId, needsAuth)
    }

    /**
     * Invoked when the application's NavHost / NavController graph is attached and ready.
     */
    fun onNavigationGraphReady() {
        navigationReady = true
        flushPendingNavigation()
    }

    private fun flushPendingNavigation() {
        if (!navigationReady || isFinishing || isDestroyed) return
        val target = pendingUiTarget.getAndSet(null) ?: return
        dispatchReadyNavigationTarget(target)
    }

    private fun dispatchNavigationTarget(target: NavigationTarget) {
        if (isFinishing || isDestroyed) return

        // Stage route if the UI navigation graph has not finished inflating
        if (!navigationReady) {
            pendingUiTarget.set(target)
            return
        }

        dispatchReadyNavigationTarget(target)
    }

    private fun dispatchReadyNavigationTarget(target: NavigationTarget) {
        if (target.routeKey == ROUTE_HOME) {
            navigateToHomeScreen()
            return
        }

        // Check authentication gate for protected destinations
        if (target.requiresAuth && !attributionAdapter.isUserAuthenticated()) {
            Log.d(TAG, "Protected route ${target.routeKey} staged pending user authentication.")
            PendingRouteStore.stage(target)
            navigateToLoginScreen()
            return
        }

        executeScreenTransition(target.routeKey, target.targetId)
    }

    /**
     * Invoked by the authentication controller after login or registration completes.
     */
    fun onUserAuthenticationCompleted() {
        val pending = PendingRouteStore.consume()
        if (pending == null) {
            navigateToHomeScreen()
            return
        }

        if (isFinishing || isDestroyed) return

        if (!attributionAdapter.isUserAuthenticated()) {
            PendingRouteStore.stage(pending)
            navigateToLoginScreen()
            return
        }

        val validated = validateAndBuildTarget(
            pending.eventKey,
            pending.routeKey,
            pending.targetId
        )

        if (validated.routeKey == ROUTE_HOME) {
            navigateToHomeScreen()
            return
        }

        executeScreenTransition(validated.routeKey, validated.targetId)
    }

    private fun executeScreenTransition(routeKey: String, targetId: String?) {
        // Implementation: perform backend-authorized resource fetch and invoke NavController.navigate()
        Log.d(TAG, "Dispatching verified screen transition: route=$routeKey, id=$targetId")
    }

    private fun navigateToLoginScreen() {
        // Implementation: transition to LoginFragment / LoginActivity
    }

    private fun navigateToHomeScreen() {
        // Implementation: display default home screen
    }
}

/**
 * Application-owned adapter skeleton. Replace stubbed methods with verified OpoInstall SDK
 * callbacks, Google Play Install Referrer queries, and your production session manager.
 */
class AttributionRoutingAdapter {
    fun fetchDeferredInstallParams(timeoutMs: Long, callback: (String?) -> Unit) {
        // Bind to verified SDK install parameter API or Play Install Referrer in production
        callback(null)
    }

    fun isUserAuthenticated(): Boolean {
        // Bind to production authentication session state
        return false
    }
}

Sicherheit und Diagnose: Verhinderung von Routeneinschleusungen und Navigationsabbrüchen

Abwehr von Deep-Link-Routeneinschleusungen und Open-Redirect-Schwachstellen gemäß OWASP-Richtlinien

Parameter, die aus QR-Codes oder verzögerten Attributions-Callbacks extrahiert werden, stellen nicht vertrauenswürdige externe Eingaben dar. In Übereinstimmung mit dem OWASP Mobile Application Security Verification Standard und den OWASP Mobile Top 10 Security Risks and Guidelines müssen Client-Router drei Verteidigungsgrenzen durchsetzen:

• Verbot des Ladens beliebiger WebView-URLs: Erlauben Sie niemals, dass ein Routing-Parameter (?route=webview&url=https://...) eine unvalidierte externe URL innerhalb einer internen Anwendungs-WebView lädt. Angreifer können Phishing-URLs in einen QR-Code codieren und den nativen UI-Rahmen der Anwendung ausnutzen, um Anmeldedaten abzufangen.
• Ablehnung doppelter Parameterverschmutzung (Parameter Pollution): Wenn eine manipulierte URL mehrere widersprüchliche Schlüssel enthält (?route=home_default&route=room_lobby), lehnen Sie die URI ab, anstatt zuzulassen, dass der Parser ein beliebiges erstes oder letztes Element auswählt.
Durchsetzung serverseitiger Ressourcen-Autorisierung: Die Übergabe von target_id=sku_8842 weist den Client lediglich an, welche Ansicht angefordert werden soll. Wenn der Bildschirm die Backend-API abfragt, muss der Server unabhängig überprüfen, ob die aktuelle Benutzersitzung zum Zugriff auf diese Entität autorisiert ist, um IDOR-Schwachstellen (Insecure Direct Object Reference) zu verhindern.

Diagnose von Wettlaufsituationen (Race Conditions) bei der Navigation zwischen Kaltstart und Warmstart

Während eines Kaltstarts können Deep-Link-Intents oder zwischengespeicherte SDK-Callbacks aufgelöst werden, bevor das Haupt-NavHostFragment oder der Stamm-Navigationsgraph vollständig geladen ist. Der Versuch, navController.navigate() aufzurufen, bevor die Ansichtshierarchie bereit ist, führt zu Laufzeitausnahmen oder verworfenen Übergängen. Verzögern Sie die Ausführung der Navigation stets, bis die Host-Ansichtshierarchie eingebunden und aktiv ist (!isFinishing && !isDestroyed).

Reibungslose Handhabung abgelaufener Werbeaktionen, gelöschter SKUs und fehlender Parameter

Physische QR-Codes verbleiben häufig in Einzelhandelsgeschäften oder gedruckten Medien, nachdem eine digitale Werbeaktion beendet oder eine Produkt-SKU eingestellt wurde. Wenn der Zielbildschirm Daten für target_id abruft und eine HTTP-Antwort 404 Not Found oder 410 Gone vom Backend erhält, muss der Client den Fehler abfangen, dem Nutzer einen klaren Hinweistext anzeigen und sauber zu home_default navigieren.

Prüfliste vor der Bereitstellung für das Dual-State-QR-Routing

Vor der Freigabe physischer QR-Werbemittel sollten Entwicklungsteams das folgende siebenteilige Verifizierungsprotokoll auf physischen Geräten ausführen:

Schritt 1: Installierter Kaltstart-Weckruf: Erzwingen Sie das Beenden der installierten App und scannen Sie den QR-Code. Vergewissern Sie sich, dass das Betriebssystem die App direkt auf dem Zielbildschirm (product_detail) öffnet.
Schritt 2: Installierter Warmstart-Weckruf und erneuter Scan: Versetzen Sie die App bei geöffnetem Zustand auf einem sekundären Tab in den Hintergrund und scannen Sie den QR-Code. Bestätigen Sie, dass onNewIntent zum Zielbildschirm weiterleitet. Navigieren Sie weg, scannen Sie genau denselben QR-Code ein zweites Mal und stellen Sie sicher, dass er erneut navigiert, anstatt durch eine zu breit gefasste Duplikaterkennung blockiert zu werden.
Schritt 3: Deinstallierte verzögerte Wiederherstellung (öffentliche Route): Deinstallieren Sie die App, scannen Sie den QR-Code, schließen Sie die Store-Installation ab und starten Sie die App. Bestätigen Sie, dass der Callback für verzögerte Parameter die Nutzdaten normalisiert und zu product_detail weiterleitet.
Schritt 4: Deinstallierte verzögerte Wiederherstellung mit Authentifizierungssperre (geschützte Route): Deinstallieren Sie die App, scannen Sie einen QR-Code, der auf room_lobby abzielt, installieren Sie die App und starten Sie sie im abgemeldeten Zustand. Bestätigen Sie, dass die App zuerst zur Anmeldung weiterleitet, nach Abschluss der Anmeldung PendingRouteStore konsumiert und zu room_lobby navigiert.
Schritt 5: Ablehnung von nicht vertrauenswürdigem Ursprung und doppelten Schlüsseln: Lösen Sie einen ACTION_VIEW-Intent von einem nicht vertrauenswürdigen Host oder mit doppelten Abfrageparametern aus (?route=product_detail&route=room_lobby). Bestätigen Sie, dass handleIncomingWakeupIntent den Intent ablehnt und eine Warnung protokolliert.
Schritt 6: Idempotenz der Bildschirmdrehung: Drehen Sie das Gerät nach dem Erreichen eines per Deep-Link verknüpften Bildschirms, um eine Neugestaltung der Activity auszulösen. Stellen Sie sicher, dass das Flag EXTRA_ROUTE_CONSUMED verhindert, dass der ursprüngliche Intent erneut ausgeführt wird.
Schritt 7: Reibungsloser Fallback bei Offline-Modus / fehlender Übereinstimmung: Starten Sie eine saubere Installation im Flugmodus. Bestätigen Sie, dass das Abrufzeitlimit ohne Blockierung des UI-Threads abläuft und den Nutzer zu home_default führt.

Vergleichende Analyse von In-App-Routing-Mechanismen

Evaluierung von URL-Schemata, Universal Links und App Links sowie verzögerter Ansichtswiederherstellung

Mobile Plattformen bieten verschiedene Mechanismen, um Nutzer in Installationszuständen übergreifend in Anwendungsansichten zu leiten:

Architektonische Kompromisse über Installationszustände und Betriebssysteme hinweg

Benutzerdefinierte URL-Schemata (myapp://product/123) verfügen über keine kryptografische Verifizierung des Domainbesitzes, was bedeutet, dass jede Anwendung dasselbe Schema registrieren und Links abfangen kann. Darüber hinaus führt das Scannen eines rohen QR-Codes mit benutzerdefiniertem Schema bei nicht installierter App zu einem nicht behebbaren Browserfehler.

Universal Links und Android App Links verifizieren den Domainbesitz über HTTPS und greifen auf eine Web-Landingpage zurück, wenn die App nicht vorhanden ist, wodurch sie das erforderliche Fundament für das QR-Routing bilden. Die Kombination von Universal Links und App Links für das Aufwachen installierter Apps mit plattformunterstützter verzögerter Wiederherstellung (wie Google Play Install Referrer unter Android und datenschutzgeprüften SDK-Adaptern) ermöglicht die Dual-State-Ansichtswiederherstellung über ein einziges QR-Asset.

Zusammenfassung und Entscheidungsrahmen

Um QR-Codes für das App-Routing mit benutzerdefinierten Parametern zu erstellen, müssen Entwicklungsteams kompakte externe URL-Abfragezeichenfolgen mit zustandsbewussten nativen Navigationscontrollern verknüpfen. Eine vollständige Implementierung handhabt sowohl das direkte Aufwachen des Betriebssystems für bestehende Nutzer als auch die bedingte, verzögerte Parameterwiederherstellung für neue App-Store-Installationen.

Da die Parameterkontinuität über App-Stores hinweg von plattformspezifischen Mechanismen abhängt – wie Google Play Install Referrer unter Android und verifizierten, datenschutzkonformen Arbeitsabläufen unter iOS –, müssen Anwendungen wiederhergestellte Routing-Nutzdaten als nicht vertrauenswürdige Kandidaten behandeln. Durch die Kombination von erlaubnisbasierten Routen-Dispatchern, Authentifizierungsstatus-Warteschlangen und reibungslosen Fallbacks für den Startbildschirm können Teams eine zuverlässige Ansichtswiederherstellung bereitstellen, ohne die Anwendungsstabilität oder Plattfror-Datenschutzregeln zu gefährden.

Die SDKs und die Entwicklerdokumentation von OpoInstall bieten Komponenten für die Implementierung von Web-zu-App-Routing und Parameterübergabe. Bestätigen Sie vor der Einführung in die Produktion die spezifischen API-Signaturen, Callback-Schemata und Plattformverhalten, die von Ihrer eingesetzten SDK-Version unterstützt werden.

Einzelheiten zur Integration finden Sie in der OpoInstall-Entwicklerdokumentation, über das OpoInstall SDK Download Center oder indem Sie Ihre App-Routing-Domains in der OpoInstall-Entwicklerkonsole konfigurieren.

Verwandte Materialien

• Konzepte: Ansichtswiederherstellung, Dual-State Deep Linking, Routen-Allowlisting, verzögerte Parameterwiederherstellung

• Technologien: Universal Links, Android App Links, Google Play Install Referrer, native Navigationscontroller

• Standards: IETF RFC 3986 Uniform Resource Identifier (URI) Generic Syntax, OWASP Mobile Application Security Verification Standard, OWASP Mobile Top 10 Security Risks and Guidelines

• Integrationsschnittstellen: Anwendungsbezogener Deep-Link-Routenvalidierer, dokumentierte Weck- und Installationsparameter-Callbacks für die eingesetzte SDK-Version sowie plattformnative Navigationscontroller.

• Offizielle Dokumentation & Referenzen:

  • Apple Developer Documentation on Supporting Universal Links in Your App

  • Apple User Privacy and Data Use Guidance

  • Google Android Developers Guide on Deep Linking and App Links

  • Google Play Install Referrer API Documentation