Mini Programs Deep Linking

Mini Programs Deep Linking

1. Background 

Term

Definition

Deep Link

Any link that directs a user past the home page of a mini program to content inside of it. e.g. linking directly to a product.

The mini program framework supports the creation of deep links and the access of any data embedded in the deep link. The data is embedded using query parameters which can be formatted and accessed in different ways discussed in the following sections. 

2. Creation of Deep Links

2.1 Mini Program Studio

The mini program studio allows you to simulate receiving query parameters from a deep link. You can create different custom compilation options which launch the mini program with your specified start params. These are created using the standard web query parameter format of key value pairs. For example, if I want to launch your mini program with the following parameters:

Key 

Value

dailyDeal

10

sku

123456

campaign

summer21

the start params would be:

dailyDeal='10'&sku='123456'&campaign='summer21'

Accessing compilation options from IDE: 

image

2.2 Internal QR Code

You can embed query parameters into a QR code that can be opened from within the Vodapay super app and launch your mini program with those query parameters. 

Steps:

  1. create query parameters in standard web format
  2. encode query parameters, example shown below: encodedParams
  3. obtain appid from the workspace app description: appId
  4. create url in following format:
    mini://platformapi/startapp?_ariver_appid=appId&query=encodedParams
  5. generate qr code from above URL 

Example: 

  1. query parameters: dailyDeal=10&sku=123456&campaign=summer21
  2. you can use any online provider for encoding, eg:  https://www.urlencoder.org/, result: dailyDeal%3D10%26sku%3D123456%26campaign%3Dsummer21
  3. obtaining appId from workspace image
  4. url: mini://platformapi/startapp?_ariver_appid=3460020090520374&query=dailyDeal%3D10%26sku%3D123456%26campaign%3Dsummer21
  5. you can use any online provider to generate qr code, eg: https://www.the-qrcode-generator.com/

image

2.3 External Link

You can embed query parameters into an external link, that when selected, will open the Vodapay app and then open your mini program with the query parameters. These links can be shared on social media, messaging apps, emails or any place where they can be opened from any Vodapay supported device. If the user has they Vodapay app installed on their device they will be directed to the app otherwise they will be redirected to the native app store. 

Steps

  1. create query parameters in standard web format
  2. encode query parameters: encodedParams
  3. obtain appid from the workspace app description: appId
  4. create url payload: action=miniapp&miniappId=appId&query=encodedParams : payload
  5. create intermediary link: vodapaywallet://deeplink.htm?payload (Note: if you are participating in the Vodapay daily deals, this is the version of the deep link required by Vodacom marketing team) 
  6. encode intermediary link: encodedIntemediaryLink 
  7. create final link
    1. Prod Link: https://app.adjust.com/jau3fuy?deep_link=encodedIntemediaryLink 
    2. Sandbox Link: https://app.adjust.com/30q9i84?deep_link=encodedIntemediaryLink 

Example

  1. query parameters: dailyDeal=10&sku=123456&campaign=summer21
  2. encoded query parameters: dailyDeal%3D10%26sku%3D123456%26campaign%3Dsummer21
  3. appId from workspace: 3460020090520374
  4. payload: action=miniapp&miniappId=3460020090520374&query=dailyDeal%3D10%26sku%3D123456%26campaign%3Dsummer21
  5. intermediary link:  vodapaywallet://deeplink.htm?action=miniapp&miniappId=3460020090520374&query=dailyDeal%3D10%26sku%3D123456%26campaign%3Dsummer21
  6. encoded intermediary link: vodapaywallet%3A%2F%2Fdeeplink.htm%3Faction%3Dminiapp%26miniappId%3D3460020090520374%26query%3DdailyDeal%253D10%2526sku%253D123456%2526campaign%253Dsummer21
  7. resultant link: 
    1. Prod:  https://app.adjust.com/jau3fuy?deep_link=vodapaywallet%3A%2F%2Fdeeplink.htm%3Faction%3Dminiapp%26miniappId%3D3460020090520374%26query%3DdailyDeal%253D10%2526sku%253D123456%2526campaign%253Dsummer21
    2. Sandbox: https://app.adjust.com/30q9i84?deep_link=vodapaywallet%3A%2F%2Fdeeplink.htm%3Faction%3Dminiapp%26miniappId%3D3460020090520374%26query%3DdailyDeal%253D10%2526sku%253D123456%2526campaign%253Dsummer21

HTML Links 

You can use the above format for website links. The url will be used as the value for the src attribute of the <a> tag. Please note that for this to work as expected, you need to ensure that the 'target' attribute has the value '_blank' 

Example:

<div class="d-flex h-100">

  <a href="https://app.adjust.com/jau3fuy?deep_link=vodapaywallet%3A%2F%2Fdeeplink.htm%3Faction%3Dminiapp%26miniappId%3D3460020090520374%26query%3DdailyDeal%253D10%2526sku%253D123456%2526campaign%253Dsummer21" target="_blank"

   class="btn btn-primary m-auto"> Open mini program </a>

</div>

3. Processing Deep Links Within Mini Program

Mini programs have configuration for the entire app, found in the app.js file and also configuration for each individual page. The different lifecycle hooks for the entire app are thus found in the app.js file. When the app is launched from a deeplink, the query parameters can be accessed in the onLaunch() lifecyle hook of the app. The lifecycle hook has a parameter options which has a query object containing all the query parameters from the link. To pass the data from the query parameters to other pages within your miniprogram, you can make it global, then use the global function getApp to access the data from any other page within your mini program.

// app.js 

App({

  onLaunch(options) {

  this.queryParams = options.query;

    

    // for native DSL apps, you can process the query parameters 

    // on this page and navigate to the required page

  },

});

// index.js 

Page({

  onLoad() {

    const app = getApp();

    const dailyDeal = app.query.dailyDeal;

    const sku = app.query.sku;

    const campaign = app.query.campaign;

    // code to redirect to correct page based on query parameters can go below 

  },

});

Once you have the query parameter data within your homepage (index.js) for your mini program, you can then facilitate navigation to required page 

  • DSL mini programs use my.navigateTo()
  • Web app mini programs can use my.postMessage() to pass data to web-app which will then route to required page 

Please note that you can only test deep linking to mini programs that have been released from the workspace to Vodapay. 

3.1 Recommended Approach 

The best approach for processing deep links is to create a generic function that can process different parameters and link to any product or page within your app. 

For example, if you are creating an ecommerce app using the DSL, and your product display page path for all products is as follows:

../category/sku

You can create a function that whenever your app is passed the category and sku as query parameters, it can redirect to that specific product page. 

// index.js 

Page({

  onLoad() {

    const app = getApp();

    if(app.query.category && app.query.sku) {

        my.navigateTo({

          url: "../"+ app.query.category + "/" + app.query.sku

        });

      },

   }

});

This is especially essential for mini app merchants that will be making use of the Vodapay daily deals feature. The goal is to create a generic system so that anytime the merchant wants to participate in the daily deals, their marketing team can create a deep link to any product without requiring any additional development work.