diff --git a/Design/FileCache.md b/Design/FileCache.md index ff758e7a6a6a30d01d65ada801898a65836b7181..c4c084f67fe0ff46773185c4b5ffd82b0eac89f3 100644 --- a/Design/FileCache.md +++ b/Design/FileCache.md @@ -1,6 +1,17 @@ -# 资源缓存与淘汰 +# 资源缓存 -## 哪些资源会自动缓存？ + + +## 一、什么情况触发资源缓存 +当使用以下API发起网络请求时会检查是否需要缓存 +- UnityWebRequest +- WWW +- UnityWebRequestAssetBundle +- Addressables + +**游戏业务侧无需关心资源是否有缓存，正常调用API即可，当有缓存时，Loader插件会构造正常响应返回给游戏** + +## 二、哪些资源会自动缓存？ - wasm主包/分包，即`wasm.code.unityweb`文件 - 首包资源，即`webgl.data.unityweb`文件 - 预加载的文件 @@ -17,25 +28,16 @@ texturesPath: 纹理存放路径 texturesHashLength: 纹理中hash长度 ``` -### unity-namespace.js配置 -```js -bundlePathIdentifier: [$BUNDLE_PATH_IDENTIFIER], // 判定为下载bundle的路径标识符，此路径下的下载，会自动缓存 -excludeFileExtensions: [$EXCLUDE_FILE_EXTENSIONS], // 命中路径标识符的情况下，并不是所有文件都有必要缓存，过滤下不需要缓存的文件拓展名 -texturesHashLength: $TEXTURE_HASH_LENGTH, // 纹理中的hash长度 -texturesPath: '$TEXTURES_PATH', // 纹理存放路径 -needCacheTextures: $NEED_CACHE_TEXTURES, // 是否需要缓存纹理 -``` - -## 缓存规则 -> 适用于预加载的文件和URL中包含StreamingAssets的文件 +## 三、缓存规则 +> 适用于预加载的文件和URL中包含`bundlePathIdentifier`的文件 在写入缓存前需要经过三步 1. 根据URL生成缓存路径 URL剔除掉DATA_CDN部分后作为缓存路径 例如： -DATA_CDN=https://weixin.qq.com -请求路径=https://weixin.qq.com/StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e -则缓存路径=StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e +- DATA_CDN=https://weixin.qq.com +- 请求路径=https://weixin.qq.com/StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e +- 则缓存路径=StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e 2. 清理掉同名旧文件 通过文件名中的hash区分同名文件的不同版本 继续上面的例子，假如本地已经有`StreamingAssets/textures_cdb8b726f0afb1e8d265a9dfd6cb7669` @@ -45,24 +47,14 @@ DATA_CDN=https://weixin.qq.com ``` bundleHashLength: bundle中hash的长度 ``` - -unity-namespace.js配置 -``` -bundleHashLength: $BUNDLE_HASH_LENGTH, // 自定义bundle中的hash长度 -``` 3. 检查存储空间是否足够，是否需要清理 当已有缓存+待写入缓存超过允许的上限时，按照LRU清理出所需大小 转换插件相关配置 ``` -defaultReleaseSize: 清理时，默认额外清理的大小 -``` - -unity-namespace.js配置 -``` -releaseMemorySize: $DEFAULT_RELEASE_SIZE, // 单位Bytes, 1MB = 1024 KB = 1024*1024Bytes +defaultReleaseSize: 清理时，默认额外清理的大小，单位Bytes，1MB = 1024KB = 1024*1024Bytes ``` -## 注意项 +## 四、注意项 1. 文件名需要带上hash [BuildAssetBundleOptions.AppendHashToAssetBundleName](https://docs.unity3d.com/ScriptReference/BuildAssetBundleOptions.AppendHashToAssetBundleName.html)，以便清理掉该文件的旧缓存。默认32位长度，可通过导出选项中`Bundle名中Hash长度`来自定义。比如游戏自己计算了crc，可将`Bundle名中Hash长度`设置为crc长度。 2. 配置到不自动缓存文件类型中的文件，不会自动缓存，默认值是json，比如addressable打包后生成StreamingAssets/aa/WebGL/catalog.json，这个文件不会自动缓存。 \ No newline at end of file diff --git a/Design/ReportStartupStat.md b/Design/ReportStartupStat.md index cb557f1fdc3c3da017aa4a548448c20c56952858..886db30148374670cee3879f9e2966245de6bc7f 100644 --- a/Design/ReportStartupStat.md +++ b/Design/ReportStartupStat.md @@ -6,9 +6,19 @@ 1. Unity Loader插件自动统计了代码包、首包资源、代码编译、引擎与首场景初始化，无需手动上报 2. 通过C# SDK接口让开发者上报自定义启动阶段，分析每个环节可能存在的流失 +## 二、上报广告信息 +为了帮助开发者分析广告渠道的留存数据，达到最好的买量效果，Loader提供了上报广告参数的能力，用于区分**不同广告位/广告类型/素材类型**的数据。 +#### 如何上报？ +广告买量时，带上广告相关自定义参数，Loader自动上报 +eg: `adSpaceType=1&adType=1&materialType=1` -## 二、上报自定义阶段 +- adSpaceType: 广告位类型；一个广告位可以投放不同类型的广告 +- adType: 广告类型；一个广告类型可以投放不同素材 +- materialType: 素材类型 + + +## 三、上报自定义阶段 为了详细统计玩家的流失情况以便开发者进行优化，我们拆分了三个部分。 其中**自动上报**为Unity Loader自动完成开发者无需关注，但**自定义阶段**与**启动加载完成**需开发者主动调用接口进行上报。详细接口可参考C# SDK中的WX.cs，此处列出关键接口： @@ -51,7 +61,52 @@ errorType取值：[0,10000] WX.ReportGameStart(0, ""); ``` -## 三、获取数据统计 +## 四、获取Loader启动阶段 +从启动时序可以知道Loader启动阶段分为以下五个阶段 +- wasm代码包下载 +- wasm编译 +- 首包资源下载 +- 首包资源读取 +- 引擎初始化(callmain) + +当业务侧需要使用Loader启动数据时，可以使用Loader暴露的进度事件上报到自己的系统 +> tips: 目前只支持js调用 +```js +gameManager.onLaunchProgress = (e) => { + // e: LaunchEvent + // interface LaunchEvent { + // type: LaunchEventType; + // data: { + // costTimeMs: number; // 阶段耗时 + // runTimeMs: number; // 总耗时 + // loadDataPackageFromSubpackage: boolean; // 首包资源是否通过小游戏分包加载 + // isVisible: boolean; // 当前是否处于前台，onShow/onHide + // useCodeSplit: boolean; // 是否使用代码分包 + // isHighPerformance: boolean; // 是否iOS高性能模式 + // }; + // } + if (e.type === launchEventType.launchPlugin) { + + } + if (e.type === launchEventType.loadWasm) { + + } + if (e.type === launchEventType.compileWasm) { + + } + if (e.type === launchEventType.loadAssets) { + + } + if (e.type === launchEventType.readAssets) { + + } + if (e.type === launchEventType.prepareGame) { + + } +} +``` + +## 五、获取数据统计 数据报表包含Unity Loader自动上报与开发者自定义阶段。关注总体流失漏斗以确定需要优化的方向，同时分阶段的耗时分布有利于帮助我们分析该阶段的对应耗时的用户占比。 diff --git a/Design/Transform.md b/Design/Transform.md index 1afedfb0d8720dd906b548a830c4c5a07bdf8e48..b7570876aa9879d1782bd0708c309600cc4f879b 100644 --- a/Design/Transform.md +++ b/Design/Transform.md @@ -38,7 +38,7 @@ 注意： * 项目使用了小游戏Unity适配插件，若小游戏是第一次使用本插件，在开发者工具会报错提示插件未授权，具体可参考[使用Loader进行游游戏加载](UsingLoader.md) -至此，可以在[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)打开转化后的小游戏进行预览。 +至此，可以在[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)导入转换后的`minigame`目录的小游戏工程进行预览。 ## 三、使用脚本集成到自己的构建系统 如果你希望将导出插件集成到自己的发布流程，想脚本调用的话，可修改 `Assets/WX-WASM-SDK/Editor/MiniGameConfig.asset`配置，然后调用WXEditorWindow 的 DoExport方法导出小游戏 @@ -64,7 +64,7 @@ assetLoadType -- 首包资源加载方式 bundleExcludeExtensions -- 不自动缓存文件类型 bundleHashLength -- bundle名中hash长度 // 预下载 -preloadFiles -- 预下载文件列表 +preloadFiles -- 预下载文件列表，用;分隔 // SDK功能 UseFriendRelation -- 使用好友关系链 UseAudioApi -- 使用微信音频API @@ -81,8 +81,8 @@ DeleteStreamingAssets -- DeleteStreamingAssets ``` // 资源加载与缓存 dataFileSubPrefix: 配置首包资源加载路径 -bundlePathIdentifier: URL中包含特定标识符时需要自动缓存 -defaultReleaseSize: 达到缓存上限时默认额外清理的存储大小 +bundlePathIdentifier: URL中包含特定标识符时需要自动缓存，用;分隔 +defaultReleaseSize: 达到缓存上限时默认额外清理的存储大小，用;分隔 needCacheTextures: 是否开启纹理缓存 texturesPath: 纹理存储路径 texturesHashLength: 纹理中hash长度 diff --git a/Design/UsingLoader.md b/Design/UsingLoader.md index d12d0613887d2f6dcec8d0379167c66dec034f90..f0a5ba6da2d8df3f90406b3fa4066873d2d099f3 100644 --- a/Design/UsingLoader.md +++ b/Design/UsingLoader.md @@ -38,14 +38,6 @@ Unity Loader是在微信小游戏环境加载Unity WebGL游戏的加载与适配 CDN: cdn地址 dataFileSubPrefix: 首包资源相对cdn地址的存放目录，默认首包资源放在cdn一级目录 ``` -#### game.js配置 -```js -DATA_CDN: "$DEPLOY_URL", -``` -#### unity-namespace.js配置 -``` -dataFileSubPrefix: '$DATA_FILE_SUB_PREFIX', // DATA_CDN + dataFileSubPrefix + datafilename -``` ### 3.2 启动界面 由于Unity WebGL启动加载需要一定时间，因此需要使用视频或图片等内容作为过渡以留住玩家。Unity Loader默认使用视频+进度信息呈现，开发者可以自定义封面/视频，可参考[启动Loader视频规范](video.md)进行配置。 diff --git a/image/file_cache.png b/image/file_cache.png new file mode 100644 index 0000000000000000000000000000000000000000..f7862d5e547839ee527a497fb5825265b24ce9e8 Binary files /dev/null and b/image/file_cache.png differ