本章节为您介绍如何集成云游戏 SDK。

环境要求

• iOS 11.0 及以上系统版本的设备
• 使用 Objective-C 开发语言
• VeGame.framework 为 Dynamic Library，且只支持真机（arm64）运行，不支持模拟器

说明：本文档中涉及编译器的示例图参考 Xcode 13.4 版本。

快速接入

使用 CocoaPods 安装

1. 在工程的 Podfile 中添加 CocoaPods 的 source 源，并依赖 VeGameSDK。

   source 'https://github.com/volcengine/volcengine-specs.git'
   
   platform :ios, '11.0'
   inhibit_all_warnings!
   
   target 'your target' do # 将 your target 替换为你的项目名
   # 默认只引用 Core
   pod 'VeGameSDK', '1.53.0'
   end
   

2. 执行 pod install，完成 SDK 的引入。

权限声明

在 info.plist 文件中配置“相机、麦克风、定位”相关使用权限说明：

接入流程

1. 初始化 VeGameManager 配置。

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
   {
       // 初始化 SDK，设置全局配置信息
       // accountId：火山引擎账号 ID
       // 建议在程序启动的时候调用
       [[VeGameManager sharedInstance] initWithAccountId: accountId]];
   }
   

2. 初始化成功后，调用 - (void)startWithConfig:(VeGameConfigObject *)configObj 接口启动游戏。

   说明

   • 登录火山引擎控制台后，点击页面右上角用户信息，选择 账号 > API访问密钥，获取火山引擎账号对应的原始 Access Key ID（ak）和 Secret Access Key（sk），用于生成临时鉴权密钥。
   • 调用 签发临时 Token 接口，获取用于鉴权的临时密钥。

   // 设置回调代理
   [VeGameManager sharedInstance].delegate = self;
   // 设置容器视图
   [VeGameManager sharedInstance].containerView = self.containerView;
   // 启动云游戏
   VeGameConfigObject *configObj = [VeGameConfigObject new];
   configObj.ak = @"";//鉴权 ak
   configObj.sk = @"";//鉴权 sk
   configObj.token = @"";//鉴权 token
   configObj.userId = @"";// 自定义客户端用户 ID
   configObj.gameId = @"";// 游戏 ID
   configObj.roundId = @"";// 自定义游戏生命周期标识
   [[VeGameManager sharedInstance] startWithConfig: configObj];
   

   VeGameConfigObject 配置参数如下：

   参数	类型	是否必填	描述
   ak	NSString	是	用于用户鉴权的临时 Access Key，需通过调用服务端 STSToken 接口 获取
   sk	NSString	是	用于用户鉴权的临时 Secret Key，需通过调用服务端 STSToken 接口 获取
   token	NSString	是	用于用户鉴权的临时 Token，需通过调用服务端 STSToken 接口 获取
   userId	NSString	是	自定义客户端用户 ID，用于标识用户在流媒体房间中的身份
   roundId	NSString	是	当次游戏生命周期的标识符，可以使用该参数查询游戏使用时长，命名规则如下： 最大长度为128位的非空字符串，支持的字符集范围为: 大写字母 A ~ Z 小写字母 a ~ z 数字 0 ~ 9 下划线 "_", 减号 "-"
   gameId	NSString	是	待启动的游戏 ID，通过火山引擎云游戏控制台 游戏管理 页面获取 当传入 customGameId 时，可不传入（以 gameId 优先）
   customGameId	NSString	是	注册游戏时指定的用户自定义游戏 ID 当传入 gameId 时，可不传入
   planId	NSString	否	火山侧套餐 ID，可通过调用服务端 ListResourceSet 接口获取（configuration_code 字段）
   reservedId	NSString	否	资源预锁定 ID，通过调用服务端 PreAllocateResource 接口获取（如不传入，将在开始播放成功回调中返回）
   control	VeGameControlObject	否	游戏支持控制权转移功能；详细参数配置，参考以下 游戏控制权转移参数
   videoStreamProfileId	NSInteger	否	游戏视频流清晰度 ID；如不传入，则使用默认清晰度。清晰度档位 ID 列表和详细说明，参考清晰度档位说明。 注意：如果启动游戏时使用的资源套餐为 “基础型”，视频流清晰度档位将默认设置为 “1”（720P，4000kbps，30FPS）。
   autoRecycleTime	NSInteger	否	设置无操作自动回收服务时长，单位秒（如不设置或设置为0，则使用默认时长）
   userProfilePathList	NSArray<NSString>	否	保存用户游戏配置文件的路径列表
   userTag	NSString	否	用户标签，由业务方指定，可通过调用服务端 CreateUserTag 接口创建，参考 创建用户属性
   keyboardEnable	BOOL	否	是否允许用户使用键盘进行信息输入，默认：YES
   sessionMode	VeBaseSessionMode	否	启动游戏模式： 0（普通模式，默认） 1（挂机模式） 说明：当开启多人游戏时，仅操作者可以设置挂机模式
   queuePriority	NSInteger	否	设置游戏玩家排队功能： 0：不设置排队功能 1~99：队列优先级，数值越小优先级越高
   disableTouchEvent	BOOL		（仅支持端游）是否禁止 SDK 将触控操作事件发送到云端游戏： NO（默认，发送触控事件，详细参数配置，参考以下 触控操作参数） YES（将会收到 gameManager:onTouchEvent 回调，可根据游戏场景调用 sendMouseData 接口发送鼠标事件）
   extraDict	NSDictionary	否	根据业务需要，自定义的扩展参数；详细信息，参考 自定义扩展参数列表

   参考示例：

   // 配置选项
   @interface VeGameConfigObject : NSObject
   
   /**--------------------------必选参数----------------------------------*/
   /** 鉴权参数 */
   @property (nonatomic, copy) NSString *ak;
   /** 鉴权参数 */
   @property (nonatomic, copy) NSString *sk;
   /** 鉴权参数 */
   @property (nonatomic, copy) NSString *token;
   /** 自定义客户端用户 ID */
   @property (nonatomic, copy) NSString *userId;
   /** 游戏 ID（当传入 customGameId 时，可不传入，以 gameId 优先）*/
   @property (nonatomic, copy) NSString *gameId;
   /** 用户自定义游戏 ID（当传入 gameId 时，可不传入）*/
   @property (nonatomic, copy) NSString *customGameId;
   /** 游戏标识，非空字符串 */
   @property (nonatomic, copy) NSString *roundId;
   
   /**--------------------------可选参数----------------------------------*/
   /** 火山侧套餐 ID */
   @property (nonatomic, copy) NSString *planId;
   /** 资源预锁定 ID */
   @property (nonatomic, copy) NSString *reservedId;
   /** 支持游戏控制权转移 */
   @property (nonatomic, strong) VeGameControlObject *control;
   /** 清晰度 ID，不传使用默认档位 */
   @property (nonatomic, assign) NSInteger videoStreamProfileId;
   /** 无操作自动回收服务时长 */
   @property (nonatomic, assign) NSInteger autoRecycleTime;
   /** 保存用户游戏配置文件的路径列表 */
   @property (nonatomic, strong) NSArray<NSString *> *userProfilePathList;
   /** 用户标签，业务方指定 */
   @property (nonatomic, copy) NSString *userTag;
   /** 键盘开关，默认：YES */
   @property (nonatomic, assign) BOOL keyboardEnable;
   /** 启动游戏模式（仅支持手游，默认：VeBaseSessionModeNormal） */
   @property (nonatomic, assign) VeBaseSessionMode sessionMode;
   /** 排队优先级（默认值：0，不参与排队，范围 0 ～ 99，数值越小，优先级越高） */
   @property (nonatomic, assign) NSInteger queuePriority;
   /** 是否禁止 SDK 将触控操作事件发送到云端游戏（仅支持端游，默认：NO） */
   @property (nonatomic, assign) BOOL disableTouchEvent;
   /** 根据业务需要，自定义附加参数 */
   @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extraDict;
   
   @end
   

   游戏控制权转移参数

   VeGameControlObject 配置参数如下：

   参数	类型	是否必填	描述
   role	VeBaseRoleType	是	当前用户进入游戏的默认角色，可选项： 0：观看者，默认 1：操作者 说明：指定 roomType 和该参数后，可在游戏中调用 changeRole 接口将观看者设置为操作者，转移游戏控制权。进入游戏的观看者也会占用实例资源，建议控制观看者数量。
   roomType	VeBaseRoomType	是	游戏房间类型，可选项： 0：单人控制单人观看，默认 1：单人控制多人观看，不可转移游戏控制权 2：单人控制多人观看，可转移游戏控制权

   @interface VeGameControlObject : NSObject
   /**
   * 用户进入游戏的角色
   * 默认：VeBaseRoleTypePlayer
   */
   @property (nonatomic, assign) VeBaseRoleType role;
   /**
   * 游戏房间类型
   * 默认：VeBaseRoomTypeDefault
   */
   @property (nonatomic, assign) VeBaseRoomType roomType;
   
   @end
   

3. 实现相关回调。

   #pragma mark - VeGameManagerDelegate
   - (void)firstRemoteAudioFrameArrivedFromGameManager:(VeGameManager *)manager
   {
       NSLog(@"--- 首帧音频到达 ---");
   }
   
   - (void)firstRemoteVideoFrameArrivedFromGameManager:(VeGameManager *)manager
   {
       NSLog(@"--- 首帧视频到达 ---");
   }
   
   - (void)gameManager:(VeGameManager *)manager startSucceedResult:(NSString *)gameId videoStreamProfileId:(NSInteger)streamProfileId reservedId:(NSString *)reservedId planId:(NSString *)planId extra:(NSDictionary *)extra
   {
       // 启动成功，收到首帧画面回调
   }
   
   - (void)gameManager:(VeGameManager *)manager changedDeviceRotation:(NSInteger)rotation
   {
       // 横竖屏方向回调，注意：VeGameSDK只负责游戏横竖屏方向回调，不负责横竖屏的旋转，接入方根据rotation自行处理
   }
   
   - (void)gameManager:(VeGameManager *)manager onWarning:(VeGameWarningCode)warnCode
   {
       // 警告回调
   }
   
   - (void)gameManager:(VeGameManager *)manager onError:(VeGameErrorCode)errCode
   {
       // 错误回调
   }
   

4. 回调代理、容器视图、游戏手柄赋值。

   /**
   * 回调代理
   */
   @property (nonatomic, weak) id<VeGameManagerDelegate>delegate;
   /**
   * 容器视图，业务方自定义
   */
   @property (nonatomic, strong) UIView *containerView;
   /**
   * 设置“游戏手柄”
   */
   @property (nonatomic, strong) UIView *gamePadView;
   

5. 订阅音视频流。

   在调用 startWithConfig: 启动游戏之前，指定启动游戏时拉取音视频流类型（如不指定，则正常拉取音视频流）：

   • VeBaseStreamTypeVideo（仅拉取视频流，不拉取音频流）
   • VeBaseStreamTypeAudio（仅拉取音频流，不拉取视频流）
   • VeBaseStreamTypeBoth（启动后正常拉取音视频流，默认）

   /**
   * 设置“媒体流”订阅类型
   * 默认：VeBaseStreamTypeBoth
   * 在调用 startWithConfig: 之前设置，不支持拉流过程中修改
   * 收到首帧之后，可通过调用 muteAudio:、muteVideo:、switchPaused: 接口恢复
   */
   @property (nonatomic, assign) VeBaseStreamType streamType;
   

6. 结束时，调用 - (void)stop 接口结束游戏。

   [[VeGameManager sharedInstance] stop];
   

错误码

初始化和启动游戏可能返回的错误码和相关说明如下：