手把手系列：如何将小程序游戏引入自有APP？（iOS篇）

自FinClip  诞生以来，一直有不少开发者询问官方 FinClip 什么时候可以支持微信小游戏？实际上，从去年开始我们就把支持微信小游戏的计划做进了产品的 Roadmap。2022年底，我们终于在新年之前实现了对小游戏的支持！

近期，我们将面向开发者们发起产品公测！我们诚挚的邀请各位来参与FinClip  支持小游戏的内测体验活动，欢迎大家来试用、拍砖。By the way，官方也为参与公测的大家准备了丰富的礼物～敬请期待！

言归正传，本期手把手系列将为大家演示将小程序游戏引入自有app的操作流程！

在 iOS 项目中引入 FinClip SDK ，实现小程序游戏在App中运行，操作如下：

第一步：获取凭据（ SDK KEY 及 SDK SECRET）

首先，集成 SDK 需要先在 FinClip 平台中创建应用并绑定小程序游戏应用，获得每个应用专属的SDK KEY及SDK SECRET后，随后就可以在集成 SDK 时填写对应的参数。打开小程序时 SDK 会自动初始化，并校验SDK KEY，SDK SECRET与BundleID(Application ID)是否正确，这一步正确了才能初始化成功并正常使用。

1.1 创建小程序游戏

需要登录FinClip管理后台「宿主应用-新增合作应用」，完成小游戏应用创建；

1.2 获取 SDK KEY 及 SDK SECRET

新增应用后，可以展开应用名称，在下方的列表中点击「添加 BundleID」，在出现的弹窗中输入需要绑定应用的 BundleID。

完成 BundleID 的填写，并点击确定按钮后，您会看到如上图所示的界面。其中的SDK KEY，SDK SECRET与API SERVER是您在集成小程序 SDK 时需要要到的凭据。

⚠️请注意：

• SDK KEY：是合作应用能使用小程序 SDK 的凭证，如果 SDK Key 校验失败，则SDK 的所有 Api 都无法使用。
• SDK SECERT：是访问服务的安全证书，不要给第三方。

第二步：集成 SDK

FinClip 小程序 SDK 目前支持pod集成或者手动集成。此次操作仅介绍pod集成方式。更多详细内容可以查看官方文档。

2.1安装pod环境

Cocoapods 提供了一个非常简单的依赖管理系统，避免手动导入产生的错误，非常方便。官方安装指南（英文） (opens new window)或CocoaPods安装教程（中文） (opens new window)。

sudo gem install cocoapods
pod setup

2.2 创建Podfile文件

如果你不需要使用扩展 SDK，那么在podfile中只依赖FinApplet.framework即可。如果你需要使用扩展 SDK 中的 API，那么你还需要依赖FinAppletExt.framework.

注意：从2.8.5版本开始，FinClip 小程序 SDK 拆分为多个SDK：FinApplet（核心SDK）、FinAppletExt、FinAppletBDMap、FinAppletGDMap、FinAppletWebRTC、FinAppletBLE、FinAppletAgoraRTC、FinAppletContact、FinAppletClipBoard、FinAppletWXExt。

其中只有FinApplet是必须的，其他扩展 SDK 可根据实际情况选择集成。

2.3 安装或更新依赖

然后，执行 pod update 或者 pod install 即可。

2.4 打开工程

执行完 pod update 或者 pod install ，打开工程目录，找到xxx.xcworkspace文件，双击打开即可。

3. 增加权限描述

根据您的实际需求，集成响应的SDK，并在工程info.plist文件中增加权限配置

如果您集成所有的 SDK，那么需要配置的权限包括：相册、相机、麦克风、位置、蓝牙、通讯录。这些权限，全都是调用相应的api和组件时才会触发。

第三步：添加SDK头文件

在需要使用 FinClip 小程序 SDK 的地方，添加如下代码：

#import <FinApplet/FinApplet.h>

如果还集成了扩展 SDK，那么调用扩展 SDK 中的 api，还需要加上下面的代码：

#import  <FinAppletExt/FinAppletExt.h>

当然，最方便的方式是在 pch 文件中添加以上代码，这样在使用的地方就不用再引用了。

第四步：初始化 SDK

在工程的AppDelegate中的以下方法中，调用 SDK 的初始化方法。

NSString *plistPath = [[NSBundle mainBundle] pathForResource:@"servers" ofType:@"plist"];
NSArray *array = [NSArray arrayWithContentsOfFile:plistPath];
NSMutableArray *storeArrayM = [NSMutableArray array];
for (NSDictionary *dict in array) {
    FATStoreConfig *storeConfig = [[FATStoreConfig alloc] init];
    storeConfig.sdkKey = dict[@"sdkKey"];
    storeConfig.sdkSecret = dict[@"sdkSecret"];
    storeConfig.apiServer = dict[@"apiServer"];
    storeConfig.apmServer = dict[@"apmServer"];
    if ([@"SM" isEqualToString:dict[@"cryptType"]]) {
        storeConfig.cryptType = FATApiCryptTypeSM;
    } else {
        storeConfig.cryptType = FATApiCryptTypeMD5;
    }
    
    [storeArrayM addObject:storeConfig];
}
FATConfig *config = [FATConfig configWithStoreConfigs:storeArrayM];
[[FATClient sharedClient] initWithConfig:config error:nil];

本次测试需要使用微信的登录，获取用户信息等能力，因此需要进行初始化注册组件。

// 准备扩展api
[[FATExtClient sharedClient] fat_prepareExtensionApis];

并在AppDelegate.m中增加下面的代码。

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    /*  微信登录和分享    */
    if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
        return YES;
    }
    return YES;
}

// iOS 9.0 之前
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
    /*  微信登录和分享    */
    // `WeChatHandleURLDelegate ` 为 `WXApiDelegate`代理文件
    if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
        return YES;
    }
    return YES;
}

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{
    /*  微信登录和分享    */
    if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
        return YES;
    }
    return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
  return [WXApi handleOpenUniversalLink:userActivity delegate:[FATWXApiManager sharedManager]];
}

第五步、handleOpenURL处理

一般来说小游戏都需要支持外部通过链接打开，便于分享。则需要做如下处理。

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
    if ([[FATClient sharedClient] handleOpenURL:url]) {
        return YES;
    }
    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    if ([[FATClient sharedClient] handleOpenURL:url]) {
        return YES;
    }
    return YES;
}

第六步、打开小程序

FATAppletRequest *request = [[FATAppletRequest alloc] init];
request.appletId = @"小程序id";
request.apiServer = @"服务器地址";
request.transitionStyle = FATTranstionStyleUp;
request.startParams = startParams;
    
[[FATClient sharedClient] startAppletWithRequest:request InParentViewController:self completion:^(BOOL result, FATError *error) {
    NSLog(@"打开小程序:%@", error);
} closeCompletion:^{
    NSLog(@"关闭小程序");
}];

其他关于 FinClip 小程序 SDK 的 API介绍，请查看 API 说明文档。

打开效果如下：

各位开发者可以上手试试看，有任何问题都可以向官方提出哦！