手把手系列:如何将小程序游戏引入自有APP?(iOS篇)

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

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

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

实现效果在自有 App 中实现小程序游戏运行
使用技术FinClip 小程序容器
测试机iOS
测试demo飞机大战小游戏
在 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

完成 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)FinAppletExtFinAppletBDMapFinAppletGDMapFinAppletWebRTCFinAppletBLEFinAppletAgoraRTCFinAppletContactFinAppletClipBoardFinAppletWXExt

其中只有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 说明文档

打开效果如下:

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