uni-app WeChat Mini Program Integration Guide

uni-app WeChat Mini Program Integration Guide

This document is intended for developers who have already developed a WeChat Mini Program using uni-app and wish to integrate the Polyv live streaming viewing page into their Mini Program pages.

With this solution, after the uni-app project is compiled into a WeChat Mini Program, the Polyv viewing component can be mounted as a native WeChat Mini Program custom component within the page, enabling capabilities such as live streaming viewing, playback viewing, chat room, viewing conditions, and interactive reception.

Solution Overview

The uni-app WeChat Mini Program viewing component is part of the WeChat Mini Program integration solution. The component ultimately runs within the mp-weixin output.

If the project only requires a low-cost way to open a complete viewing page, consider the WeChat Mini Program WebView H5 viewing page solution first. If only player capabilities are needed, evaluate the Polyv WeChat Mini Program live streaming player plugin, live streaming player custom component, or live streaming player core SDK.

Prerequisites

1. Polyv Account and Channel

Prepare the following before integration:

• A Polyv live streaming account that can log in normally.
• A live streaming channel that has been created.
• The channel ID for testing.

The viewing conditions, playback, chat room, interactive features, etc., of the channel are still subject to the channel configuration in the Polyv live streaming backend.

2. WeChat Mini Program Entity and Qualifications

Capabilities such as live streaming playback, co-hosting, and plugin usage are related to the WeChat Mini Program's entity, service category, interface permissions, and plugin permissions. Relevant reviews and activations must be completed under the customer's own WeChat Mini Program AppID.

It is recommended to confirm the following before integration:

• The Mini Program entity has completed WeChat verification and is not a personal entity Mini Program.
• The Mini Program's service category meets the actual business scenario and WeChat review requirements.
• The Mini Program plugin required by the Polyv viewing component has been added in the WeChat public platform backend.
• If using co-hosting capabilities, confirm that live-pusher, camera, microphone, and other related capabilities are available.
• Necessary business domain names have been configured in both the WeChat public platform and the Polyv live streaming backend.
• If the functionality involves user information, camera, microphone, etc., the user privacy protection guidelines have been configured as required by WeChat.

Qualification and category requirements may change with WeChat platform rules; the final result is subject to the review by the WeChat public platform.

3. Obtain the Component Package

The integrator can obtain the polyv-live-watch component package in the following two ways.

When building from the open-source viewing page project, follow these steps:

git clone https://gitee.com/polyv_ef/polyv-mp-live-watch-ui.git
cd polyv-mp-live-watch-ui
npm install
npm run build:uniapp-wxcomponents

After the build is complete, the component package is generated at:

dist-uniapp-wxcomponents/polyv-live-watch

Copy this directory completely to the uni-app project:

src/wxcomponents/polyv-live-watch

The subsequent examples in this document assume the following directory structure after copying:

src
  wxcomponents
    polyv-live-watch
      components
        watch-room
          watch-room.json
          watch-room.js
          watch-room.wxml
          watch-room.wxss
      polyv-live-watch.package.json

polyv-live-watch is the native WeChat Mini Program custom component package. The entire directory must be copied completely; do not copy only the watch-room single component.

Quick Integration

1. Copy the Component Package

Copy the polyv-live-watch directory to the src/wxcomponents directory of the uni-app project:

src/wxcomponents/polyv-live-watch

After copying, at least the following entry files should exist:

src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.json
src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.js
src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.wxml
src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.wxss

2. Configure manifest.json

Enable custom component support in the mp-weixin node of manifest.json, and declare the Mini Program plugin required by the Polyv viewing component:

{
  "mp-weixin": {
    "usingComponents": true,
    "plugins": {
      "polyv-live-plugin": {
        "version": "1.3.1",
        "provider": "wxfb2e591959a8bacf"
      },
      "polyv-player": {
        "version": "1.17.0",
        "provider": "wx4a350a258a6f7876"
      }
    }
  }
}

If the project already has mp-weixin configuration, only merge the usingComponents and plugins sections. Do not overwrite the project's existing appid, setting, permission, etc., configurations.

3. Configure pages.json

Register the polyv-watch-room component in the uni-app page where the viewing page needs to be displayed:

{
  "path": "pages/polyv-watch/index",
  "style": {
    "navigationBarTitleText": "直播观看",
    "usingComponents": {
      "polyv-watch-room": "/wxcomponents/polyv-live-watch/components/watch-room/watch-room"
    }
  }
}

The path is relative to the root directory of the compiled WeChat Mini Program from uni-app, typically using the /wxcomponents/... format.

4. Mount the Component in the Page

The following example uses Vue 3 syntax. Vue 2 projects can be adapted using the same parameters and event names.

<script setup lang="ts">
import { onLoad, onUnload, onShareAppMessage } from '@dcloudio/uni-app'
import { reactive } from 'vue'

const configs = reactive({
  channelId: '',
  forceLayout: 'portrait',
})

onLoad((query) => {
  configs.channelId = typeof query?.channelId === 'string' ? query.channelId : ''
})

onUnload(() => {
  const pages = getCurrentPages()
  const currentPage = pages[pages.length - 1]
  const room = currentPage?.selectComponent?.('#polyvWatchRoom')
  room?.destroy?.()
})

onShareAppMessage(() => ({}))

function handleReady(event) {
  console.log('polyv watch ready', event.detail)
}

function handleViewChange(event) {
  console.log('polyv watch view change', event.detail)
}

function handleWebview(event) {
  const url = event.detail?.url

  if (!url) {
    return
  }

  uni.navigateTo({
    url: `/pages/webview/index?url=${encodeURIComponent(url)}`,
  })
}

function handleLoginRequired(event) {
  console.log('polyv watch login required', event.detail)
}
</script>

<template>
  <view class="polyv-watch-page">
    <polyv-watch-room
      id="polyvWatchRoom"
      class="polyv-watch-room-host"
      :configs="configs"
      @ready="handleReady"
      @view-change="handleViewChange"
      @webview="handleWebview"
      @login-required="handleLoginRequired"
    />
  </view>
</template>

<style>
page {
  height: 100%;
}

.polyv-watch-page {
  height: 100vh;
  min-height: 100vh;
  overflow: hidden;
}

.polyv-watch-room-host {
  display: block;
  width: 100%;
  height: 100%;
  min-height: 100vh;
}
</style>

The page only needs to mount the polyv-watch-room once. The process of entering the guide page, viewing page, or error page is handled internally by the component; the host page does not need to remount the component based on events.

Parameter Description

polyv-watch-room receives initialization configuration via configs.

If the delivery package adds new configuration items in the future, refer to the component package documentation for the corresponding version.

Event Description

In uni-app Vue templates, it is recommended to use kebab-case for binding events. For example, the internal component event viewChange should be written as @view-change in the template; loginRequired should be written as @login-required.

Viewing Flow and Host Boundaries

In this solution, the main body of the viewing page is handled internally by the component:

polyv-watch-room
  loading
  splash
  watch
  error

The component internally decides whether to display a guide page, authorization page, viewing page, or error page based on the channel configuration and viewing conditions. The host uni-app page is only responsible for providing the container, passing the configuration, and handling events that cross the component boundary.

Behaviors handled internally by the component include:

• Entering the guide or authorization view.
• Entering the viewing view.
• Displaying the error view.
• Internal state transitions of the player, chat room, interactive components, etc., within the viewing page.

Behaviors that the host page needs to handle include:

• Opening its own WebView page.
• Navigating to its own login page.
• Configuring Mini Program sharing according to its own rules.
• Handling page-level routing and tracking according to its own rules.

Do not create or mount a new viewing component again after receiving viewChange, as this may lead to duplicate component initialization, duplicate chat room connections, or abnormal playback states.

Style and Resource Description

The polyv-live-watch component package includes the necessary business WXSS and static resources for the viewing page. The integrator usually does not need to import additional global styles from the original Polyv project.

The host page is only recommended to provide the container height:

• Set height: 100% for page.
• Set height: 100vh for the page root node.
• Set display: block, width: 100%, height: 100% for the polyv-watch-room host node.

It is not recommended to override internal class names within the polyv-live-watch component package in the global styles of the uni-app project, such as business class names for the player, chat room, interactive cards, icons, buttons, etc. Global overrides may cause issues like incorrect icon sizes, text truncation failure, layer misalignment, and abnormal button states.

If obvious style issues occur after integration, troubleshoot in the following order:

1. Confirm that the complete polyv-live-watch directory has been copied.
2. Confirm that the old version of the component package has been completely overwritten, with no mixing of old and new files.
3. Confirm that directories like common, assets, package-watch, package-splash under src/wxcomponents/polyv-live-watch exist completely.
4. Confirm that the host page has not overridden internal business class names of the component package.
5. Use the WeChat Developer Tools to check if the components, WXSS, and image resources exist in the final mp-weixin output.

Build and Preview

After completing the integration, execute the uni-app WeChat Mini Program build command. For example:

pnpm build:mp-weixin

The actual command depends on the package manager and project scripts used; it could also be npm run build:mp-weixin or the built-in build in HBuilderX.

After the build is complete, open the dist/build/mp-weixin directory using the WeChat Developer Tools, and use the customer's own AppID for preview and real device debugging.

It is recommended to at least verify the following:

• The viewing page can be opened using the channel ID.
• Viewing conditions such as no condition, captcha, registration, and whitelist display correctly according to the channel configuration.
• Live streaming or playback can play normally.
• The chat room can connect, receive, and send messages normally.
• Interactive features like likes, check-ins, card pushes, conditional lotteries, and product libraries display correctly according to the channel configuration.
• WebView links can be passed to the host page via the webview event.
• If using co-hosting capabilities, the user can normally request co-hosting on a real device and obtain camera and microphone authorization.
• Flows like Mini Program sharing, page return, page destruction and re-entry work normally.

Frequently Asked Questions

1. Is this a complete uni-app multi-platform SDK?

No. This solution is only for the mp-weixin platform after uni-app is compiled into a WeChat Mini Program. Platforms like App, H5, Alipay Mini Program, and Douyin Mini Program are not covered by this solution.

2. Is it mandatory for the customer's Mini Program to complete the qualification and plugin configuration?

Yes. WeChat service categories, plugin additions, interface permissions, privacy agreements, and review results are all bound to the customer's own Mini Program AppID and cannot be replaced by the Polyv test AppID.

3. Does the host page need to navigate after the viewChange event is triggered?

No. viewChange only notifies the host of the current internal view change. The viewing flow is handled internally by polyv-watch-room; the host page does not need to re-route or remount the viewing component based on viewChange.

4. Why does the host need to handle clicks on products, ads, or external links?

These actions have left the boundary of the viewing component, and the target page usually belongs to the customer's own business page. The component passes the link or business information to the host page via an event, and the host page then handles it using uni.navigateTo, uni.redirectTo, or its own routing solution.

5. What if it works in the WeChat Developer Tools but not on a real device?

First, check the following configurations:

• Whether the preview is using the customer's own AppID.
• Whether the required plugins have been added in the WeChat public platform backend.
• Whether the Mini Program's service category and interface permissions meet the current functional requirements.
• Whether business domain names for request, socket, upload, download, web-view, etc., have been configured.
• Whether the access domain name or related developer information for the current Mini Program has been configured in the Polyv live streaming backend.
• Whether permissions for the camera, microphone, etc., have been granted on the real device.

Related Documentation

• Mini Program Solution Selection Guide
• WeChat Mini Program Viewing Page SDK (New Version) Product Introduction
• WeChat Mini Program Viewing Page SDK (New Version) Quick Start
• Polyv Cloud Live Mini Program Player Plugin
• WeChat Mini Program SDK Category Application Qualification Requirements
• uni-app Mini Program Custom Component Support
• uni-app WeChat Mini Program Plugin Usage Guide