245 lines
9.4 KiB
Markdown
245 lines
9.4 KiB
Markdown
# 项目发布设置使用说明
|
||
|
||
---
|
||
|
||
此文档旨在帮助用户顺利的完成项目打包发布，解决发布过程中可能遇到的问题，并最终完成发布工程的个性化配置和功能接入，文档分为以下几个部分：
|
||
|
||
> * 发布设置前的准备工作
|
||
> * 项目发布配置
|
||
> * 发布工程的个性化配置
|
||
> * JS和原生的通信接入
|
||
> * 运行时error事件和state事件处理方法
|
||
> * 添加loading界面
|
||
|
||
---
|
||
|
||
## 发布设置前的准备工作
|
||
|
||
- 安装最新版本的launcher
|
||
- 确认引擎版本
|
||
- 下载的引擎版本必须为***5.1.6及以上***
|
||
- 在launcher中的引擎页选择下载
|
||
- 安装Xcode
|
||
- 建议版本: 8.3或以上
|
||
- 后续需要在Xcode中完成发布项目的修改和功能接入
|
||
|
||
---
|
||
|
||
## 项目发布配置
|
||
|
||
### 1. 创建项目
|
||
|
||
- launcher项目页中，点击创建项目，填入项目名称，并选择引擎版本为5.1.6（或以上），点击创建按钮。
|
||
|
||
>此文档不涉及具体项目功能，可以关闭 Egret Wing窗口。
|
||
|
||
### 2. 发布配置
|
||
|
||
- 在launcher的项目页中找到新创建的项目，点击该项目下的发布设置按钮。
|
||
|
||
- 点击左侧的iOS按钮，然后在右侧页面中，输入应用名称，填写新的应用包名，点击确定。
|
||
- 新弹出的窗口中选择点击***打开文件夹***按钮。
|
||
|
||
---
|
||
|
||
## 发布工程的个性化配置
|
||
|
||
- 解决国行手机首次启动需要请求网络权限的问题
|
||
- 模版中通过`[_native setNetworkStatusChangeCallback:]`监听网络状态，有网络连接时才启动游戏。
|
||
|
||
- 访问相册权限的问题
|
||
- 为了支持保存截图到本地的功能，模版中默认注册了访问相册的权限，如不需要可以从info.plist中删除。
|
||
- 模版中默认加入的权限并无对应的文字，若要发布至AppStore中，必须在权限后添加任意提醒用户的文字才能通过审核，如“允许Egret Native访问您的相册？”
|
||
|
||
|
||
> - Privacy - Photo Library Usage Description是IOS11.0版本之前的相册读写权限
|
||
> - Privacy - Photo Library Additions Usage Description是IOS11.0版本之后的相册写权限，读权限系统已经默认开放
|
||
|
||
- 没加文字之前与添加文字之后
|
||
|
||
 
|
||
 
|
||
|
||
- 个性化设置
|
||
- 修改游戏地址：将函数`[native startGame:]`的参数替换为当前游戏的地址。
|
||
|
||
>需要注意，如果工程的assets目录下存在game文件，那么此处填写的游戏必须和game文件中的游戏保持一致，否则会出现问题。
|
||
|
||
- 控制FPS面板的显示：修改`_native.config.showFPS = true/false;`。true为显示，false为隐藏。
|
||
- 控制log在屏幕上的显示时间：修改`_native.config.fpsLogTime = 30;`，改为`-1`时是永久显示。
|
||
- 是否禁用核心渲染驱动：修改`_native.config.disableNativeRender = false/true`。false为启用核心渲染驱动，true为禁用核心渲染驱动。
|
||
- 是否清理缓存：修改`_native.config.clearCache = false/true;`。false为不自动清理缓存，true为自动清理缓存。
|
||
- 控制页面超时时间：修改`_native.config.loadingTimeout = 0;`。单位为秒，0为不设置超时。
|
||
- 游戏是否支持刘海屏显示：修改`_native.config.useCutout = false;`。true 为游戏支持并适配，false为不支持。
|
||
|
||
---
|
||
|
||
## JS和原生的通信接入
|
||
|
||
### 1. 原生部分
|
||
- 在AppDelegate.mm的`setExternalInterfaces`方法里配置通信接口
|
||
- `[_native setExternalInterface: Callback:]` 注册JS中可以调用的原生函数
|
||
- `[_native callExternalInterface: Value:]`调用JS函数
|
||
- `setExternalInterface`方法的第一个参数是JS中调用原生函数的函数名，第二个参数是该原生函数的功能实现
|
||
- `callExternalInterface`方法的第一个参数是JS函数的函数名，第二个传入的参数
|
||
|
||
```objective-c
|
||
- (void)setExternalInterfaces {
|
||
__block EgretNativeIOS* support = _native;
|
||
[_native setExternalInterface:@"sendToNative" Callback:^(NSString* message) {
|
||
NSString* str = @"Native get message: ";
|
||
str = [str stringByAppendingString:message];
|
||
NSLog(@"%@", str);
|
||
[support callExternalInterface:@"sendToJS" Value:str];
|
||
}];
|
||
}
|
||
```
|
||
|
||
### 2. JS部分
|
||
|
||
- `egret.ExternalInterface.call`调用注册过的原生函数
|
||
|
||
```js
|
||
egret.ExternalInterface.call("sendToNative", "message from JS");
|
||
```
|
||
|
||
- `egret.ExternalInterface.addCallback`注册原生中可以调用的JS函数
|
||
|
||
```js
|
||
function sendToJS(msg) {
|
||
console.log(msg);
|
||
}
|
||
egret.ExternalInterface.addCallback("sendToJS", sendToJS);
|
||
```
|
||
|
||
> 只有通过`setExternalInterface`注册的原生函数，才能在JS中通过`call`调用。
|
||
> 只有通过`addCallback`注册的JS函数，才能在原生中通过`callExternalInterface`调用。
|
||
|
||
---
|
||
|
||
## runtime阶段状态定义
|
||
|
||
- 我们将runtime启动及运行的阶段进行了定义，主要分为如下几种阶段状态：
|
||
|
||
> * loading: 系统初始时的默认状态
|
||
> * starting: 表示index.html已经加载成功
|
||
> * running: 表示starting状态后，执行完json、js等文件资源加载并开始执行渲染
|
||
|
||
## 运行时state事件处理方法
|
||
|
||
### 1. runtime运行中各个事件的说明
|
||
- 事件说明如下
|
||
|
||
|事件类型 |事件消息 |所属阶段 |事件意义 |
|
||
|:-------------|----------------------------|:-----------------|:-----------------------------------------------------------------------------------------|
|
||
|@onState |{"state”:”starting”} |loading到starting |index.html加载成功 |
|
||
|@onState |{"state”:”running”} |starting到running |starting状态后开始执行渲染(注：starting状态后，若json或js等文件加载失败，会通过具体的js错误进行提示) |
|
||
|
||
### 2. 监听state事件的方法
|
||
|
||
- 注册对state事件的监听，在函数`setExternalInterfaces`中：
|
||
|
||
```objective-c
|
||
- (void)setExternalInterfaces {
|
||
__block EgretNativeIOS* support = _native;
|
||
__block AppDelegate* thiz = self;
|
||
|
||
[_native setExternalInterface:@"@onState" Callback:^(NSString* message) {
|
||
NSData* jsonData = [message dataUsingEncoding:NSUTF8StringEncoding];
|
||
NSError* err;
|
||
NSDictionary* dic = [NSJSONSerialization JSONObjectWithData:jsonData
|
||
options:NSJSONReadingMutableContainers
|
||
error:&err];
|
||
if (err) {
|
||
NSLog(@"onState message failed to analyze");
|
||
return;
|
||
}
|
||
|
||
NSString* state = [dic objectForKey:@"state"];
|
||
if ([state isEqualToString:@"starting"]) {// 正在启动引擎
|
||
NSLog(@"Engine starting");
|
||
} else if ([state isEqualToString:@"running"]) {// 引擎开始渲染
|
||
// 如果您使用了自定义闪屏，这里是关掉的好时机
|
||
NSLog(@"Engine is rendering");
|
||
}
|
||
NSLog(@"Native get onState message: %@", state);
|
||
}];
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 处理错误
|
||
|
||
如果您需要处理错误，请参照 [Egret Native 上处理游戏错误](https://docs.egret.com/native/docs/manual/abouterrors)。
|
||
|
||
---
|
||
|
||
## 添加loading界面
|
||
|
||
>loading界面的使用依赖与state事件的处理，请先完成上一部分的阅读。
|
||
|
||
### 1. 打开loading界面
|
||
|
||
- 在AppDelegate的didFinishLaunchingWithOptions函数中调用函数showLoadingView
|
||
|
||
```objective-c
|
||
@implementation AppDelegate {
|
||
UIViewController* _viewController;
|
||
UIImageView* _imageView;
|
||
}
|
||
|
||
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
|
||
// Override point for customization after application launch.
|
||
NSString* gameUrl = @"http://tool.egret-labs.org/Weiduan/game/index.html";
|
||
|
||
_native = [[EgretNativeIOS alloc] init];
|
||
_native.config.showFPS = true;
|
||
_native.config.fpsLogTime = 30;
|
||
_native.config.disableNativeRender = false;
|
||
_native.config.clearCache = false;
|
||
|
||
_viewController = [[ViewController alloc] initWithEAGLView:[_native createEAGLView]];
|
||
if (![_native initWithViewController:_viewController]) {
|
||
return false;
|
||
}
|
||
[self setExternalInterfaces];
|
||
|
||
NSString* networkState = [_native getNetworkState];
|
||
if ([networkState isEqualToString:@"NotReachable"]) {
|
||
__block EgretNativeIOS* native = _native;
|
||
[_native setNetworkStatusChangeCallback:^(NSString* state) {
|
||
if (![state isEqualToString:@"NotReachable"]) {
|
||
dispatch_async(dispatch_get_main_queue(), ^{
|
||
[native startGame:gameUrl];
|
||
});
|
||
}
|
||
}];
|
||
return true;
|
||
}
|
||
|
||
[_native startGame:gameUrl];
|
||
|
||
[self showLoadingView];
|
||
|
||
return true;
|
||
}
|
||
|
||
- (void)showLoadingView {
|
||
_imageView = [[UIImageView alloc] initWithFrame:_viewController.view.frame];
|
||
[_imageView setImage:[UIImage imageNamed:@"icon"]];
|
||
[_viewController.view addSubview:_imageView];
|
||
[_viewController.view bringSubviewToFront:_imageView];
|
||
}
|
||
```
|
||
|
||
### 2. 关闭loading界面
|
||
|
||
- 收到{"state”:”running”}消息后，调用函数hideLoadingView
|
||
|
||
```objective-c
|
||
- (void)hideLoadingView {
|
||
[_imageView removeFromSuperview];
|
||
}
|
||
```
|