Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

Overview

Mini program QR codes let users open a specific page in your mini program by scanning a QR code with a target app. You can use QR codes to connect offline or external touchpoints, such as product packaging, campaign posters, and websites, to pages in your mini program.

QR code types

You can use two types of QR codes for mini programs:

  • Promotion QR code: A platform-generated QR code that opens a specific page in your mini program.
  • Customized QR code: A standard QR code that contains an external URL and is bound to a specific mini program page.

The following table summarizes the key differences of the QR code types:

Promotion QR code

Customized QR code

Encoded content

A proprietary mini program page path.

A standard web URL (HTTPS, HTTP, or FTP).

Source

You generate a new code on Mini Program Platform.

You generate a code on an external system.

Behavior when scanned by a target app

Opens the specified mini program page.

Opens the mini program page bound to the URL.

Behavior when scanned by a generic scanner (e.g., system camera)

No action (unrecognizable code).

Opens the original encoded URL.

Best use case

Creating a new QR code for a mini program page.

Adding a mini program experience to a standard QR code, without breaking the original web URL.

Choose a QR code type

Use the following guidance to decide which QR code type to use:

  • Use a promotion QR code for one of the following scenarios:
    • You want to create a new QR code for a specific mini program page.
    • The QR code only needs to work when scanned with target apps.
  • Use a customized QR code for one of the following scenarios:
    • You want to reuse existing standard QR codes that are printed on packaging, posters, labels, or other offline materials.
    • You want users to open a mini program page when scanning with a target app, but open a standard web URL when scanning with other apps.

Basic concepts

Before you create or bind QR codes, understand the following concepts.

Mini program page directory

A mini program page directory is the internal path to a page in your mini program.

The page directory must exactly match a valid page configured in your mini program. If the path is incorrect, target apps cannot navigate users to the intended page.

URL matching method (customized QR codes only)

When you bind an external URL to a mini program page, you need to choose how a target app matches scanned URLs against your binding. You can use one of the following matching methods:

Matching method

Description

Example use case

Fuzzy matching

Matches URLs that share the same prefix.

Route multiple product URLs, such as https://example.com/product/123 and https://example.com/product/456, to the same mini program page.

Exact matching

Matches only the specified URL.

Route one specific campaign URL to one specific mini program page.

Promotion QR codes

A promotion QR code directly encodes a mini program page path. It is generated by Mini Program Platform and is designed to be scanned with target apps.

Default code

After your mini program is fully released to a target app, the platform automatically generates a default promotion QR code that opens your mini program's homepage. You can view this code on the mini program details page, under QR code > Promotion QR code.

Scanning behavior

Promotion QR codes behave differently based on the used scanner:

  • Scanned with a target app scanner: Opens the specified mini program page.
  • Scanned with a generic scanner (e.g., system camera or browser): Does not open the mini program. An unrecognizable code error might show.

How a promotion QR code works

The following process shows how a promotion QR code works:

  1. You specify the target page directory in your mini program.
  2. The platform generates a QR code for that page.
  3. You download and distribute the QR code.
  4. A user scans the QR code with a target app.
  5. The target app opens your mini program and navigates to the specified page.

Customized QR codes

A customized QR code is a standard QR code that contains an external URL. You can bind that URL to a page in your mini program.

Encoded URL requirements

The external URL encoded in the QR code must meet the following requirements:

  • ICP verification: The URL domain must have a valid Internet Content Provider (ICP) filing.
  • Protocol: The URL must use one of the following protocols:
    • HTTPS
    • HTTP
    • FTP

Scanning behavior

Customized QR codes behave differently based on the used scanner:

  • Scanned with a target app scanner: Opens the bound mini program page.
  • Scanned with a generic scanner (e.g., system camera or browser): Opens the original encoded URL.

How a customized QR code works

The following process shows how a customized QR code works:

  1. You identify a standard QR code that contains an external URL.
  2. You create a binding between the URL and a mini program page directory.
  3. A user scans the QR code with a target app.
  4. The target app decodes the URL and checks whether it matches a binding.
  5. If the URL matches a binding, the target app opens the bound mini program page.

Capacity limits

The maximum number of QR codes may vary by QR code type and platform configuration. You can view the limit when you manage QR codes in Mini Program Platform.

Related information

To manage your mini program QR codes, refer to the following topics: