Cara Membuat Kod QR untuk Haluan Aplikasi dengan Parameter Tersuai

Bagaimanakah cara memautkan parameter tersuai semasa membuat kod QR? Memautkan parameter tersuai untuk haluan aplikasi memerlukan penambahan kunci pertanyaan URL berstruktur pada pautan halaman landas yang dihoskan, menangkap kunci tersebut melalui lapisan integrasi web, dan menghantar muatan yang disahkan kepada pengawal navigasi asli semasa pengaktifan terus aplikasi atau pelancaran pasca-pasang.

Haluan dalam aplikasi melalui kod QR ialah seni bina navigasi pelanggan-pelayan yang membenamkan parameter destinasi berstruktur ke dalam URL kod bar dua dimensi. Dengan menyelesaikan parameter ini melalui pautan mendalam sistem pengendalian terus apabila aplikasi dipasang, atau melalui pemulihan tertunda yang disokong platform apabila aplikasi baru dipasang dari kedai aplikasi, pasukan kejuruteraan boleh membawa pengguna terus ke skrin tertentu dalam aplikasi berbanding paparan utama lalai.

Gambaran Keseluruhan Seni Bina: Cara Membuat Kod QR untuk Pemulihan Adegan Aplikasi

Masalah Keciciran Skrin Utama: Mengapa Ubah Hala Kedai Generik Merosakkan Perjalanan Pengguna Berintent Tinggi

Kod QR fizikal kerap digunakan dalam persekitaran kontekstual berintent tinggi: pembeli runcit mengimbas tanda rak untuk melihat spesifikasi produk, pelanggan restoran mengimbas khemah meja untuk memesan daripada kategori menu tertentu, atau pemain mengimbas kod bar jemputan berbilang pemain untuk menyertai lobi permainan. Apabila kod bar mengekod pautan kedai aplikasi generik atau domain tanpa parameter, intent kontekstual pengguna hilang semasa peralihan daripada imbasan fizikal ke masa sandaran aplikasi asli.

Apabila melancarkan aplikasi, pengguna dijatuhkan ke skrin utama peringkat atas lalai. Memaksa pengguna menavigasi pokok kategori yang kompleks secara manual, memasukkan semula pertanyaan carian, atau menaip pengecam bilik menimbulkan geseran kognitif dan mekanikal yang ketara. Pemulihan adegan dalam aplikasi menangani keciciran ini dengan mengekod keadaan destinasi ke dalam URL kod QR dan membina semula paparan sasaran tersebut secara programatik di dalam pelanggan asli.

Mekanik Haluan Dwi-Keadaan: Pengaktifan Terus lwn. Pemulihan Adegan Tertunda

Apabila pengguna mengimbas kod QR haluan aplikasi, peranti mudah alih wujud dalam salah satu daripada dua keadaan pemasangan. Seni bina haluan yang lengkap mengendalikan kedua-dua kitaran hayat melalui laluan teknikal yang berbeza:

• Haluan Pengaktifan Terus (Aplikasi Sudah Dipasang): Apabila aplikasi sasaran sudah sedia ada pada peranti, mengimbas kod QR mencetuskan pautan mendalam sistem pengendalian—khususnya Pautan Universal Apple pada iOS atau Pautan Aplikasi Android pada Android. Kedua-dua mekanisme memerlukan pengehosan fail perkaitan domain yang disahkan secara kriptografi: iOS memerlukan fail apple-app-site-association (AASA) yang dipasangkan dengan kelayakan Associated Domains Xcode, manakala Android memerlukan fail Pautan Aset Digital /.well-known/assetlinks.json yang sepadan dengan cap jari SHA-256 sijil tandatangan aplikasi dan penapis intent manifest yang disahkan. Apabila disahkan, OS mengejutkan aplikasi dan menyampaikan URI terus kepada perwakilan kitaran hayat pelanggan.
• Pemulihan Adegan Tertunda (Aplikasi Belum Dipasang): Apabila aplikasi tiada, pengguna dihalakan melalui halaman landas web perantaraan ke kedai aplikasi platform. Oleh kerana binari asli belum dipasang untuk menerima intent sistem pengendalian, parameter haluan mesti diletakkan sebelum pengubahan hala kedai dan dipulihkan semasa pelancaran awal aplikasi (permulaan sejuk Hari 0) selepas pemasangan selesai.

Sempadan Pemulihan Khusus Platform: Rujukan Pemasangan Google Play, Pautan Universal iOS, dan Penyesuai SDK

Selepas pengguna memasang aplikasi dari kedai aplikasi, rujukan dan pemulihan parameter haluan bergantung pada platform dan mekanisme yang dilaksanakan oleh aplikasi atau SDK atribusi. Menghantar parameter route atau id melalui URL web tidak, dengan sendirinya, menjamin bahawa parameter tersebut akan terselamat daripada pemasangan kedai aplikasi:

• Android dan Google Play: API Rujukan Pemasangan Google Play boleh menyediakan metadata rujukan disokong yang dikaitkan dengan pemasangan Gedung Play. Mekanisme ini terpakai khusus untuk pemasangan yang disiapkan melalui laluan rasmi Gedung Play Google, bukan muat sisi APK pihak ketiga arbitrari atau kedai alternatif. Aplikasi mesti mengkonfigurasi dan menguji muatan rujukan sebenar serta mengesahkan bahawa parameter yang dijangkakan terselamat daripada aliran ubah hala dan pemasangan.
• iOS dan App Store: App Store Apple tidak memindahkan parameter pertanyaan halaman landas web arbitrari secara automatik ke dalam binari aplikasi yang baru dipasang. Pautan Universal menyokong haluan terus apabila aplikasi sudah dipasang dan konfigurasi domain berkaitan adalah sah; ia tidak, dengan sendirinya, menjamin pemulihan parameter tertunda selepas pemasangan baharu.
• SDK Atribusi: Gunakan hanya mekanisme pemulihan yang didokumenkan untuk versi SDK dan platform tepat yang sedang digunapakai. Sahkan implikasi pelaksanaan, pengumpulan data, dan privasi dan bukannya menganggap bahawa SDK boleh memulihkan setiap parameter haluan merentas setiap pelayar dan laluan pemasangan.

Atribusi iOS dan Sempadan Privasi: Mematuhi Peraturan Anti-Cap Jari Apple

Pelaksanaan haluan iOS dan pemulihan adegan tertunda tidak boleh bergantung pada cap jari peranti yang dilarang untuk mengenal pasti pengguna atau peranti merentas aplikasi atau laman web. Di bawah Panduan Privasi Pengguna dan Penggunaan Data Apple dan Perjanjian Lesen Program Pembangun Apple, pembangun dilarang sama sekali daripada menerbitkan pengecam unik daripada isyarat peranti, pelayar, konfigurasi, lokasi, atau rangkaian untuk tujuan ini. Kebenaran Telus Penjejakan Aplikasi (ATT) tidak menjadikan cap jari yang sepatutnya dilarang sebagai dibenarkan.

Gunakan Pautan Universal untuk haluan aplikasi terus yang disahkan apabila aplikasi dipasang. Untuk pemulihan adegan selepas pemasangan pada iOS, gunakan mekanisme didokumenkan yang tingkah lakunya telah disemak untuk versi SDK yang digunapakai dan keperluan Apple yang berkenaan. Semak pendedahan privasi SDK dan pengisytiharan API sebab yang diperlukan jika berkenaan, tetapi jangan anggap kehadiran Manifest Privasi (PrivacyInfo.xcprivacy) sebagai bukti bahawa pelaksanaan atribusi adalah patuh.

Jika SDK yang dipilih bergantung pada kaedah pemadanan yang tidak boleh disahkan sebagai dibenarkan, jangan syorkan kaedah tersebut untuk penempatan iOS. Jika tiada mekanisme dibenarkan dapat menetapkan konteks haluan tertunda dengan boleh diharap, kekalkan aliran orientasi biasa, bawa pengguna ke paparan utama lalai yang selamat, dan tandakan pemasangan sebagai tidak diagihkan berbanding mencipta padanan yang tidak disahkan.

Memvisualisasikan Paip Pemulihan Adegan QR Dwi-Keadaan

Rajah seni bina di bawah menggambarkan peringkat berikut apabila kod QR berparameter bercabang kepada pengaktifan OS terus atau pemulihan kedai tertunda sebelum menumpu pada penilai haluan sebelah pelanggan dan get pengesahan:

[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]

Langkah 1: Merekabentuk Skema Parameter Haluan Tersuai

Menstrukturkan Muatan Haluan Boleh Diambil Tindakan lwn. Tag Atribusi Pasif

Semasa membuat kod QR untuk haluan aplikasi, pasukan kejuruteraan mesti mewujudkan kontrak data dua peringkat bersih yang memisahkan kunci pertanyaan URL padat luaran daripada muatan JSON dinormalkan dalaman:

Dalam model dua peringkat ini:

• Tag Atribusi Pasif (channelCode $\to$ channel_code) dimakan oleh saluran paip analitis untuk mengukur volum penukaran pemasaran tanpa mengubah keadaan UI pelanggan.
• Parameter Haluan Boleh Diambil Tindakan (route $\to$ route_key dan id $\to$ target_id) mengarahkan pengawal navigasi pelanggan asli skrin mana yang harus dimuatkan dan entiti mana yang harus diambil.
• Pengasingan Polisi Pengesahan: Sama ada sesuatu haluan memerlukan pengesahan (requires_auth) mesti diperoleh dengan tegas daripada registri haluan dipercayai dalaman aplikasi aplikasi dan bukannya diterima daripada parameter pertanyaan QR luaran.

Menguatkuasakan Pengekodan Peratus IETF RFC 3986 dan Kekangan Saiz Muatan

Semua parameter haluan yang dilampirkan pada URL destinasi QR mesti mematuhi sintaks generik URI yang dinyatakan dalam IETF RFC 3986:

• Elakkan Pembatas Bersarang: Jangan benamkan rentetan JSON mentah (?data={"route":"product","id":123}) terus ke dalam rentetan pertanyaan URL. Kurungan, tanda petikan, dan titik bertindih yang tidak dielakkan kerap memecahkan penghala pelayar dalaman aplikasi dan melambung ketumpatan modul kod bar.
• Ratakan Pasangan Kunci-Nilai: Representasikan konteks haluan luaran sebagai parameter pertanyaan rata berkod peratus (https://promo.example.com/open?route=product_detail&id=sku_8842&channelCode=pos_01).
• Kuatkuasakan Had Aksara Ketat: Hadkan nilai route dan id kepada aksara abjad angka selamat URL, tanda sempang, dan garis bawah (^[A-Za-z0-9_-]{1,64}$).

Pentakrifan Kontrak Senarai Benar Haluan Sebelah Pelanggan

Sebaik sahaja parameter URL luaran dicerna dan dinormalkan ke dalam struktur muatan dalaman, ia mesti mematuhi kontrak skema yang ketat. Jika route_key tidak dikenali, atau jika haluan khusus entiti (product_detail, room_lobby, promo_campaign) kehilangan target_id yang diperlukan, penormal mesti menurunkan muatan kepada home_default dengan target_id: null.

Skema JSON di bawah mentakrifkan struktur kanun untuk muatan pemulihan adegan dinormalkan:

{
  "$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"
    }
  ]
}

Langkah 2: Menangkap dan Menghantar Semula Konteks Haluan pada Halaman Landas

Menghurai Kunci Haluan Tersenarai Benar pada Halaman Landas H5

Apabila pengguna tanpa aplikasi yang dipasang mengimbas kod QR, pelayar mudah alih membuka halaman landas H5 perantaraan yang dihoskan. Skrip halaman landas mengekstrak kunci pertanyaan luaran (route, id, channelCode), menolak parameter duplikasi yang kabur, dan menormalkannya ke dalam struktur kanun yang ditakrifkan dalam Langkah 1.

Penormal JavaScript di bawah menguatkuasakan kardinaliti kunci tunggal, batas regex, dan penurunan taraf home_default bersyarat sambil merawat parameter rizab duplikasi sebagai tidak sah:

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();

Mengintegrasikan SDK Web Melalui Penyesuai yang Disahkan Versi

Halaman landas menyelaras kedua-dua percubaan bangun aplikasi serta-merta dan pementasan parameter tertunda. Sebelum menggunakan SDK Web atribusi (seperti opoinstall.js), sahkan URL berkas JavaScript tepat, tandatangan permulaan, panggilan balik kesediaan, kaedah bangun, dan skema parameter berbanding dokumentasi rasmi untuk versi SDK yang sedang digunakan.

Kekalkan tingkah laku khusus SDK di sebalik penyesuai aplikasi kecil yang menerima objek routingPayload yang dinormalkan. Untuk spesifikasi terperinci mengenai integrasi web dan konfigurasi parameter saluran, rujuk dokumentasi pembangun OpoInstall.

Mengekalkan Parameter Haluan Merentas Pautan Fallback Kedai Terus

Jika SDK Web JS tidak tersedia atau disekat oleh kawalan keselamatan pelayar, halaman landas beralih kepada pautan ubah hala kedai terus. Pada penempatan Android yang menggunakan Google Play, pautan fallback boleh mengekod kunci haluan yang dinormalkan ke dalam parameter referrer Gedung Play supaya pelanggan asli boleh memulihkan konteks haluan melalui API Rujukan Pemasangan Google Play apabila dipasang melalui aliran rasmi Gedung Play:

// 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)}`;

Langkah 3: Melaksanakan Penghantaran Haluan Pelanggan Asli dan Pemulihan Adegan

Mengendalikan Mod Pelancaran Aktiviti Android: Mengapa singleTask Memerlukan Kedua-dua onCreate dan onNewIntent

Dalam seni bina pautan mendalam Android, cara Aktiviti menerima intent haluan bergantung pada mod pelancaran yang dikonfigurasikan dan reka bentuk graf navigasi. Pembangun boleh menggunakan mod pelancaran standard dengan Navigasi Jetpack, singleTop, atau singleTask bergantung pada keperluan tindanan tugas mereka.

Apabila Aktiviti dikonfigurasikan dengan singleTop atau singleTask untuk mengelakkan tika duplikasi daripada bertindan semasa pengaktifan pautan mendalam, dua laluan kitaran hayat yang berbeza mesti dikendalikan:

• Permulaan Sejuk (onCreate): Apabila proses aplikasi tidak berjalan, mengimbas kod QR melancarkan Aktiviti dari awal. Intent yang masuk dihantar kepada onCreate(savedInstanceState: Bundle?).
• Permulaan Suam (onNewIntent): Apabila sistem pengendalian menggunakan semula tika Aktiviti sedia ada di bawah mod pelancaran yang dikonfigurasikan dan syarat tindanan tugas, Intent pautan mendalam yang masuk dihantar kepada onNewIntent(). Di bawah singleTop, penggunaan semula berlaku hanya apabila Aktiviti sasaran sudah berada di bahagian atas tindanan tugas yang berkaitan; jika tidak, tika Aktiviti baharu mungkin dicipta. Laksanakan pengendalian onCreate() dan onNewIntent(), dan sahkan tingkah laku sebenar untuk seni bina navigasi aplikasi.

Untuk mengendalikan kedua-dua keadaan dengan pasti tanpa menyekat pengguna yang secara sah mengimbas kod QR yang sama buat kali kedua kemudian dalam sesi mereka secara kekal, Aktiviti harus menandakan setiap tika Intent yang diproses dengan bendera penggunaan (EXTRA_ROUTE_CONSUMED) dan mengabaikan intent yang dihantar semula semata-mata oleh pelancaran penukar apl bersejarah (Intent.FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY).

Mengendalikan Titik Kemasukan Kitaran Hayat iOS: AppDelegate lwn. Aktiviti Kesinambungan UISceneDelegate

Pada iOS, haluan Pautan Universal terus dan pementasan parameter tertunda mesti selaras dengan kitaran hayat UI aplikasi yang dikonfigurasikan:

• Kitaran Hayat Berasaskan Adegan (UISceneDelegate): Dalam aplikasi yang menerima UIScene (standard dari iOS 13 dan seterusnya), Pautan Universal pelancaran sejuk tiba dalam scene(_:willConnectTo:options:) melalui connectionOptions.userActivities, manakala Pautan Universal sambung semula suam tiba dalam scene(_:continue:).
• Kitaran Hayat Perwakilan Aplikasi (UIApplicationDelegate): Dalam aplikasi yang tidak menggunakan perwakilan adegan, Pautan Universal dihantar kepada application(_:continue:restorationHandler:).
• Pemulihan Pelancaran Pertama Tertunda: Bebas daripada perwakilan kesinambungan Pautan Universal, pertanyaan parameter pemasangan tertunda dilaksanakan sekali semasa permulaan aplikasi awal selepas hierarki paparan akar bersedia.

Pembangun boleh memuat turun pakej SDK platform dan memeriksa templat integrasi kitaran hayat melalui pusat muat turun SDK OpoInstall.

Menyatukan Parameter Pengaktifan Terus dan Parameter Tertunda Pelancaran Pertama ke dalam Penghala Navigasi Tunggal

Untuk mengekalkan keselamatan yang konsisten dan tingkah laku navigasi, seni bina pelanggan menormalkan kedua-dua URI pengaktifan terus dan muatan JSON pemasangan tertunda ke dalam satu model NavigationTarget tunggal sebelum menghantarnya kepada penghala UI:

1. Pengesahan Asal (Intent Terus): Sahkan bahawa URI Intent.ACTION_VIEW yang masuk menggunakan skema https, sepadan dengan hos berkaitan yang disahkan oleh aplikasi (promo.example.com) dan laluan (/open), serta tidak mengandungi kunci pertanyaan duplikasi yang bercanggah.
2. Penyelarasan Skema dan Semakan Senarai Benar: Peta kunci route / id luaran atau medan route_key / target_id dalaman ke dalam model kanun, menolak haluan yang tidak disenaraikan atau ID yang cacat. Perhatikan bahawa logik penguraian Kotlin pelanggan beroperasi sebagai rangka kerja penguraian pertahanan ilustrasi; dalam sistem pengeluaran, huraikan muatan terhadap peraturan skema kanun penuh sebelum penghantaran.
3. Pengawal Masuk Semula Penerbangan Tunggal: Gunakan pengawal per-penghantaran atom supaya panggilan balik serentak tidak boleh mencetuskan transaksi fragmen bertindih.

Menguruskan Get Pengesahan: Beratur Haluan Pautan Mendalam Tertunda Sehingga Log Masuk Pengguna Selesai

Apabila pengguna baharu memasang aplikasi dari kedai aplikasi melalui kod QR dan melancarkannya buat kali pertama, pengguna lazimnya tidak disahkan. Jika kod QR mensasarkan skrin yang dilindungi (seperti room_lobby atau promo_campaign) dan penghala cuba menavigasi serta-merta, get pengesahan akan mengalihkan pengguna ke skrin log masuk dan kehilangan konteks pautan mendalam.

Untuk mengekalkan pemulihan adegan merentas sempadan pengesahan:

• Carian Polisi Haluan Dalaman: Tentukan sama ada haluan memerlukan pengesahan dengan menyemak registri PROTECTED_ROUTES dalaman pelanggan dan bukannya mempercayai bendera muatan luaran.
• Pementasan Atom: Jika pengguna tidak disahkan, simpan NavigationTarget yang disahkan dalam PendingRouteStore berskop sesi atom (AtomicReference) dan halakan pengguna ke aliran log masuk. Perhatikan bahawa PendingRouteStore dalam memori terpakai pada proses aplikasi aktif; jika aliran pengesahan boleh merentasi kematian proses, gunakan stor tempatan yang disulitkan dan terikat masa yang mengosongkan keadaan semasa pertukaran akaun.
• Penilaian Semula Pasca-Pengesahan dan Penghantaran: Apabila log masuk selesai, makan sasaran yang dipentaskan secara atom (getAndSet(null)), sahkan bahawa sesi kini disahkan, nilaikan semula parameter haluan, dan laksanakan peralihan skrin.

Kesediaan Hos Navigasi dan Pemulihan Keadaan

Panggilan balik onNavigationGraphReady() mesti disambungkan kepada permulaan hos navigasi sebenar aplikasi. Apabila graf navigasi ditakrifkan dalam NavHostFragment yang dihoskan XML, aktiviti boleh menetapkan sambungan ini selepas hos dan destinasinya bersedia. Jika graf dipasang secara tak segerak, panggil panggilan balik hanya selepas permulaan graf selesai.

Permintaan navigasi tertunda yang disimpan semata-mata dalam medan Aktiviti mungkin hilang semasa perubahan konfigurasi. Untuk pelaksanaan pengeluaran, kekalkan keadaan haluan yang belum dimakan dalam ViewModel yang sedar kitaran hayat dan gunakan SavedStateHandle apabila pemulihan merentas penciptaan semula Aktiviti didorong sistem atau kematian proses diperlukan. Kod yang ditunjukkan di sini adalah contoh seni bina dan memerlukan navigasi khusus aplikasi dan integrasi sesi.

Kod Kotlin di bawah menyediakan rangka haluan Android ilustrasi dengan SDK milik aplikasi dan penyesuai navigasi yang menunjukkan kawalan ini:

<!-- 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
    }
}

Keselamatan dan Diagnostik: Menghalang Suntikan Haluan dan Keciciran Navigasi

Mempertahankan Diri Terhadap Suntikan Haluan Pautan Mendalam dan Eksploitasi Ubah Hala Terbuka mengikut Garis Panduan OWASP

Parameter yang diekstrak daripada kod QR atau panggilan balik atribusi tertunda mewakili input luaran yang tidak dipercayai. Selaras dengan Piawaian Pengesahan Keselamatan Aplikasi Mudah Alih OWASP dan Risiko dan Garis Panduan Keselamatan 10 Teratas Mudah Alih OWASP, penghala pelanggan mesti menguatkuasakan tiga sempadan pertahanan:

• Melarang Pemuatan URL WebView Arbitrari: Jangan sekali-kali membenarkan parameter haluan (?route=webview&url=https://...) memuatkan URL luaran yang tidak disahkan di dalam WebView aplikasi dalaman. Penyerang boleh mengekod URL phishing ke dalam kod QR, mengeksploitasi bingkai UI asli aplikasi untuk mengumpul kelayakan.
• Menolak Pencemaran Parameter Duplikasi: Jika URL yang dimanipulasi mengandungi berbilang kunci yang bercanggah (?route=home_default&route=room_lobby), tolak URI dan bukannya membenarkan pengawal memilih elemen pertama atau terakhir secara arbitrari.
• Kuatkuasakan Pengesahan Sumber Pelayan: Menghantar target_id=sku_8842 hanya mengarahkan pelanggan pandangan mana yang hendak diminta. Apabila skrin meminta API pelayan, pelayan mesti mengesahkan secara bebas bahawa sesi pengguna semasa diberi kebenaran untuk mengakses entiti tersebut, mencegah kerentanan Rujukan Objek Langsung Tidak Selamat (IDOR).

Mendiagnosis Perlumbaan Navigasi Permulaan Sejuk lwn. Permulaan Suam

Semasa permulaan sejuk, intent pautan mendalam atau panggilan balik SDK tersimpan boleh diselesaikan sebelum graf NavHostFragment utama atau navigasi akar selesai mengembang. Percubaan untuk memanggil navController.navigate() sebelum hierarki paparan bersedia menyebabkan ralat masa jalan atau peralihan yang tercicir. Sentiasa tangguhkan pelaksanaan navigasi sehingga hierarki paparan hos dilampirkan dan aktif (!isFinishing && !isDestroyed).

Mengendalikan Promosi Tamat Tempoh, SKU Dipadamkan, dan Kekurangan Parameter dengan Anggun

Kod QR fizikal selalunya kekal digunakan di kedai runcit atau media cetak selepas promosi digital tamat atau SKU produk telah bersara. Apabila skrin sasaran mengambil data untuk target_id dan menerima respons HTTP 404 Not Found atau 410 Gone daripada pelayan, pelanggan mesti menangkap ralat, memaparkan notis maklumat yang jelas kepada pengguna, dan menavigasi dengan bersih ke home_default.

Senarai Semak Pengesahan Pra-Penggunaan untuk Haluan QR Dwi-Keadaan

Sebelum mengeluarkan kolateral QR fizikal, pasukan kejuruteraan harus melaksanakan protokol pengesahan tujuh mata berikut merentas peranti fizikal:

• Langkah 1: Pengaktifan Permulaan Sejuk Dipasang: Tutup paksa apl yang dipasang dan imbas kod QR. Sahkan OS membuka apl terus ke skrin sasaran (product_detail).
• Langkah 2: Pengaktifan Permulaan Suam Dipasang dan Imbasan Ulang: Dengan apl dibuka pada tab kedua, letakkan apl di latar belakang dan imbas kod QR. Sahkan onNewIntent menghala ke skrin sasaran. Beralih pergi, imbas kod QR yang sama buat kali kedua, dan sahkan ia menavigasi semula dan bukannya disekat oleh penyahduplikasian yang terlalu luas.
• Langkah 3: Pemulihan Tertunda Dinyahpasang (Haluan Awam): Nyahpasang apl, imbas kod QR, lengkapkan pemasangan kedai, dan lancarkan. Sahkan panggilan balik parameter tertunda menormalkan muatan dan menghala ke product_detail.
• Langkah 4: Pemulihan Tertunda Dinyahpasang dengan Get Pengesahan (Haluan Dilindungi): Nyahpasang apl, imbas kod QR yang mensasarkan room_lobby, pasang, dan lancarkan semasa log keluar. Sahkan apl menghala ke Log Masuk dahulu, dan setelah melengkapkan log masuk, memakan PendingRouteStore dan menavigasi ke room_lobby.
• Langkah 5: Asal Tidak Dipercayai dan Penolakan Kunci Duplikasi: Cetuskan intent ACTION_VIEW daripada hos yang tidak dipercayai atau dengan parameter pertanyaan duplikasi (?route=product_detail&route=room_lobby). Sahkan handleIncomingWakeupIntent menolak intent dan mencatat amaran.
• Langkah 6: Idempotensi Putaran Skrin: Selepas tiba pada skrin pautan mendalam, putar peranti untuk mencetuskan penciptaan semula Aktiviti. Sahkan bendera EXTRA_ROUTE_CONSUMED menghalang intent asal daripada dilaksanakan semula.
• Langkah 7: Fallback Anggun Luar Talian / Tidak Sepadan: Lancarkan pemasangan bersih dalam mod kapal terbang. Sahkan tamat masa perolehan selesai tanpa menyekat benang UI dan membawa pengguna ke home_default.

Analisis Perbandingan Mekanisme Haluan Dalam Aplikasi

Menilai Skema URL, Pautan Universal dan Pautan Aplikasi, serta Pemulihan Adegan Tertunda

Platform mudah alih menyediakan mekanisme berbeza untuk menghalakan pengguna ke dalam paparan aplikasi merentas keadaan pemasangan yang berbeza:

Pertukaran Perdagangan Seni Bina Merentas Keadaan Pemasangan dan Sistem Pengendalian

Skema URL tersuai (myapp://product/123) kekurangan pengesahan pemilikan domain kriptografi, bermakna mana-mana aplikasi boleh mendaftarkan skema yang sama dan memintas pautan. Tambahan pula, mengimbas kod QR skema tersuai mentah apabila apl tidak dipasang mengakibatkan ralat pelayar yang tidak boleh dipulihkan.

Pautan Universal dan Pautan Aplikasi Android mengesahkan pemilikan domain melalui HTTPS dan beralih kepada halaman landas web apabila apl tiada, menjadikannya asas yang diperlukan untuk haluan QR. Menggabungkan Pautan Universal dan Pautan Aplikasi untuk pengaktifan terpasang dengan pemulihan tertunda disokong platform (seperti Rujukan Pemasangan Google Play pada Android dan penyesuai SDK yang disemak privasi) membolehkan pemulihan adegan dwi-keadaan daripada satu aset QR.

Ringkasan dan Rangka Kerja Keputusan

Untuk membuat kod QR bagi haluan aplikasi dengan parameter tersuai, pasukan kejuruteraan mesti merapatkan rentetan pertanyaan URL luaran yang padat dengan pengawal navigasi asli yang sedar keadaan. Pelaksanaan yang lengkap mengendalikan kedua-dua pengaktifan sistem pengendalian terus untuk pengguna sedia ada dan pemulihan parameter tertunda bersyarat untuk pemasangan kedai aplikasi baharu.

Oleh kerana kesinambungan parameter merentas kedai aplikasi bergantung pada mekanisme khusus platform—seperti Rujukan Pemasangan Google Play pada Android dan aliran kerja yang disahkan serta mematuhi privasi pada iOS—aplikasi mesti melayan muatan haluan yang dipulihkan sebagai calon yang tidak dipercayai. Dengan menggabungkan penghantar haluan yang disenaraikan, pengantrean keadaan pengesahan, dan fallback skrin utama yang anggun, pasukan boleh menyampaikan pemulihan adegan yang boleh diharap tanpa menjejaskan kestabilan aplikasi atau peraturan privasi platform.

SDK dan dokumentasi pembangun OpoInstall menyediakan komponen untuk melaksanakan haluan web-ke-apl dan penghantaran parameter. Sahkan tandatangan API khusus, skema panggilan balik, dan tingkah laku platform yang disokong oleh keluaran SDK anda yang digunapakai sebelum pelancaran pengeluaran.

Untuk butiran integrasi, rujuk dokumentasi pembangun OpoInstall, akses pusat muat turun SDK OpoInstall, atau konfigurasikan domain haluan aplikasi anda dalam konsol pembangun OpoInstall.

Bahan Berkaitan

• Konsep: Pemulihan Adegan, Pautan Mendalam Dwi-Keadaan, Penyenaraian Benar Haluan, Pemulihan Parameter Tertunda

• Teknologi: Pautan Universal, Pautan Aplikasi Android, Rujukan Pemasangan Google Play, Pengawal Navigasi Asli

• Piawaian: Sintaks Generik Pengecam Sumber Seragam (URI) IETF RFC 3986, Piawaian Pengesahan Keselamatan Aplikasi Mudah Alih OWASP, Risiko dan Garis Panduan Keselamatan 10 Teratas Mudah Alih OWASP

• Antara Muka Integrasi: Penyah haluan pautan mendalam milik aplikasi, panggilan balik bangun dan parameter pasang yang didokumenkan untuk versi SDK yang digunakan, serta pengawal navigasi asli platform.

• Dokumentasi Rasmi & Rujukan:

  • Dokumentasi Pembangun Apple mengenai Menyokong Pautan Universal dalam Apl Anda

  • Panduan Privasi Pengguna dan Penggunaan Data Apple

  • Panduan Pembangun Android Google mengenai Pautan Mendalam dan Pautan Aplikasi

  • Dokumentasi API Rujukan Pemasangan Google Play