tcmpp_flutter 1.5.19+1

The Tencent Cloud Mini Program Platform (TCMPP) amalgamates Tencent's technical prowess in mini program development, testing, release, operation, and mini program containerization, offering corporate [...]

TCMPP Flutter Plugin

TCMPP Flutter Plugin is a Flutter plugin to provide access for TCMPP SDK in Flutter. For details of TCMPP, see: https://www.tencentcloud.com/products/tcmpp.

Add TCMPP Flutter Plugin

Add TCMPP core plugin from Pub.dev

1. Add dependecy

   To add plugin from pub.dev, open the pubspec.yaml file located inside the app folder, and add tcmpp_flutter: ${version} under dependencies.

2. Install dependecy

• From the terminal: Run flutter pub get.
• From VS Code: Click Get Packages located in right side of the action ribbon at the top of pubspec.yaml indicated by the Download icon.
• From Android Studio/IntelliJ: Click Pub get in the action ribbon at the top of pubspec.yaml.

For details how to add Flutter plugins or packages, see Use packages & plugins

Add TCMPP extra plugins

Some TCMPP mini-program APIs may require additional privacy and permissions. To use these APIs, additional Flutter plugin dependencies are needed.

APIs	Plugin name	Permissions needed
LBS related APIs (Location & POI search)	tcmpp_flutter_lbs	Access location
MDNS APIs	tcmpp_flutter_mdns	Access locale network
TCP/UDP APIs	tcmpp_flutter_network	Access internet
Meida APIs (Photos & Videos)	tcmpp_flutter_media	Access photo library
Wifi APIs, Bluetooth APIs, Calandar APIs, Contact APIs, Clipboard APIs, Biometric authenication APIs	tcmpp_flutter_device	Access wifi state, Access bluetooth, Access calandar, Access contact, Access clipboard, Access fingerprint & face id

These plugins must be used together with tcmpp_flutter plugin.

Add assets for TCMPP configuration files

Get TCMPP configuration file from your TCMPP web console

1. Get appcation ID / bundle ID of your Android / IOS application.

• For Android, in your Flutter project, open android > app > build.gradle, application id can be found in android > defaultConfig section.

• For IOS, in your Flutter project, open ios > Runner.xcodeproj > project.pbxproj, search for PRODUCT_BUNDLE_IDENTIFIER.

2. Create Flutter Application on TCMPP web console.

   1. Login the Tencent Cloud Mini Program Platform Console and click 'Overview' in the left-hand navigation bar.
   2. On the Overview page, click Access Application.
   3. In the pop-up window for creating an application, fill in informations for your application.
   4. For Intergration platform section, check both IOS platfrom & Android Platform. Then fill application ID / bundle ID you got in the package name field.

   

   5. Click next, download Android / IOS configuration file in the new page.

   

Add configuration file

1. Copy TCMPP configuration file to your Flutter project directory.

   Please do not rename files downloaded from web console. Otherwise will not be loaded by TCMPP plugin.

   

2. Edit pubspec.yaml file and add assets for TCMPP configuration files.

   

Platform specific

For Android platform

1. Open android > app directory, edit build.gradle file.

2. In android > defaultConfig section, change minSdkVersion to no less than 21.

minSdkVersion 21

3. In android > defaultConfig section, add ndk filter for armeabi, armeabi-v7a, arm64-v8a.

ndk { abiFilters "armeabi", "armeabi-v7a", "arm64-v8a" }

4. In android > defaultConfig section, add packagingOptions.

packagingOptions {
   pickFirst 'lib/arm64-v8a/libc++_shared.so'
   pickFirst 'lib/armeabi/libc++_shared.so'
   pickFirst 'lib/armeabi-v7a/libc++_shared.so'
   pickFirst 'lib/arm64-v8a/libmarsxlog.so'
   pickFirst 'lib/armeabi/libmarsxlog.so'
   pickFirst 'lib/armeabi-v7a/libmarsxlog.so'
   pickFirst 'lib/arm64-v8a/libv8jni.so'
}

For IOS platform

Add source

In the Podfile file in the ios directory, add source:

source 'https://e.coding.net/tmf-work/tmf/tmf-repo.git'

Execute pod install

cd to ios directory,execute pod install:

pod install

TCMPP Flutter APIs

Usage

1. To use TCMPP APIs, import 'package:tcmpp_flutter/tcmpp_flutter.dart'.

   

2. Then create a TcmppFlutter object and use it to call TCMPP APIs.

   

Implement Open APIs

Some mini-program APIs need to interact with host app or third-party library, such as get account information or request a payment action. For these APIs to work properly, developer should implement and register a OpenApiHandler before mini-program is launched. For details about these APIs, see OpenApiHandler in Classes section.

example code:

class MyAppletHandler extends OpenApiHandler {
  @override
  Future<Map<String, dynamic>> getUserProfile(
      AppInfo appInfo, Map<Object?, Object?> params) async {
    print("getUserProfile:$appInfo params:$params");
    Map<String, dynamic> result = {
      "userInfo": {
        "nickName": "xcode",
        "avatarUrl":
            "https://staticintl.cloudcachetci.com/cms/backend-cms/8WGP653_%E5%BC%80%E5%8F%91%E8%80%85%E5%B7%A5%E5%85%B7%E9%80%9A%E7%94%A8.png",
        "gender": 1,
        "country": "China",
        "province": "ChongQing",
        "city": "ChongQing",
      }
    };
    return result;
  }

  @override
  Future<Map<String, dynamic>> login(
     AppInfo appInfo, Map<Object?, Object?> params) async {
    /// return current login certification or do login if not logged in
    ...
  }

  @override
  Future<Map<String, dynamic>> checkSession(
     AppInfo appInfo, Map<Object?, Object?> params) async {
     /// throw any error if this api call is failed
     throw NotLoggedInError();
  }

  /// other api implementation
  ...
}

The parameter of these API calls are provided by corresponding mini-program API, converted from JSON object into Dart Map object. Also return value of your implementation will be converted into JSON object and delivered to corresponding mini-program API. You can check out these APIs in TCMPP's mini-program API document.

To register your OpenApiHandler instance, use registerOpenApiHandler in TcmppFlutter object.

final _tcmppFlutterPlugin = TcmppFlutter();

...

@override
void initState() {
   super.initState();
   
   ...

   /// Must registered before mini-program is launched
   _tcmppFlutterPlugin.registerOpenApiHandler(MyAppletHandler());
}

APIs

Future<void> startMiniAppWithId(String appId, MiniStartOptions? options)

Start a mini program with given appId

• appId: The app id of mini program
• options: Start options of this mini program
  
  

Future<void> startMiniAppWithLink(String link, MiniStartOptions? options)

Start a mini program with given link

• link: The uri link to start
• options: Start options of this mini program
  
  

Future<ScanResult?> scan()

Start a new page to scan for QR codes, returns a ScanResult if found one

Future<List<AppInfo>?> getRecentList()

Get a list of recent opened mini programs

Future<List<AppInfo>?> searchMiniApp(String keyword,
   {int pageIndex = 0, int pageSize = 0})

Search for online mini programs with given keyword

• keyWord: Keyword of mini program to search
• pageIndex: Page to return if pageSize has a none-zero value, which means paging is enabled.
• pageSize: The max size of a page returned by server. When set to 0, paging willl be disabled.
  
  

Future<void> stopMiniApp(String appId)

Stop mini program with given app ID

• appId: The app id of mini program.
  
  

Future<void> stopAllMiniApp()

Stop all running mini programs

Future<void> deleteMiniAppCache(String appId,
   {int appVerType = 0, String? version})

Remove all local data of mini program with given ID

• appId: the app id of mini program
• appVerType: type of mini program
• version: version of mini program to remove
  
  

Future<AppInfo?> currentMiniApp()

Return information for current foreground running mini program

Future<void> preDownloadMiniApp(List<String> appIdList,
   {bool isDownload = false})

Preload information for online mini programs

• appIdList: a list of app IDs for mini programs to load
• isDownload: if set to true, mini program package will be downloaded after preload, default to false
  
  

void registerOpenApiHandler

Register handler for sdk to send open api event to your flutter code. These events are triggered when mini-program require third-party information or action, such as, account login, request payment or get user information

• handler: method ref to handle open api event

Classes

MiniStartOptions

class MiniStartOptions {
  /// entry path of mini program
  String? entryPath;

  /// is always update mini program when start
  bool? isForceUpdate;

  /// string param passed to mini program when start
  String? params;
}

ScanResult

class ScanResult {
  /// result string of qrcode or barcode contains
  String? result;

  /// the type of code
  String? scanType;

  /// charset of result string
  String? charset;
}

AppInfo

class AppInfo {
  /// MiniProgram id
  String appId;

  /// MiniProgram package type (release, dev, etc.). See [AppVerType]
  int appVerType;

  /// MiniProgram version
  String version;

  /// MiniProgram name
  String? name;

  /// MiniProgram icon url
  String? iconUrl;

  /// MiniProgram description
  String? appIntro;

  /// Developer of MiniProgram
  String? appDeveloper;

  /// MiniProgram release time
  int time;
}

AppVerType

/// Consts for MiniProgram package type. see[AppInfo]
class AppVerType {
  static const int online = 0;
  static const int develop = 1;
  static const int preview = 2;
  static const int experience = 3;
}

OpenApiHandler

abstract class OpenApiHandler {
  /// Called when mini-program invoke wx.requestPayment, requesting third-party payment action
  ///  
  Future<Map<String, dynamic>> requestPayment(
      AppInfo appInfo, Map<Object?, Object?> params);

  /// Called when mini-program invoke wx.getUserProfile, requesting host app's user information
  ///
  Future<Map<String, dynamic>> getUserProfile(
      AppInfo appInfo, Map<Object?, Object?> params);

  /// Called when mini-program invoke wx.login, requesting host app's login certificate
  ///
  Future<Map<String, dynamic>> login(
      AppInfo appInfo, Map<Object?, Object?> params);

  /// Called when mini-program invoke wx.checkSession, requesting host app's login state
  /// check if login expired
  ///
  Future<Map<String, dynamic>> checkSession(
      AppInfo appInfo, Map<Object?, Object?> params);

  /// Called when mini-program invoke wx.getUserInfo, deprecated by wx.getUserProfile
  /// compatibility for earlier mini-program api
  ///
  Future<Map<String, dynamic>> getUserInfo(
      AppInfo appInfo, Map<Object?, Object?> params);

  /// Called when mini-program invoke wx.getPhoneNumber, get current user's phone number
  ///
  Future<Map<String, dynamic>> getPhoneNumber(
      AppInfo appInfo, Map<Object?, Object?> params);
}