聊聊支付宝小程序的 LaunchOptions 接口

江海入海，知识涌动，这是我参与江海计划的第14篇。
（2025年1月第14篇）

本系列前两篇文章：

聊聊支付宝小程序的 ReferrerInfo 接口
支付宝小程序开发详解：关于支付宝小程序的类型定义文件
本文继续学习支付宝小程序的 LaunchOptions 接口。

该接口定义在如下文件内：lib.app.d.ts

文件路径：C:\Users\I042416\.minidev\typings\public\alipay-local\package\node_modules\@mini-types\global\types

源代码：

interface LaunchOptions<
    Query extends Record<string, string> = Record<string, string>
  > {
    /**
     * 当前小程序的 query，从启动参数的 query 字段解析而来
     */
    query: Query;
    /**
     * 启动小程序的 场景值
     * @see https://opendocs.alipay.com/mini/framework/scene
     */
    scene: number;
    /**
     * 当前小程序的页面地址，从启动参数 page 字段解析而来，page 忽略时默认为首页
     */
    path: string;
    /**
     * 来源信息
     */
    referrerInfo: ReferrerInfo;
  }

这段代码定义了一个 TypeScript 接口 LaunchOptions，用来描述支付宝小程序在启动时可用的参数信息。这些字段可以帮助开发者了解用户如何进入小程序，以及当前的上下文信息。

1. `query`

query 是一个泛型字段，其类型是 Record<string, string>，默认值也是 Record<string, string>。

query 表示小程序启动时传入的查询参数，通常以 URL 查询字符串的形式体现。例如，在访问 myapp?userId=123&source=referral 时，query 的值为：

    {
      "userId": "123",
      "source": "referral"
    }

当需要根据用户的行为或外部来源定制化展示内容时，query 提供了所需的上下文。例如一家电商平台的小程序提供了商品详情页分享功能，生成的分享链接可能形如： myapp://pages/product?productId=456&ref=share。通过解析 query，小程序可以直接打开对应的商品详情页，并显示特定的营销文案。用户点击分享链接后，小程序解析到 query 的值：

    {
      "productId": "456",
      "ref": "share"
    }

这样，开发者便可以通过 productId 加载商品详情数据，并利用 ref 分析分享效果。

2. `scene`

scene 是一个数字字段，代表小程序启动时的场景值。

场景值是支付宝定义的标识，表示用户是通过何种方式进入小程序。场景值的具体含义可以参考支付宝文档。

当需要根据进入来源调整逻辑时，scene 提供了上下文支持。例如某在线教育平台的小程序可以通过扫码、收藏夹、推送消息等多种方式进入。扫码进入时的 scene 值为 1014，推送消息进入时的值为 1037。根据 scene 值，该平台实现了以下逻辑：

扫码进入：直接跳转到扫码课程对应的页面。
推送消息进入：加载消息对应的课程并高亮显示。

3. `path`

path 是一个字符串字段，表示当前小程序的页面地址。该字段通常从启动参数 page 字段解析而来。如果 page 忽略，则默认值为小程序首页。

在多页面应用中，需要确保用户进入的页面与其预期一致。例如一个理财工具小程序支持多个功能模块（如记账、预算、投资分析等）。推广活动可能会引导用户直接进入特定功能页面：

活动链接：myapp://pages/budget。
小程序启动时，path 的值为 pages/budget，开发者可以利用该字段确保直接加载预算模块。

4. `referrerInfo`

referrerInfo 描述小程序的来源信息，包括来源小程序的 appId 和传递的额外数据。下面是一个例子。

    {
      "appId": "123456",
      "extraData": {
        "from": "partnerApp",
        "campaignId": "789"
      }
    }

当小程序是通过其他小程序跳转而来时，referrerInfo 可以帮助开发者确定来源并执行相应的业务逻辑。比如一个餐饮平台小程序与多个本地生活服务平台（如点评类小程序）合作。用户点击点评小程序中的跳转链接进入餐饮平台时，开发者可以通过 referrerInfo 中的 appId 和 extraData 获取合作平台的标识和活动 ID，进而触发优惠券发放逻辑。

综合应用场景

在用户通过扫码、分享链接等方式进入小程序时，可以通过 query 和 scene 提供高度个性化的体验。例如：

实现基于用户行为的推荐内容：根据 query 中的参数加载用户感兴趣的内容。
根据场景值优化用户路径：扫码进入时直接跳转目标页，而无需中间页面。

结合 scene 和 referrerInfo，开发者可以分析用户进入路径并评估营销活动效果：

收集不同入口的用户行为数据：扫码、分享链接、广告等。
根据 referrerInfo 统计合作渠道的引流效果。

支付宝小程序生态允许小程序之间跳转，通过 referrerInfo，目标小程序可以获取来源小程序传递的数据，实现深度联动：

购物平台跳转支付类小程序时，传递订单信息；
旅游平台与地图服务小程序联动时，传递目的地信息。

聊聊支付宝小程序的 LaunchOptions 接口