商业化公共模板使用指南

六安🐟片 · 发表于 2024-10-25 10:42:45

本帖最后由六安🐟片于 2024-12-11 14:07 编辑

12月4日更新
- 新增通行证模块
- 修复商业化模块bug
- 增添了红点逻辑及示例
- 迁移商业化模块至工程公用目录，优化商业化模块接口调用方法

通行证模块

1. 通行证模块内容演示

2. 最新模板下载

IAPTemplate.rar (7.65 MB, 下载次数: 70)

2024-12-11 14:07 上传

点击文件名下载附件

3. 纯净内容包下载

common.rar (187.35 KB, 下载次数: 26)

2024-12-4 19:08 上传

点击文件名下载附件

使用方式：下载解压后，将下方common文件夹下的内容复制到工程common目录中

------------------------------------------------------------
大家好！为了帮助各位开发者更快速地为自己的项目接入商业化，并灵活地为玩家举办各类活动以提升玩家的活跃度，我们为大家准备了一套完整的商业化模板。该模板包含了首充礼包、累充自选商品、试用商品、综合礼包商城、零售商店、充值礼包等多种功能，同时还提供了全套的商业化UI设计供开发者选择使用。大家可以灵活使用（×）魔改（√）模板中的代码及UI来适配自己的项目。

1. 内容演示
首先来看看使用演示：

2. 内容介绍
下图红色框中标注了示例项目中的主要内容：

IAP核心模块
不同IAP功能的UI页面
关联的一些核心工具

此外，项目中也包含CurrencyTempModule和ShopTempModule两个临时模块，由于不同项目中，实现货币和商城的方式各有所不同，所以只做了简单实现。

3.1 IAP核心模块

相关代码：
- IAPProxy.ts 商业化模块代理文件，负责公共模块与游戏自身逻辑的互通。
- IAPData.ts IAP模块数据类，负责记录相关购买行为，活动状态等数据
- IAPModuleC.ts IAP客户端模块，负责关联UI购买交互，客户端与服务器的通信，及物品发放的客户端表现
- IAPModuleS.ts IAP服务端模块，负责处理的订单配送，处理各种相关信息的权威端验证。

3.2 商城大厅页面：
商城大厅页面是一个总的页面，其中有一个大的canvas来方式不同类型活动的子页面。通过tab来切换不同页面的显示。

相关UI：
- MallPanel.ui 大厅页面
- IAPTab.ui 大厅页面切换不同子页面的tab按钮
相关代码：
- MallPanel.ts
- IAPTab.ts

3.3 首充页面：
首充活动页面。当玩家第一次充值后，即可领取对应的奖励。

相关UI：
- FirstRechargePanel.ui 首充页面UI
- FirstRechargeItem.ui 首充页面中物品对象UI
相关代码：
- FirstRechargePanel.ts

3.4 累充页面：
当玩家累计充值达到指定数额时，即可从指定的奖励中多选一领取一个。

相关UI：
- AddRechargePanel.ui 累充页面UI
- AddRechargeItemUI.ui 累充页面中物品对象UI
相关代码：
- TotalRechargeMain.ts

3.5 限时体验页面：
活动期间，玩家可以体验使用指定的几件商品，当达到体验次数时不可再进行体验。可以直接点击对应商品永久购买。

相关UI：
- TrialPanel.ui 限时体验页面UI
- TrialItem.ui 限时体验页面中物品对象UI
相关代码：
- TrialShopMain.ts
- TrialItem.ts

3.6 精选礼包页面：
玩家可以购买对应的礼包。可配置礼包的奖励内容，价格，折扣等。

相关UI：
- GiftPackPanel.ui 礼包页面UI
- GiftPackItem.ui 礼包页面中礼包对象UI
- GiftPackSubItem.ui 礼包页面中礼包中的物品对象UI
相关代码：
- GiftPanel.ts

3.7 零售商店页面：
玩家可以使用派对币/游戏内货币购买对应商品。

相关UI：
- RetailMainPanel.ui 零售商店页面UI
- RetailTab.ui 零售商店页面中的页签对象UI
- ShopItem.ui 零售商店页面中礼包中的商品对象UI
相关代码：
- RetailShopPanel.ts

3.8 充值页面页面：
玩家可以购买对应的货币礼包。可配置礼包的首次购买bonus等。

相关UI：
- CoinPackPanel.ui 充值页面UI
- CoinPackItem.ui 充值页面中不同档位对象UI
相关代码：
- AddCoinPanel.ts

4. 配置方法
该模板中使用到了四个表格来实现礼包，活动，商品的配置。
4.1 CommonGlobal表
全局表，配置了不同活动页面的启用状态，开启/结束时间，活动奖励内容以及其他参数。同时还配置了涉及不同品质商品的底图/颜色配置。

4.2 CommonItem表
物品表，包含了所有货币，资源，商品的基础属性
.jpg

4.3 CommonIapGiftPack
礼包表，共有两个类型，（货币）充值礼包以及综合礼包。可配置礼包的配置，价格，限购数量，刷新周期等属性。

4.4 CommonIapCommodity
商业化商品表，配置了所有需要用派对币直接购买的商品，在此模板中，主要有礼包及一些高级零售商品。分别对应了礼包表及物品表中的对象。
.jpg

如果自身的项目中已经有一些配置表格，不想再新增表格，可以在对应的表格中添加符合以上表格的字段，使得表格导出的配置类型符合模板中定义的接口要求，然后重写CommonConfigProxy中的initCfg()方法，将自己的表格配置文件关联到模块当中。



export class CommonCfgProxy {



    /** 绑定的物品表配置 */

    private static itemConfig: ConfigBase<ICommonItemConfig>;

    /** 绑定的全局表配置 */

    private static globalConfig: ConfigBase<ICommonGlobalConfig>;

    /** 绑定的礼包表配置 */

    private static giftPackConfig: ConfigBase<ICommonIapGiftpackConfig>;

    /** 绑定的付费商品表配置 */

    private static commodityConfig: ConfigBase<ICommonIapCommodityConfig>;

    /** 绑定的通行证配置 */

    private static passConfig: ConfigBase<ICommonPassConfig>;



    /** 初始化配置，如果开发者使用自身的配置表，需要相关配置表中包含对应表格配置的接口，然后在方法内将自己的表格配置关联到相应的配置项上 */

    static initCfg() {

        // TODO 可以重写，关联自身项目的表格配置

        this.itemConfig = GameConfig.CommonItem;

        this.globalConfig = GameConfig.CommonGlobal;

        this.giftPackConfig = GameConfig.CommonIapGiftPack;

        this.commodityConfig = GameConfig.CommonIapCommodity;

        this.passConfig = GameConfig.CommonPasses;

    }

}

5. 相关接口说明
在将模板迁移到自己的项目中时，需要在自身游戏中设置以下回调方法，来实现对应商品及资源的互通。

5.1 设置改变货币回调及获取当前货币数量回调
接口说明：





/**

 * 货币改变的回调方法

 * @param currencyType 货币类型

 * @param num 货币数量

 * @param player 玩家

 * @returns 是否成功

 */

export type ChangeCurrencyCallback = (currencyType: number, num: number, player: Player) => boolean;





/**

 * 获取货币数量回调

 * @param type 货币类型

 * @param player 玩家(服务端设置需传player参数)

 * @returns 数量

 */

export type GetCurrencyNumCallback = (type: number, player?: Player) => number;













export class CommonIAPProxy {



    /**

     * 设置货币改变的回调方法，需要在回调方法中实现货币添加/扣除并返回结果

     * @param callback (currencyType: CurrencyType, num: number, player: Player) => boolean

     * @networkStatus 仅服务端

     */

    public static setChangeCurrencyCallback(callback: ChangeCurrencyCallback);







    /**

     * 设置获取货币数量回调

     * @param callback (itemId: number, player?: Player) => number

     * @networkStatus 客户端设置

     */

    public static setGetCurrencyNumCallback(callback: GetCurrencyNumCallback);

}

使用方式
在自身的项目的货币逻辑初始化时进行设置。



export class CurrencyModuleC extends ModuleC<CurrencyModuleS, CurrencyData> {

    protected onStart(): void {

        CommonIAPProxy.setGetCurrencyNumCallback((type: number) => {

            return this.data.getCurrencyNum(type);

        })





        this.data.onTokenChanged.add(() => {

            CommonIAPProxy.onCurrencyChanged();

        })





}





export class CurrencyModuleS extends ModuleS<CurrencyModuleC, CurrencyData> {



    protected onStart(): void {

        CommonIAPProxy.setChangeCurrencyCallback((type: number, num: number, player: Player) => {

            return this.changeCurrency(type, num, player);

        })

    }

}

5.1 设置改变物品回调、获取当前物品数量回调及物品试用状态改变回调



/**

 * 物品发放的回调方法

 * @param itemId 物品ID

 * @param num 物品数量

 * @param player 玩家

 * @returns 是否成功

 */

export type ChangeItemCallback = (itemId: number, num: number, player: Player) => boolean;





/**

 * 试用状态改变的回调方法

 * @param itemId 物品ID

 * @param state 开始true/结束false

 * @param player 玩家(服务端设置需传player参数)

 */

export type TrialStateChangeCallback = (itemId: number, state: boolean, player?: Player) => void;









/**

 * 获取物品数量回调

 * @param itemId 物品ID

 * @param player 玩家(服务端设置需传player参数)

 * @returns 数量

 */

export type GetItemNumCallback = (itemId: number, player?: Player) => number;



export class CommonIAPProxy {







    /**

     * 设置物品改变的回调方法，需要在回调方法中实现物品发放/扣除并返回结果

     * @param callback (itemId: number, num: number, player: Player) => boolean

     * @networkStatus 仅服务端

     */

    public static setChangeItemCallback(callback: ChangeItemCallback);





    /**

     * 设置获取物品数量回调

     * @param callback (itemId: number, player?: Player) => number

     * @networkStatus 客户端设置

     */

    public static setGetItemNumCallback(callback: GetItemNumCallback);





    /**

     * 设置试用状态改变的回调方法

     * @param callback (itemId: number, state: boolean, player?: Player) => void

     * @networkStatus 可双端设置

     */

    public static setTrialStateChangeCallback(callback: TrialStateChangeCallback)

使用方式
在自身项目的物品逻辑初始化时进行设置。

export class WarehouseModuleC extends ModuleC<WarehouseModuleS, WarehouseData> {



    onStart() {

        CommonIAPProxy.setGetItemNumCallback((itemId: number) => {

            return this.data.getItemNum(itemId);

        })

    }

}



export class WarehouseModuleS extends ModuleS<WarehouseModuleC, WarehouseData> {

    onStart() {

        CommonIAPProxy.setChangeItemCallback((itemId: number, num: number, player: Player) => {

            return this.changeItem(itemId, num, player);

        })

    }

}

5.3 使用通行证时，调用通行证经验增加接口



export class CommonPassProxy {

    /**

     * 添加经验

     * @param exp 

     * @param playerId 

     * @networkStatus 可双端调用



     */

    static addPassExp(exp: number, playerId: number);

}