回调方法

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

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

1. IAppletHandler

部分抽象业务被定义在IAppletHandler中，应用可以通过调用IAppletApiManager的setAppletHandler把IAppletHandler的实例传给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

外部如果需要监听小程序的生命周期，可以调用IAppletApiManager的setAppletLifecycleCallback接口把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类型事件的接口类，包含getPhoneNumber、chooseAvatar、launchApp、contact、shareAppMessage、feedback。

代码示例：

FinAppClient.appletOpenTypeHandler = MyAppletOpenTypeHandler()

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

注意

• FinAppClient类需要在主进程使用。

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

• 若集成了微信扩展SDK（WeChatSDK），请勿使用该接口类，而是使用：

  WeChatOpenTypeClient.instance.iWeChatOpenTypeHandler = MyWeChatAppletOpenTypeHandler()
  

5. IShareAppletHandler

从 2.39.11 版本开始，小程序更多菜单中会新增”分享“按钮，可以依赖 ShareSDK 并进行相应的简单配置，实现分享小程序的功能，也可以自行实现 IShareAppletHandler 接口，实现对应功能。

注意

IShareAppletHandler 的实现类将会在小程序运行时通过反射创建示例，因此请保持无参构造方法，并不要直接访问主进程内的变量，否则将会出现异常。

代码示例：

class ShareAppletHandler : IShareAppletHandler {
    override fun onShareApplet(
        context: Context,
        appInfo: FinAppInfo,
        appletPagePath: String
    ) {
        // 您自己的业务逻辑
    }
}

public class ShareAppletHandler implements IShareAppletHandler {
    @Override
    public void onShareApplet(@NonNull Context context,
                              @NonNull FinAppInfo finAppInfo,
                              @NonNull String appletPagePath) {
        // 您自己的业务逻辑
    }
}

并在SDK初始化时进行设置。

代码示例：

val config = FinAppConfig.Builder()
        // 其它配置项省略
        .setShareAppletHandler(ShareAppletHandler::class.java)
        .build()
FinAppClient.init(application, finAppConfig, finCallback)

FinAppConfig config = new FinAppConfig.Builder()
        // 其它配置项省略
        .setShareAppletHandler(ShareAppletHandler.class)
        .build();
FinAppClient.INSTANCE.init(application, config, finCallback);