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

# 代理方法

小程序的部分功能,需要原生端去实现才能调用,比如转发和获取主体App的用户信息等。 而相应的代理方法都声明在FATAppletDelegate中。

# 1 小程序配置

# 1.1 灰度扩展参数配置

除了,我们平台提供的默认灰度配置项,您也可根据业务数据添加一些灰度控制项,这时业务参数小程序在打开时会通过如下代理方法来读取。

/// 小程序灰度扩展参数
/// @param appletId 小程序id
- (NSDictionary *)grayExtensionWithAppletId:(NSString *)appletId;

示例代码:

- (NSDictionary *)grayExtensionWithAppletId:(NSString *)appletId
{
    NSDictionary *grayExtension = @{@"key11":@"value1",@"key12":@"value2"};
    if ([appletId isEqualToString:@"5e017a61c21ecf0001343e31"]) {
        grayExtension = @{@"fckey1":@"fcvalue1"};
    }
    return grayExtension;
}

然后,SDK请求后台接口时会透传给后台服务匹配相关规则。

# 1.2 小程序参数配置

初始化SDK时,可以设置一些通用的配置项,有的场景我们希望某个配置项只针对某个小程序生效,这时候就可以实现该代理方法。小程序在启动时,会通过该代理方法读取小程序的配置信息。

/// 给小程序设置配置项,使用场景:需要给某个特定小程序设置特殊配置项
/// @param appletInfo 小程序信息
- (FATAppletConfig *)getConfigWithAppletInfo:(FATAppletInfo *)appletInfo;

示例:

- (FATAppletConfig *)getConfigWithAppletInfo:(FATAppletInfo *)appInfo
{
    FATAppletConfig *appletConfig = [[FATAppletConfig alloc] init];
    appletConfig.header = @{@"userId":@"finclip18607180143",
                            @"User-Agent":@"finogeeks-Agent"
    };
    if ([appInfo.appId isEqualToString:@"5e017a61c21ecf0001343e31"]) {
        appletConfig.hideBackToHomeStatus = FATAppletConfigPositive;
    }
    
    return appletConfig;
}

# 2 open-type事件

小程序中的button 有一系列的open-type事件,有部分行为需要App来实现,所以也会通过代理方法来触发对应的事件

# 2.1 share

open-type为share时,触发行为是转发,与 更多菜单里的转发按钮行为一样。都是要转发小程序至其他(比如IM房间)地方。所以,SDK会通过该代理事件,将小程序以及当前页面信息传递出来。若App要实现转发功能,实现该代理方法即可。

/** 转发事件
 当你点击小程序右上角更多里的转发菜单,或者 点击open-type属性为share的Button时,会触发小程序里shareAppMessage方法,然后回调到原生该方法
 @param contentInfo 小程序相关信息,里面包含小程序id、小程序名称、小程序图标、小程序截图(5:4)等。
 {
    appAvatar = "小程序图标地址";
    logoImage=UIImage对象,只有本地小程序且设置了该参数时,才包含。
    appDescription = "小程序的描述信息";
    appId = "小程序id";
    appInfo =  {}; // 客户可在appInfo中自定义字段,appInfo内容会透传
    appStartParams =     {
        path = "点击转发时的小程序页面路径";
    };
    appThumbnail = "小程序封面图的路径,可能是网络路径或者本地路径,宽高比是5:4";
    appTitle = "小程序名称";
    userId = "小程序开发者id";
}
 @param completion 执行完后的回调,如果你转发操作执行完后,希望告知小程序端转发结果,就需要调用该block。
 参考链接:https://www.finclip.com/mop/document/develop/component/form.html#button
 */
- (void)forwardAppletWithInfo:(NSDictionary *)contentInfo completion:(void (^)(FATExtensionCode code, NSDictionary *result))completion;

# 2.2 getUserInfo

调用获取用户信息API(getUserInfo) 或者 点击open-type属性为getUserInfo的Button时触发该代理事件

/**
 调用获取用户信息API(getUserInfo) 或者 点击open-type属性为getUserInfo的Button时触发
 @param appletInfo 小程序信息
 返回值参考格式如下(可由宿主App自定义):
 {
    nickName = "昵称"
    avatarUrl = “头像地址”
    gender = "性别"
    province = "省份"
    city = "城市"
    country = "国家"
    userId = "值为[FATClient sharedClient].config.currentUserId" // sdk默认添加
    baseUrl = "值为appletInfo.apiServer" //// sdk默认添加
 }
*/
- (NSDictionary *)getUserInfoWithAppletInfo:(FATAppletInfo *)appletInfo;

# 2.3 contact

当open-type为contact时,会触发该代理事件。

/// Button open-type属性为contact,打开客服会话。
/// @param appletInfo 小程序信息
/// @param sessionFrom 会话来源
/// @param sendMessageTitle 会话内消息卡片标题
/// @param sendMessagePath 会话内消息卡片点击跳转小程序路径
/// @param sendMessageImg 会话内消息卡片图片
/// @param showMessageCard 小程序信息
- (void)contactWithAppletInfo:(FATAppletInfo *)appletInfo sessionFrom:(NSString *)sessionFrom sendMessageTitle:(NSString *)sendMessageTitle sendMessagePath:(NSString *)sendMessagePath sendMessageImg:(NSString *)sendMessageImg showMessageCard:(BOOL)showMessageCard;

# 2.4 getPhoneNumber

当open-type为getPhoneNumber时,会触发该代理事件。

/// Button open-type属性为getPhoneNumber,获取用户手机号。
/// @param appletInfo 小程序信息
/// @param bindGetPhoneNumber 获取用户手机号回调
- (void)getPhoneNumberWithAppletInfo:(FATAppletInfo *)appletInfo bindGetPhoneNumber:(void (^)(NSDictionary *result))bindGetPhoneNumber;

# 2.5 launchApp

当open-type为launchApp时,会触发该代理事件。

/// Button open-type属性为launchApp,打开APP。
/// @param appletInfo 小程序信息
/// @param appParameter 打开 APP 时,向 APP 传递的参数
/// @param bindError 打开 APP 发生错误的回调
/// @param bindLaunchApp 打开 APP 成功的回调
- (void)launchAppWithAppletInfo:(FATAppletInfo *)appletInfo appParameter:(NSString *)appParameter bindError:(void (^)(NSDictionary *result))bindError bindLaunchApp:(void (^)(NSDictionary *result))bindLaunchApp;

# 2.6 feedback

open-type为feedback时,会触发该代理方法。如果App未实现该代理方法,则会打开 更多菜单里的 投诉反馈页面。

/// Button open-type属性为feedback,打开“意见反馈”页面。(APP 未实现时,则打开菜单栏里面的反馈)
/// @param appletInfo 小程序信息
- (void)feedbackWithAppletInfo:(FATAppletInfo *)appletInfo;

# 2.7 chooseAvatar

open-type为chooseAvatar时,会触发该代理方法。

/// Button open-type属性为chooseAvatar,获取用户头像。
/// @param appletInfo 小程序信息
/// @param bindChooseAvatar 获取用户头像回调
- (void)chooseAvatarWithAppletInfo:(FATAppletInfo *)appletInfo bindChooseAvatar:(void (^)(NSDictionary *result))bindChooseAvatar;

# 3 小程序生命周期代理事件

/**
 小程序打开完成的事件
 @param appletId 小程序id
 @param error 错误对象
 */
- (void)applet:(NSString *)appletId didOpenCompletion:(NSError *)error;

/**
 小程序关闭完成的事件
 @param appletId 小程序id
 @param error 错误对象
 */
- (void)applet:(NSString *)appletId didCloseCompletion:(NSError *)error;

/**
 小程序初始化完成,首页加载出来的事件
 @param appletId 小程序id
 @param error 错误对象
 */
- (void)applet:(NSString *)appletId initCompletion:(NSError *)error;

/**
 小程序进入活跃状态的事件
 @param appletId 小程序id
 @param error 错误对象
 */
- (void)applet:(NSString *)appletId didActive:(NSError *)error;

/**
 小程序进入非活跃状态的事件
 @param appletId 小程序id
 @param error 错误对象
 */
- (void)applet:(NSString *)appletId resignActive:(NSError *)error;

/**
 小程序出错的事件
 @param appletId 小程序id
 @param error 错误对象
 */
- (void)applet:(NSString *)appletId didFail:(NSError *)error;

/**
 小程序被销毁的事件
 @param appletId 小程序id
 @param error 错误对象
 */
- (void)applet:(NSString *)appletId dealloc:(NSError *)error;

# 4 更多按钮以及更多视图

/**
 右上角胶囊中 【...】的点击事件,可在该事件中弹出自己设计的更多视图。
 因此实现了该代理事件,就不会触发下面两个自定义菜单的事件
 @param appletInfo 小程序信息
 @path 小程序页面路径,示例:pages/index/index
 */
- (void)applet:(FATAppletInfo *)appletInfo didClickMoreBtnAtPath:(NSString *)path;

/**
 更多按钮中自定义的菜单,会在页面弹出菜单时调用该api
 @param appletInfo 小程序信息
 @param path 页面路径
 */
- (NSArray<id<FATAppletMenuProtocol>> *)customMenusInApplet:(FATAppletInfo *)appletInfo atPath:(NSString *)path;

/**
 点击自定义菜单时,会触发的事件(新版)
 只有实现了该代理方法,才会触发【-clickCustomItemMenuWithInfo:completion:】
 @param contentInfo 分享信息
 @param appletInfo 小程序信息
 @param completion 分享回调(小程序分享回调:1.【code】回调状态码;2.【result】回传给小程序的回调信息)
 */
- (void)clickCustomItemMenuWithInfo:(NSDictionary *)contentInfo inApplet:(FATAppletInfo *)appletInfo completion:(void (^)(FATExtensionCode code, NSDictionary *result))completion;

代理实现示例:

1.在合适的位置赋值实现代理方法的实例对象

[FATClient sharedClient].delegate = [FATClientHelper shareInstance];

2.创建实现代理方法的类

#import <Foundation/Foundation.h>
#import <FinApplet/FinApplet.h>

@interface FATClientHelper : NSObject<FATAppletDelegate>

+ (instancetype)shareInstance;

@end

3.在实现类(比如FATClientHelper)中实现对应的以上菜单代理事件。

# 5 H5 hook事件

如果宿主app 使用URLProtocol拦截了http 或https,会导致H5中的request 丢失body。我们SDK为了兼容这一问题,会hook request请求。在发起请求之前,先将body中的参数,通过代理方法传递给宿主App,宿主App可自行存储每个request的body,然后在自定义的URLProtocol里发起请求之前,组装上body内容。

所以,当H5中发起request 请求时,集成了我们的js-sdk,就会触发该代理事件。

/**
 小程序H5中发出的request包含body时会触发该事件
 requestInfo 中会包含
 bodyType: body内容的类型
 requestHref: request做在页面的链接
 requestId:请求id,每次请求都会构造,后续拦截请求时,可在query参数中通过FinClipHookBridge-RequestId匹配
 requestUrl:发起request时,请求的地址。
 value: request的body内容。
 示例
 {
     bodyType = String;
     requestHref = "http://aaronly.gitee.io/aymj";
     requestId = 16499170263357297;
     requestUrl = "https://www.finclip.com/api/v1/mop/mop-fast-trial-manager/web/visits/statistics";
     value = "{\"type\":\"download_click\"}";
 };
 */
- (void)applet:(FATAppletInfo *)appletInfo hookRequestInfo:(NSDictionary *)requestInfo;

# 6 录屏、截屏事件

在小程序页面执行录屏或者截屏事件时,也会触发代理事件

/// 录屏事件回调
/// @param appletInfo  录屏事件时,当前正在运行的小程序
/// @param isCapture  是否在录制屏幕
/// @param pagePath  录屏事件时,小程序当前的页面路径
- (void)applet:(FATAppletInfo *)appletInfo screenCaptureStatusChanged:(BOOL)isCapture atPagePath:(NSString *)pagePath;

/// 截屏事件回调
/// @param appletInfo 截屏时,当前正在运行的小程序
/// @param pagePath  截屏时,小程序当前的页面路径
- (void)appletDidTakeScreenshot:(FATAppletInfo *)appletInfo atPagePath:(NSString *)pagePath;

# 7 水印事件

小程序的页面也可以添加水印。在页面将要显示时,会调用该代理方法。如果要在页面上添加水印,可在这里的水印容器视图上绘制内容即可。

/// 自定义添加水印
/// @param appletInfo 小程序信息
/// @param watermaskView 水印容器视图,可在这个视图添加文字或图片等水印内容
- (void)applet:(FATAppletInfo *)appletInfo customizeWatermarkView:(UIView *)watermaskView;

# 8 JS SDK

当对js-sdk调用config进行验证时,会触发该代理事件。需要返回验证结果,成功或失败。

/// 验证 js-sdk config信息 (未实现该代理方法则默认为验证通过)
/// @param appletInfo 小程序信息
/// @param config 验证信息
/// @param completion 执行完后的回调,验证通过则code返回FATExtensionCodeSuccess,失败返回FATExtensionCodeFailure
- (void)applet:(FATAppletInfo *)appletInfo onJSSDKConfig:(NSDictionary *)config completion:(void (^)(FATExtensionCode code, NSDictionary *result))completion;
© 2022 FinClip with ❤

👋🏻 嘿,你好!

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

>> 点我免费注册体验

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

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

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

400-066-00210755-86967467

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

联系线上
人工客服

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

填写 FinClip 问卷抽缤纷夏日盲盒
Hi,这里是我们为 FinClip 用户准备的一封调研问卷,期待您的参与,您的反馈和建议,将指引 FinClip 未来前进的方向。