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. This quick guide shows how to setup and use TCMPP Flutter Plugin.

🆕 EventConfig Auto-Generator

New Feature: Automatically generate event configuration from code annotations! No manual configuration needed.

class EventHandler extends TcmppFlutterEventChannel {
  @EventConfig(value: true)  // Enable event
  @override
  Future<void> isUpdateBaseLib(Map<dynamic, dynamic>? data) async {
    // Your logic here
  }
}

Run flutter pub run build_runner build to auto-generate lib/generated/tcmpp_event_config.json.

📖 中文说明

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. image-20240422150143401

  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 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.

image-20240422153054592

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

image-20240422154058326

  1. 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.

    7226c27b-45c6-4e22-8936-d4ed7678cae7

    1. Click next, download Android / iOS configuration file in the new page.

    3e06ebf3-0034-4302-834d-acf91e144bf4

Add configuration file

  1. Put TCSAS configuration file someware in your flutter project.

  2. Add a file named "tcsas-plugin-settings.json" in your project's root.

  3. Edit pubspec.yaml file and add flutter assets for files mentioned above.

  4. Specify the path to TCSAS configuration file in "tcsas-plugin-settings.json".

SDK settings

In the tcsas-plugin-settings.json file, you can choose to configure settings of your SDK.

For Android:

field name type function
configAssetsName string TCMPP android configuration file path
debug bool enable SDK debug

For iOS:

field name type function
configAssetsName string TCMPP iOS configuration file path
debug bool enable SDK debug
logEnable bool enable SDK log

For common:

field name type function
appName string Host app name, mainly used for copyright prompts in mini-program
appVersion string Host app version, mainly used for copyright prompts in mini-program

Gateway request signing

Register the DeviceKey handler before launching a mini program. Obtain the key from your secure service; do not hard-code or log it in the application.

await TcmppFlutter().registerDeviceKeyHandler((request) async {
  final key = await loadDeviceKeyFromSecureService(
    uuid: request.uuid,
    appId: request.appId,
    platform: request.platform,
    customId: request.customId,
    sdkVersion: request.sdkVersion,
  );
  if (key == null) {
    // No key with no error means that this key fetch should not be signed.
    return null;
  }
  return DeviceKey(
    deviceKey: key.deviceKey,
    version: key.version,
    windowSize: key.windowSize,
    allowPersist: key.allowPersist,
  );
});

Returning null skips signing for the current key fetch. Throwing an exception reports a fetch failure so the native SDK can apply its cache/retry policy. Passing null as the handler disables further Flutter DeviceKey callbacks:

await TcmppFlutter().registerDeviceKeyHandler(null);

On Android, allowPersist controls whether the SDK persists the key. The iOS SDK consumes deviceKey, version, and windowSize and manages its own secure key storage.

Feedback page theme

Configure the complaint and feedback page before it is opened. Colors use the #RRGGBB format, and either color can be omitted to keep the SDK default.

await TcmppFlutter().configFeedbackTheme(
  FeedbackThemeConfig(
    primaryColor: '#FF6600',
    backgroundColor: '#F5F5F5',
  ),
);

Restore all SDK defaults by passing null:

await TcmppFlutter().configFeedbackTheme(null);

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.

image-20240419181348211

minSdkVersion 21
  1. In android > defaultConfig section, add packagingOptions.

image-20240419181539243

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://github.com/TCMPP-Team/tcmpp-repo.git'
source 'https://github.com/CocoaPods/Specs.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'.

    image-20240419182106686

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

    image-20240419182158294

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 mini program QR code and start mini program 

Future<List<AppInfo>?> getRecentList()

Get a list of recent opened mini programs 

Future<SearchMiniAppResult?> searchMiniApp(
    String keyword,{
      SearchAppType searchAppType = SearchAppType.searchAppTypeAll,
      CategoryInfo? category = const CategoryInfo(),
      PageInfo? pageInfo = const PageInfo()
})

Search for online mini programs with given keyword

  • keyWord: Keyword of mini program to search

  • pageInfo: The index and size of a page returned by server. When set to 0, paging willl be disabled.

  • searchAppType: searchAppType：mini app or mini game.See SearchAppType

  • category: The category of classification of the miniapp.



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<List<AppInfo>> getRunningAppList([
  SearchAppType appType = SearchAppType.searchAppTypeAll,
])

Return all foreground and kept-alive mini programs. Use SearchAppType.searchAppTypeAll, SearchAppType.searchAppTypeApp, or SearchAppType.searchAppTypeGame to filter the result. When no matching instance exists, an empty list is returned.

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;

  /// mini app or mini game. See [AppType]
  int appType;

  /// MiniProgram version
  String version;

  /// MiniProgram name
  String? name;

  /// MiniProgram icon url
  String? iconUrl;

  /// MiniProgram description
  String? appIntro;

  /// Developer of MiniProgram
  String? appDeveloper;

  /// MiniProgram categories
  List<CategoryInfo> appCategorys;

  /// 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;
}

AppType

/// Type, mini app or mini game
///
final class AppType {
static const int appTypeApp = 0;
static const int appTypeGame = 1;
AppType._();
}

SearchAppType

/// Type, mini app or mini game
///
final class SearchAppType {
static const int searchAppTypeAll = 0;
static const int searchAppTypeApp = 1;
static const int searchAppTypeGame = 2;
SearchAppType._();
}

EventConfig注解代码生成器

TCMPP Flutter插件提供了一个EventConfig注解代码生成器，它可以自动扫描项目中实现了TcmppFlutterEventChannel的类，读取方法上的@EventConfig注解，并生成配置文件。

快速开始

  1. 在实现了TcmppFlutterEventChannel的类方法上使用@EventConfig注解：
import 'package:tcmpp_flutter/tcmpp_flutter.dart';
import 'package:tcmpp_flutter/src/annotations.dart';

class EventHandler extends TcmppFlutterEventChannel {
  @EventConfig(value: true)
  @override
  Future<void> isUpdateBaseLib(Map<dynamic, dynamic>? data) async {
    // 实现代码
  }

  @EventConfig(value: false)
  @override
  Future<void> reportRealTimeLog(RealTimeLogInfo? logInfo) async {
    // 实现代码
  }
}
  1. 运行生成器脚本：
# 在tcmpp_flutter插件目录中运行
./bin/generate_event_config.sh

# 或在集成tcmpp_flutter的项目中运行
./path/to/tcmpp_flutter/bin/generate_event_config.sh
  1. 生成的配置文件将位于lib/generated/event_config.g.dart：
final Map<String, dynamic> eventConfig = {
  'isUpdateBaseLib': true,
  'reportRealTimeLog': false,
};

详细使用说明

请参考EVENT_CONFIG_README.md获取更多详细信息和高级用法。

Documents

For more information about usage and APIs of TCMPP Flutter plugin, see Accessing with Flutter

Libraries

tcmpp_config_manager
tcmpp_data_class
tcmpp_flutter