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

# 代理方法

小程序的部分功能,需要原生端去实现才能调用,比如转发和获取主体App的用户信息等。

在2.37.13之前,所有的代理事件都添加在协议FATAppletDelegate中,所以 我们只需要设置[FATClient sharedClient].delegate即可。

而2.37.13之后,我们将代理方法按照功能做了拆分,您可根据需要设置对应的代理即可。 当然,旧版本的代理事件也是兼容的。需要注意的是:若同时实现的新的代理和旧的代理,那么只会响应新的代理方法。

  • configurationDelegate:小程序配置相关代理
  • buttonOpenTypeDelegate:小程序中button组件不同类型事件的代理
  • lifeCycleDelegate:小程序生命周期事件代理
  • moreMenuDelegate:更多视图相关的代理
  • waterMaskAndScreenCaptureDelegate:水印和截图、录屏相关代理
  • localAppletDelegate:本地小程序相关代理

设置示例

[FATClient sharedClient].buttonOpenTypeDelegate = [FINButtonDelegate sharedHelper];
[FATClient sharedClient].lifeCycleDelegate = [FINLifeCycleDelegate sharedHelper];
[FATClient sharedClient].moreMenuDelegate = [FINMoreMenuDelegate sharedHelper];
[FATClient sharedClient].localAppletDelegate = [FINlocalAppletDelegate sharedHelper];
[FATClient sharedClient].configurationDelegate = [FINConfigurationDelegate sharedHelper];
[FATClient sharedClient].waterMaskAndScreenCaptureDelegate = [FINWaterMaskAndScreenCaptureDelegate sharedHelper];

//[FATClient sharedClient].delegate = [FINDemoClientHelper sharedHelper];(2.37.13前设置这一个就行了)

# 1. configurationDelegate

FATAppletConfigurationDelegate中是小程序配置相关的代理事件。

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

# 1.3 设置小程序加载H5时的Cookie

小程序运行时,你可能想在打开H5页面时注入cookie,可以通过该代理方法进行配置

/// 设置小程序的Cookie
/// @param appletId 小程序id
- (NSDictionary *)getCookieWithAppletInfo:(NSString *)appletId;

示例:

- (NSDictionary *)getCookieWithAppletInfo:(NSString *)appletId {
    NSMutableDictionary *cookieProperties = [NSMutableDictionary dictionary];
    [cookieProperties setObject:@"Hm_apvt_0d885a47c55a66238287cbd00b79a117" forKey:NSHTTPCookieName];
    [cookieProperties setObject:@"finogeeks" forKey:NSHTTPCookieValue];
    [cookieProperties setObject:@".myqcloud.com" forKey:NSHTTPCookieDomain];
    [cookieProperties setObject:@"finogeeks.com" forKey:NSHTTPCookieOriginURL];
    [cookieProperties setObject:@"/" forKey:NSHTTPCookiePath];
    [cookieProperties setObject:@"0" forKey:NSHTTPCookieVersion];
    [cookieProperties setObject:[NSDate dateWithTimeIntervalSinceNow:36000] forKey:NSHTTPCookieExpires];
    return cookieProperties;
}

# 1.4 验证 js-sdk config信息

当对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;

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

# 2. buttonOpenTypeDelegate

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

注意

2.37.13前的open-type事件相关的代理方法无返回值

# 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。
 @return 实现该方法后返回YES
 参考链接:https://www.finclip.com/mop/document/develop/component/form.html#button
 */
- (BOOL)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 小程序信息
 @param bindGetUserInfo 获取用户信息回调
 @return 实现该方法后返回YES
  result参考格式如下(可由宿主App自定义):
 {
    nickName = "昵称"
    avatarUrl = “头像地址”
    gender = "性别"
    province = "省份"
    city = "城市"
    country = "国家"
    userId = "值为[FATClient sharedClient].config.currentUserId" // sdk默认添加
    baseUrl = "值为appletInfo.apiServer" //// sdk默认添加
 }
*/
- (BOOL)getUserInfoWithAppletInfo:(FATAppletInfo *)appletInfo bindGetUserInfo:(void (^)(NSDictionary *result))bindGetUserInfo;

# 2.3 contact

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

/// Button open-type属性为contact,打开客服会话。
/// @param appletInfo 小程序信息
/// @param sessionFrom 会话来源
/// @param sendMessageTitle 会话内消息卡片标题
/// @param sendMessagePath 会话内消息卡片点击跳转小程序路径
/// @param sendMessageImg 会话内消息卡片图片
/// @param showMessageCard 小程序信息
/// @return 实现该方法后返回YES
- (BOOL)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 获取用户手机号回调
/// @return 实现该方法后返回YES
- (BOOL)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 成功的回调
/// @return 实现该方法后返回YES
- (BOOL)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 小程序信息
/// @return 实现该方法后返回YES
- (BOOL)feedbackWithAppletInfo:(FATAppletInfo *)appletInfo;

# 2.7 chooseAvatar

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

/// Button open-type属性为chooseAvatar,获取用户头像。
/// @param appletInfo 小程序信息
/// @param bindChooseAvatar 获取用户头像回调
/// @return 实现该方法后返回YES
- (BOOL)chooseAvatarWithAppletInfo:(FATAppletInfo *)appletInfo bindChooseAvatar:(void (^)(NSDictionary *result))bindChooseAvatar;

# 3. lifeCycleDelegate

小程序生命周期代理事件:didOpen、didClose、init、didActive、resignActive、didFail、dealloc。

# 3.1 小程序打开完成的事件

/**
 小程序打开完成的事件
 @param appletInfo 小程序info
 @param error 错误对象
 */
- (void)appletInfo:(FATAppletInfo *)appletInfo didOpenCompletion:(NSError *)error;

# 3.2 小程序关闭完成的事件

/**
 小程序关闭完成的事件
 @param appletInfo 小程序info
 @param error 错误对象
 */
- (void)appletInfo:(FATAppletInfo *)appletInfo didCloseCompletion:(NSError *)error;

# 3.3 小程序初始化完成,首页加载出来的事件

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

# 3.4 小程序进入活跃状态的事件

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

# 3.5 小程序进入非活跃状态的事件

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

# 3.6 小程序出错的事件

/**
 小程序出错的事件
 @param appletInfo 小程序info
 @param error 错误对象
 */
- (void)appletInfo:(FATAppletInfo *)appletInfo didFail:(NSError *)error;

# 3.7 小程序被销毁的事件

/**
 小程序被销毁的事件
 @param appletInfo 小程序info
 @param error 错误对象
 */
- (void)appletInfo:(FATAppletInfo *)appletInfo dealloc:(NSError *)error;

# 4.moreMenuDelegate

更多视图面板相关的代理事件,这些代理方法可实现自定义更多视图 或自定义更多视图里的菜单项。

# 4.1 右上角胶囊中 【...】的点击事件

可在该事件中弹出自己设计的更多视图,返回YES,代表您要自己自定义更多视图;返回NO或不实现,代表不自定义更多视图。

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

# 4.1 自定义更多视图中菜单项的代理方法

更多按钮中自定义的菜单,会在页面弹出菜单时调用该api来获取自定义菜单项的数据源

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

# 4.1 点击自定义菜单时,会触发的事件

/**
 点击自定义菜单时,会触发的事件(新版)
 只有实现了该代理方法,才会触发【-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;

# 5. waterMaskAndScreenCaptureDelegate 录屏、截屏、水印事件

# 5.1 小程序录屏代理事件

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

# 5.2 小程序截屏代理事件

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

# 5.3 小程序水印代理事件

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

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

# 6. localAppletDelegate

打开本地小程序相关的事件

# 6.1 本地小程序打开其他小程序的代理事件

由于本地小程序,都是由App配置的小程序信息,所以本地小程序中调用navigateToMiniProgram时,会触发该代理方法,由App实现打开其他小程序的功能。

/**
 触发打开其他本地小程序的请求事件
 该事件只有离线小程序才会触发。
 @param appletInfo 小程序对象
 @param request 小程序request对象,应该直接使用该request对象,不要创建新的对象。
 @param currentVC 当前小程序的顶层视图控制器
 @param completion 打开小程序完毕的回调
 */
- (void)applet:(FATAppletInfo *)appletInfo
    navigateToMiniProgram:(FATLocalAppletRequest *)request
                currentVC:(UIViewController *)currentVC
               completion:(void (^)(FATExtensionCode code, NSDictionary *result))completion;

# 6.2 本地小程序获取zip分包路径的代理事件

本地小程序也包含分包小程序,由于部分分包是在小程序触发跳转逻辑时才会触发,所以当小程序跳转至未下载的分包时,会触发该代理方法,由App实现代理获取分包的过程。

/**
 本地小程序从宿主App获取zip分包路径(适用于小程序分包加载,小程序分包加载必须实现)
 如果有多个小程序的分包放在app包中,为了避免zip分包同名,可以将不同小程序的分包放在不同文件夹中,
 并通过create folder references方式引入,代码中通过 文件夹名称/分包名.zip 方式获取分包
 @param appletInfo 小程序信息
 @param packDict 分包信息
 @param zipPathCallback zip分包路径回调,路径获取失败调用 zipPathCallback(nil)
 */
- (void)localApplet:(FATAppletInfo *)appletInfo packDict:(NSDictionary *)packDict zipPathCallback:(void (^)(NSString *zipPath))zipPathCallback;

# 6.3 getAccountInfoSync的代理事件

由于本地小程序的小程序信息是由App维护的,所以当本地小程序内调用ft.getAccountInfoSync时,会触发该代理事件,需要同步返回当前账号信息。

/// 获取本地小程序账号信息
/// @brief 获取本地小程序账号信息,返回的信息结构:
/// @{
///     @"miniProgram": @{
///         @"appId": ##小程序appId##,
///         @"envVersion": ##小程序版本##,
///         @"version": ##线上小程序版本号##
///     },
///     @"plugin": @{
///         @"appId": ##插件appId##,
///         @"version": ##插件版本号##
///     }
/// }
/// @param appletInfo 小程序信息
/// @return 小程序账号信息
- (NSDictionary *)localAppletAccountInfo:(FATAppletInfo *)appletInfo;
© 2022 FinClip with ❤

👋🏻 嘿,你好!

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

>> 点我免费注册体验

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

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

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

0755-86967467

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

联系线上
人工客服

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