FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

# 回调方法

小程序中部分业务是抽象定义的,这些抽象的业务通过接口的形式暴露给了外部,外部可以自行实现具体的业务逻辑。

这些代理方法都声明在[IAppletHandler]、[IAppletProcessHandler]等抽象类中。

# 1. IAppletHandler

部分抽象业务被定义在IAppletHandler中,应用可以通过调用IAppletApiManagersetAppletHandlerIAppletHandler的实例传给SDK,当业务被触发时,SDK将通过IAppletHandler对应的方法回调给外部,执行外部实现的具体的业务逻辑。

/**
 * 小程序抽象业务回调接口,SDK将这些抽象的业务通过接口的形式暴露给外部,由外部具体实现
 */
interface IAppletHandler {

    interface IAppletCallback {

        /**
         * 成功回调
         */
        fun onSuccess(result: JSONObject? = null)

        /**
         * 失败回调
         */
        fun onFailure()

        /**
         * 取消回调
         */
        fun onCancel()
    }

    /**
     * 转发小程序
     *
     * @param appInfo 小程序信息,是一串json,包含了小程序id、小程序名称、小程序图标、用户id、转发的数据内容等信息。
     * [appInfo]的内容格式如下:
     * {
     *      "appTitle": "凡泰小程序",
     *      "appAvatar": "https:\/\/www.finogeeks.club\/statics\/images\/swan_mini\/swan_logo.png",
     *      "appId": "5df36b3f687c5c00013e9fd1",
     *      "appType": "trial",
     *      "userId": "finogeeks",
     *      "cryptInfo": "SFODj9IW1ENO8OA0El8P79aMuxB1DJvfKenZd7hrnemVCNcJ+Uj9PzkRkf/Pu5nMz0cGjj0Ne4fcchBRCmJO+As0XFqMrOclsqrXaogsaUPq2jJKCCao03vI8rkHilrWxSDdzopz1ifJCgFC9d6v29m9jU29wTxlHsQUtKsk/wz0BROa+aDGWh0rKvUEPgo8mB+40/zZFNsRZ0PjsQsi7GdLg8p4igKyRYtRgOxUq37wgDU4Ymn/yeXvOv7KrzUT",
     *      "params": {
     *           "title": "apt-test-tweet-接口测试发布的动态!@#¥%……&*(",
     *           "desc": "您身边的服务专家",
     *           "imageUrl": "finfile:\/\/tmp_fc15edd8-2ff6-4c54-9ee9-fe5ee034033d1576550313667.png",
     *           "path": "pages\/tweet\/tweet-detail.html?fcid=%40staff_staff1%3A000000.finogeeks.com&timelineId=db0c2098-031e-41c4-b9c6-87a5bbcf681d&shareId=3dfa2f78-19fc-42fc-b3a9-4779a6dac654",
     *           "appInfo": {
     *               "weixin": {
     *                   "path": "\/studio\/pages\/tweet\/tweet-detail",
     *                   "query": {
     *                       "fcid": "@staff_staff1:000000.finogeeks.com",
     *                       "timelineId": "db0c2098-031e-41c4-b9c6-87a5bbcf681d"
     *                    }
     *               }
     *           }
     *       }
     * }
     * [appInfo]中各字段的说明:
     * appId 小程序ID
     * appTitle 小程序名称
     * appAvatar 小程序头像
     * appType 小程序类型,其中trial表示体验版,temporary表示临时版,review表示审核版,release表示线上版,development表示开发版
     * userId 用户ID
     * cryptInfo 小程序加密信息
     * params 附带的其它参数,由小程序自己透传
     *     
     * @param bitmap 小程序封面图片。如果[appInfo].params.imageUrl字段为http、https的链接地址,那么小程序封面图片
     * 就取[appInfo].params.imageUrl对应的图片,否则小程序的封面图片取[bitmap]。
     */
    fun shareAppMessage(appInfo: String, bitmap: Bitmap?, callback: IAppletCallback)

    /**
     * 获取用户信息
     *
     * @return 用户信息[Map]
     */
    fun getUserInfo(): Map<String, String>
  
  	/**
     * 获取用户手机号
     * 通过回调以json格式返回信息,一般格式如下:
     * {"phone": "xxxxxxxxxxx"}
     */
  	override fun getPhoneNumber(callback: IAppletHandler.IAppletCallback) {
        callback.onSuccess(JSONObject().put("phone", "xxxxxxxxxxx"))
    }

  	/**
     * 从小程序页面回到宿主app页面事件,由宿主app实现此操作;
     * @return 如果正确处理该事件返回true,否则返回false.
     */
    override fun launchApp(appParameter: String?): Boolean {
        return false
    }

  	/**
     * 打开"意见反馈"页面,由宿主app接管实现;
     * @return 如果宿主app接管此事件返回true,否则返回false,同时打开默认意见反馈页面。
     */
    override fun feedback(bundle: Bundle): Boolean {
        return false
    }

  	/**
     * 获取用户头像,通过回调返回信息,由SDK透传给小程序
     */
    override fun chooseAvatar(callback: IAppletHandler.IAppletCallback) {
        callback.onFailure()
    }

  	/**
     * 打开客服会话,由宿主app实现具体操作
     * @param json 由小程序透传给宿主app的数据
     * @return 成功打开会话返回true,否则返回false
     */
    override fun contact(json: JSONObject): Boolean {
        return false
    }
    
    /**
     * 获取注册的"更多"菜单项
     *
     * @param appId 小程序ID
     * @return 注册的"更多"菜单项
     */
    fun getRegisteredMoreMenuItems(appId: String): List<MoreMenuItem>?

    /**
     * 注册的"更多"菜单项被点击
     *
     * @param appId 小程序ID
     * @param path 小程序页面路径
     * @param menuItemId 被点击的菜单条目的ID
     * @param appInfo 小程序信息,是一串json,包含了小程序id、小程序名称、小程序图标、用户id、转发的数据内容等信息。
     * [appInfo]的内容格式如下:
     * {
     *      "appTitle": "凡泰小程序",
     *      "appAvatar": "https:\/\/www.finogeeks.club\/statics\/images\/swan_mini\/swan_logo.png",
     *      "appId": "5df36b3f687c5c00013e9fd1",
     *      "appType": "trial",     
     *      "userId": "finogeeks",
     *      "cryptInfo": "SFODj9IW1ENO8OA0El8P79aMuxB1DJvfKenZd7hrnemVCNcJ+Uj9PzkRkf/Pu5nMz0cGjj0Ne4fcchBRCmJO+As0XFqMrOclsqrXaogsaUPq2jJKCCao03vI8rkHilrWxSDdzopz1ifJCgFC9d6v29m9jU29wTxlHsQUtKsk/wz0BROa+aDGWh0rKvUEPgo8mB+40/zZFNsRZ0PjsQsi7GdLg8p4igKyRYtRgOxUq37wgDU4Ymn/yeXvOv7KrzUT",
     *      "params": {
     *           "title": "apt-test-tweet-接口测试发布的动态!@#¥%……&*(",
     *           "desc": "您身边的服务专家",
     *           "imageUrl": "finfile:\/\/tmp_fc15edd8-2ff6-4c54-9ee9-fe5ee034033d1576550313667.png",
     *           "path": "pages\/tweet\/tweet-detail.html?fcid=%40staff_staff1%3A000000.finogeeks.com&timelineId=db0c2098-031e-41c4-b9c6-87a5bbcf681d&shareId=3dfa2f78-19fc-42fc-b3a9-4779a6dac654",
     *           "appInfo": {
     *               "weixin": {
     *                   "path": "\/studio\/pages\/tweet\/tweet-detail",
     *                   "query": {
     *                       "fcid": "@staff_staff1:000000.finogeeks.com",
     *                       "timelineId": "db0c2098-031e-41c4-b9c6-87a5bbcf681d"
     *                    }
     *               }
     *           }
     *       }
     * }
     * [appInfo]中各字段的说明:
     * appId 小程序ID
     * appTitle 小程序名称
     * appAvatar 小程序头像
     * appType 小程序类型,其中trial表示体验版,temporary表示临时版,review表示审核版,release表示线上版,development表示开发版
     * userId 用户ID
     * cryptInfo 小程序加密信息
     * params 附带的其它参数,由小程序自己透传
     *
     * @param bitmap 小程序封面图片。如果[appInfo].params.imageUrl字段为http、https的链接地址,那么小程序封面图片
     * 就取[appInfo].params.imageUrl对应的图片,否则小程序的封面图片取[bitmap]。
     */
    fun onRegisteredMoreMenuItemClicked(appId: String, path: String, menuItemId: String, appInfo: String?, bitmap: Bitmap?, callback: IAppletCallback)
    
    /**
     * 获取灰度发布配置参数
     *
     * @param appId 小程序ID
     * @return 灰度发布配置参数
     */
    fun getGrayAppletVersionConfigs(appId: String): List<GrayAppletVersionConfig>?
    
    /**
     * 小程序导航栏中的"关闭"按钮被点击
     *
     * @param appId 小程序ID
     */
    fun onNavigationBarCloseButtonClicked(appId: String)
}

# API

/**
 * 设置[IAppletHandler]的实现类
 *
 * @param appletHandler [IAppletHandler]的实现类
 */
fun setAppletHandler(appletHandler: IAppletHandler)

# 调用示例

FinAppClient.appletApiManager.setAppletHandler(
    object : IAppletHandler {
        override fun shareAppMessage(
            appInfo: String,
            bitmap: Bitmap?,
            callback: IAppletHandler.IAppletCallback
        ) {

        }
    })
FinAppClient.INSTANCE.getAppletApiManager().setAppletHandler(new IAppletHandler() {
    @Override
    public void shareAppMessage(@NotNull String appInfo,
                                @Nullable Bitmap bitmap,
                                @NotNull IAppletCallback callback) {

    }
});

注意

  • FinAppClient类需要在小程序进程使用。
  • 对于异步回调的方法(参数带有callback),请务必保证无论业务逻辑成功与否都使用callback进行回调,否则小程序端会无法收到调用结果。

# 2. IAppletProcessHandler

# API

/**
 * 设置[IAppletProcessHandler]的实现类
 *
 * @param appletProcessHandler [IAppletProcessHandler]的实现类
 */
fun setAppletProcessHandler(appletProcessHandler: IAppletProcessHandler)

# 调用示例

FinAppProcessClient.appletProcessApiManager.setAppletProcessHandler(
    object : IAppletProcessHandler {
        override fun onNavigationBarMoreButtonClicked(
            context: Context,
            appId: String
        ): Boolean {
            return true // 返回true表示自行处理"更多"按钮点击事件,屏蔽默认菜单显示逻辑。
        }
    })
FinAppProcessClient.INSTANCE.getAppletProcessApiManager().setAppletProcessHandler(new IAppletProcessHandler(){
    @Override
    public boolean onNavigationBarMoreButtonClicked(@NonNull Context context, @NonNull String appId) {
        return true; // 返回true表示自行处理"更多"按钮点击事件,屏蔽默认菜单显示逻辑。
    }
});

注意

  • FinAppProcessClient类需要在小程序进程使用。

    请使用FinAppClient.INSTANCE.isFinAppProcess()方法判断是否处于小程序进程

  • IAppletProcessHandler接口方法在小程序进程执行。

# 3. IAppletLifecycleCallback

外部如果需要监听小程序的生命周期,可以调用IAppletApiManagersetAppletLifecycleCallback接口把IAppletLifecycleCallback的实例传给SDK,当小程序的生命周期发生变化时,SDK会通过IAppletLifecycleCallback对应的方法回调给外部。

/**
 * 小程序生命周期回调接口
 */
interface IAppletLifecycleCallback {

    /**
     * 小程序当前页面状态,与[Activity].[onCreate]对应
     */
    fun onCreate(appId: String)

    /**
     * 小程序当前页面状态,与[Activity].[onStart]对应
     */
    fun onStart(appId: String)

    /**
     * 小程序当前页面状态,与[Activity].[onResume]对应
     */
    fun onResume(appId: String)

    /**
     * 小程序当前页面状态,与[Activity].[onPause]对应
     */
    fun onPause(appId: String)

    /**
     * 小程序当前页面状态,与[Activity].[onStop]对应
     */
    fun onStop(appId: String)

    /**
     * 小程序当前页面状态,与[Activity].[onDestroy]对应
     */
    fun onDestroy(appId: String)
}

# API

/**
 * 设置[IAppletLifecycleCallback]
 *
 * @param appletLifecycleCallback [IAppletLifecycleCallback]对象
 */
fun setAppletLifecycleCallback(appletLifecycleCallback: IAppletLifecycleCallback)

# 调用示例

FinAppClient.appletApiManager.setAppletLifecycleCallback(object : IAppletLifecycleCallback {
     override fun onCreate(appId: String) {
        Log.d(TAG, "IAppletLifecycleCallback onCreate : $appId")
    }

    override fun onInitComplete(appId: String) {
        Log.d(TAG, "IAppletLifecycleCallback onInitComplete : $appId")
    }

    override fun onStart(appId: String) {
        Log.d(TAG, "IAppletLifecycleCallback onStart : $appId")
    }

    override fun onResume(appId: String) {
        Log.d(TAG, "IAppletLifecycleCallback onResume : $appId")
    }

    override fun onPause(appId: String) {
        Log.d(TAG, "IAppletLifecycleCallback onPause : $appId")
    }

    override fun onStop(appId: String) {
        Log.d(TAG, "IAppletLifecycleCallback onStop : $appId")
    }

    override fun onDestroy(appId: String) {
        Log.d(TAG, "IAppletLifecycleCallback onDestroy : $appId")
    }

    override fun onFailure(appId: String, errMsg: String) {
        Log.d(TAG, "IAppletLifecycleCallback onFailure : $appId ,$errMsg")
    }
})
FinAppClient.INSTANCE.getAppletApiManager().setAppletLifecycleCallback(new IAppletLifecycleCallback() {

    @Override
    public void onCreate(@NotNull String appId) {
        Log.d(TAG, "IAppletLifecycleCallback onCreate : " + appId);
    }
    
    @Override
    public void onInitComplete(@NotNull String appId) {
        Log.d(TAG, "IAppletLifecycleCallback onInitComplete : " + appId);
    }

    @Override
    public void onStart(@NotNull String appId) {
        Log.d(TAG, "IAppletLifecycleCallback onStart : " + appId);
    }

    @Override
    public void onResume(@NotNull String appId) {
        Log.d(TAG, "IAppletLifecycleCallback onResume : " + appId);
    }

    @Override
    public void onPause(@NotNull String appId) {
        Log.d(TAG, "IAppletLifecycleCallback onPause : " + appId);
    }

    @Override
    public void onStop(@NotNull String appId) {
        Log.d(TAG, "IAppletLifecycleCallback onStop : " + appId);
    }

    @Override
    public void onDestroy(@NotNull String appId) {
        Log.d(TAG, "IAppletLifecycleCallback onDestroy : " + appId);
    }

    @Override
    public void onFailure(@NotNull String appId, String errMsg) {
        Log.d(TAG, "IAppletLifecycleCallback onFailure : " + appId);
    }
});

# 4. IAppletOpenTypeHandler

2.37.13版本开始,IAppletHandler中拆分出来专门用于open-type类型事件的接口类,包含getPhoneNumberchooseAvatarlaunchAppcontactshareAppMessagefeedback

# 代码示例:

FinAppClient.appletOpenTypeHandler = MyAppletOpenTypeHandler()
FinAppClient.INSTANCE.setAppletOpenTypeHandler(new MyAppletOpenTypeHandler());

注意

  • FinAppClient类需要在小程序进程使用。

  • 设置了IAppletOpenTypeHandler,将会覆盖掉IAppletHandler中以上open-type方法的实现。

  • 若集成了微信扩展SDK(WeChatSDK),请勿使用该接口类,而是使用:

    WeChatOpenTypeClient.instance.iWeChatOpenTypeHandler = MyWeChatAppletOpenTypeHandler()
    
© 2022 FinClip with ❤

👋🏻 嘿,你好!

「FinClip」是一套基于云原生框架设计的小程序容器。能够让任何移动应用在集成小程序SDK之后,获得可用、安全的小程序运行能力。

>> 点我免费注册体验

查看产品文档
了解与 FinClip 相关的一切信息

产品博客 👈  了解产品更新与核心功能介绍
资源下载 👈  获取小程序 SDK 与开发工具
文档中心 👈  查询 FinClip 小程序开发指南与答疑

商务咨询热线
预约 FinClip 产品介绍,咨询商务报价或私有化部署事宜

0755-86967467

获取产品帮助
联系 FinClip 技术顾问,获取产品资料或加入开发者社群

联系线上
人工客服

或 👉  点击这里,提交咨询工单