小游戏发行SDK

@dyminigame_pub/core 是小游戏发布SDK的核心模块，提供了SDK的基础功能、业务模块和API接口。

功能特性

• 单例模式：提供全局唯一的SDK实例
• 配置管理：统一的配置存取接口
• 业务模块：集成公告、兑换码、准入权限等核心业务功能
• 网络请求：封装的HTTP请求工具
• 平台检测：自动识别当前小游戏平台
• 环境标识：支持多环境配置和环境类型检测
• 准入限制：提供用户准入权限验证机制
• 场景上报：支持事件和场景数据上报
• 性能API：提供游戏性能数据采集和上报功能
• 测试API：提供节点查找和操作功能，方便自动化测试

核心概念

1. MinigameSDK

MinigameSDK 是整个模块的核心类，采用单例模式实现，提供SDK初始化和核心功能访问。

2. 业务模块

SDK集成了多个业务模块，包括：

• 公告模块：获取和管理游戏内公告
• 兑换码模块：处理CDKEY兑换功能
• 功能开关模块：游戏内功能/活动模块可用开关控制屏蔽
• 惩罚状态模块：查询用户惩罚状态信息

3. 请求系统

封装了网络请求功能，支持统一的请求配置和响应处理。

响应结构

interface IResponse<T = any> {
  success: boolean; // 请求是否成功
  data?: T; // 响应数据
  message?: string; // 响应消息
  code?: number; // 错误码
  StatusCode?: number; // 服务端返回的业务错误码
  StatusMessage?: string; // 服务端返回的业务错误信息
}

错误码说明

| 错误码 | 类型 | 描述 | |-------|------|------| | 0 | 成功 | 一级错误码为0可以判断为请求成功，直接读取结果进行其他业务逻辑 | | -1 | 网络请求错误 | 检查网络，此时 StatusCode 为网络请求状态码，StatusMessage 为网络请求错误信息 | | -2 | 服务端返回业务错误 | 关注 StatusCode 和 SubMessage | | -3 | 数据解析错误 | SDK 内部错误，关注 StatusCode 联系SDK寻求技术支持 | | -4 | 其他内部错误 | SDK 内部错误，联系SDK寻求技术支持 | | -100 | 初始化错误 | 初始化错误，具体请参考初始化错误码声明部分 |

API 参考

MinigameSDK

export enum EnvType {
  Production = 'production',
  Development = 'development',
  Preview = 'preview',
  Gray = 'gray',
}

export interface InitResult {
  accessible: {
    is_accessible: boolean;
    message?: string;
  }
}

export interface IMinigameSDK {
  onInit(callback: (result: InitResult) => void): void;
  getConfig<T>(key: string): T | undefined;
  setConfig<T>(key: string, value: T): boolean;
  initialize(options: SDKOptions): void;
  Business: {
    announcement: Announcement;
    redeem: Redeem;
    access: Access;
    feature: Feature;
    punishStatus: PunishStatus;
  };
  readonly request: <T>(config: HttpRequestConfig) => Promise<HttpResponse<T>>;
  readonly platform: IPlatform;
  readonly reportService: Report;
  reportAnalytics: IReport['reportAnalytics'];
  reportScene: IReport['reportScene'];
  // 测试API
  testapi: ITestApi;
  // SDK初始化状态
  isInitialized: boolean;
}

/**
 * 抖音小游戏 SDK 初始化配置
 * @param appId - 小游戏ID
 * @param debug - 是否启用调试模式
 * @param reportUrl - 上报接口地址
 * @param x-environment - 环境区分标识
 * @param x-tt-env - 测试环境下的环境变量
 */
export interface SDKOptions {
  appId: string;
  debug?: boolean;
  reportUrl?: string;
  // 环境区分
  'x-environment'?: PlatformEnv;
  // 测试环境下的环境变量
  'x-tt-env'?: string;
  [key: string]: any;
}

主要方法

• initialize(options: SDKOptions)：初始化SDK

  • options.appId：应用ID（必需）
  • options.debug：是否启用调试模式（可选，默认为false）
  • options.reportUrl：上报接口地址（可选）
  • options['x-environment']：环境区分标识（可选）默认值为EnvType.Production（生产环境），可以使用 tt实例动态获取环境类型
  • options['x-tt-env']：测试环境下的环境变量（可选）

• onInit(callback: (result: InitResult) => void)：注册SDK初始化完成回调函数

  • result.accessible.is_accessible：是否拥有准入权限
  • result.accessible.message：准入权限相关消息

• getConfig(key: string): T | undefined：获取配置项

• setConfig(key: string, value: T): boolean：设置配置项

  注意：appId 不能通过此方法修改

• request(config: object): Promise<HttpResponse>：发起网络请求

  • config.url：请求URL（必需）
  • config.header：请求头（可选）
  • config.method：请求方法，可选值：'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS'（可选，默认为'GET'）
  • config.data：请求数据（可选）
  • config.dataType：数据类型（可选）
  • config.responseType：响应类型（可选）
  • config.timeout：超时时间（可选）
  • config.success：成功回调（可选）
  • config.fail：失败回调（可选）
  • config.complete：完成回调（可选）

• reportAnalytics(event: string, data: Record<string, any>): Promise：上报分析事件

• reportScene(options: SceneReportOptions): Promise：上报场景数据

属性

• Business：业务模块集合

  • Business.announcement：公告模块实例
  • Business.redeem：兑换码模块实例
  • Business.access：准入权限模块实例
  • Business.feature：功能开关模块实例
  • Business.punishStatus：惩罚状态模块实例

• platform：平台信息服务

• reportService：上报服务实例

• testapi：测试API服务，提供节点查找和操作功能

testapi API

interface ITestApi {
  // 获取节点映射表
  getNodeMap(): Record<string, any>;
  
  // 根据名称查找节点
  getByName(name: string): ITestApi;
  
  // 触发节点点击事件
  click(): ITestApi;
  
  // 设置节点文本内容
  input(text: string): ITestApi;
}

主要方法

• getNodeMap(): 获取当前场景所有节点的映射表
  • 返回值: 包含节点信息的对象，键为节点名称，值为节点详细信息
• getByName(name: string): 根据节点名称查找节点
  • name: 要查找的节点名称
  • 返回值: 当前ITestApi实例，支持链式调用
• click(): 触发当前选中节点的点击事件
  • 返回值: 当前ITestApi实例，支持链式调用
• input(text: string): 设置当前选中节点的文本内容
  • text: 要设置的文本内容
  • 返回值: 当前ITestApi实例，支持链式调用

使用示例

// 获取所有节点映射表
const nodeMap = SDK.testapi.getNodeMap();
console.log('Node map:', nodeMap);

// 根据名称查找并点击节点
SDK.testapi.getByName('startButton').click();

业务模块API

前置准备

1. 添加服务器域名 请参考 抖音小游戏网络请求，添加服务器域名和下载文件合法域名。

• request合法域名： minigame.zijieapi.com
• downloadFile合法域名： p3-mgame-sign.byteimg.com;p11-mgame-sign.byteimg.com;p26-mgame-sign.byteimg.com

公告模块 (Announcement)

interface IAnnouncement {
  // 获取公告列表
  getAnnouncementList(req: IGetAnnouncementListReq): Promise<publish_operation.QueryAnnouncementListInGameResp>;
  // 标记公告已读
  markAnnouncementRead(req: IMarkAnnouncementReadReq): Promise<publish_operation.ReadAnnouncementResp>;
}

主要方法

• getAnnouncementList(req: IGetAnnouncementListReq)：获取公告列表

  • req.role_id：角色ID
  • req.server_id：服务器ID（可选）
  • req.popup_rule_list：弹窗类型列表（可选）

• markAnnouncementRead(req: IMarkAnnouncementReadReq)：标记公告为已读

  • req.announcement_id：公告ID
  • req.role_id：角色ID

兑换码模块 (Redeem)

interface IRedeem {
  // 使用兑换码
  useCode(req: IUseCodeReq): Promise<publish_marketing.UseCdkeyResponse>;
}

interface IUseCodeReq {
  role_id: string;
  server_id?: string;
  cdkey: string;
}

主要方法

• useCode(req: IUseCodeReq)：使用兑换码

  • req.role_id：角色ID
  • req.server_id：服务器ID（可选）
  • req.cdkey：兑换码

  返回值：包含奖励信息的响应对象

准入权限模块 (Access)

interface IAccess {
  // 查询用户准入权限
  queryUserAccessPolicy(): Promise<{ data?: boolean; message?: string }>;
}

主要方法

• queryUserAccessPolicy()：查询用户准入权限

  • 返回值：包含准入权限信息的对象
    • data：是否拥有准入权限
    • message：准入权限相关消息

  该方法在SDK初始化时会自动调用，结果会通过onInit回调函数返回。

功能开关模块 (Feature)

interface IFeature {
  /**
   * 查询功能是否可用
   * @param featureIds 功能ID列表
   * @returns data 功能状态映射
   * @returns message 信息
   */
  queryFeatureStatus(featureIds: string[]): Promise<{
    success: boolean,
    data?: GameFeatureStatusData,
    message?: string,
    code?: number,
  }>;
}

主要方法

• queryFeatureStatus(featureIds: string[])：查询功能是否可用

  • featureIds：功能ID列表（功能ID由运维平台自行定义）
  • 返回值：包含功能状态信息的对象
    • success：查询是否成功
    • data：功能状态映射，键为功能ID，值为功能状态
    • message：查询结果消息
    • code：错误码

  该方法用于查询游戏内功能/活动模块的可用状态，可根据返回结果控制功能的显示或屏蔽。

惩罚状态模块 (PunishStatus)

interface IPunishStatus {
  // 查询用户惩罚状态
  queryUserPunishStatus(req: IQueryUserPunishStatusReq): Promise<publish_operation.QueryUserPunishStatusResp>;
}

interface IQueryUserPunishStatusReq {
  role_id: string;
  server_id?: string;
  task_type?: string;
}

主要方法

• queryUserPunishStatus(req: IQueryUserPunishStatusReq)：查询用户惩罚状态

  • req.role_id：角色ID
  • req.server_id：服务器ID（可选）
  • req.task_type：任务类型（可选）

  返回值：包含用户惩罚状态信息的响应对象

使用示例

安装

npm install @dyminigame_pub/core

基本用法

入口场景初始化时，需要先调用 initialize 方法初始化 SDK。

import SDK from '@dyminigame_pub/core';
import { EnvType, PlatformEnv } from '@dyminigame_pub/core';

// 先监听初始化完成事件
SDK.onInit((result) => {
  console.log('SDK initialized successfully!');
  console.log('Access status:', result.accessible.is_accessible);
  if (!result.accessible.is_accessible) {
    console.log('Access denied:', result.accessible.message);
  }
});

// 然后初始化 SDK
SDK.initialize({
  appId: 'your-app-id',
  debug: true,
  'x-environment': PlatformEnv.Test,
  'x-tt-env': 'ppe_mg_publish',
});

// 获取配置
const appId = SDK.getConfig<string>('appId');
console.log('Current appId:', appId);

// 获取准入权限状态
const isAccessible = SDK.getConfig<boolean>('is_accessible');
console.log('Is accessible:', isAccessible);

使用公告模块

// 获取公告列表
const result = await SDK.Business.announcement.getAnnouncementList({
  role_id: 'user-role-id',
  server_id: 'game-server-id', // 可选
  popup_rule_list: [1, 2] // 可选，弹窗类型列表
});

if (result.success) {
  const announcementList = result.data;
  console.log('公告列表:', announcementList);
} else {
  console.error('获取公告失败:', result.message);
}

// 标记公告为已读
const markResult = await SDK.Business.announcement.markAnnouncementRead({
  announcement_id: 'announcement-id',
  role_id: 'user-role-id'
});

if (markResult.success) {
  console.log('公告标记已读成功');
} else {
  console.error('公告标记已读失败:', markResult.message);
}

使用兑换码模块

// 使用兑换码
const result = await SDK.Business.redeem.useCode({
  role_id: 'user-role-id',
  server_id: 'game-server-id', // 可选
  cdkey: 'your-cdkey'
});

// 处理兑换结果
if (result.success) {
  console.log('兑换成功，获得奖励：', result.data?.reward_item_list);
} else {
  console.error('兑换失败:', result.message);
}

使用功能开关模块

// 查询功能是否可用
const featureResult = await SDK.Business.feature.queryFeatureStatus([
  '1001',  // 功能ID由运维平台自行定义
  '1002',
  '1003'   // 活动ID也可作为功能ID使用
]);

if (featureResult.success) {
  const featureStatusMap = featureResult.data || {};
  console.log('功能状态:', featureStatusMap);
  
  // 根据功能状态控制功能的显示或屏蔽
  if (featureStatusMap['1002']) {
    // 功能1可用，显示相关UI
    console.log('功能1可用');
  } else {
    // 功能1不可用，屏蔽相关UI
    console.log('功能1不可用');
  }
  
  if (featureStatusMap['1003']) {
    // 活动1可用，显示活动入口
    console.log('活动1可用');
  } else {
    // 活动1不可用，隐藏活动入口
    console.log('活动1不可用');
  }
} else {
  console.error('查询功能状态失败:', featureResult.message);
  // 处理查询失败的情况，可使用默认状态
}

使用上报功能

// 上报分析事件
await SDK.reportAnalytics('user_login', {
  role_id: 'user-role-id',
  server_id: 'game-server-id'
});

// 上报场景数据
await SDK.reportScene({
  scene_id: 'game_start',
  scene_data: {
    level: 1,
    difficulty: 'easy'
  }
});

使用网络请求

// 发起自定义网络请求
const response = await SDK.request<YourResponseType>({
  url: 'https://api.example.com/data',
  method: 'GET',
  data: {
    page: 1,
    limit: 10
  }
});

console.log('Response data:', response.data);

项目结构

packages/core/src/
├── index.ts          # 主入口文件，导出SDK和核心API
├── business/         # 业务模块实现
│   ├── index.ts
│   ├── operation/    # 运营相关模块
│   │   ├── announcement/  # 公告模块
│   │   ├── access/        # 准入权限模块
│   │   ├── feature/        # 功能开关模块
│   │   └── punishStatus/   # 惩罚状态模块
│   └── marketing/    # 营销相关模块
│       └── redeem/        # 兑换码模块
├── modules/          # 核心模块
│   ├── index.ts
│   ├── logger/       # 日志服务
│   ├── platform/     # 平台相关功能
│   ├── report/       # 上报服务
│   ├── request/      # 网络请求模块
│   ├── perfapi/      # 性能API模块
│   │   ├── cocos/        # Cocos引擎性能API
│   │   ├── laya/         # Laya引擎性能API
│   └── testapi/      # 测试API
│       ├── cocos/        # Cocos引擎测试API
│       └── laya/         # Laya引擎测试API
├── utils/            # 通用工具函数
├── const/            # 常量定义
├── services/         # 业务服务接口定义
│   ├── custom-request.ts  # 自定义请求处理
│   ├── publish_marketing/ # 营销相关服务
│   ├── publish_operation/ # 运营相关服务
│   └── typings/      # 类型定义
├── types/            # 类型定义
└── global.d.ts       # 全局类型声明

安装

npm install @dyminigame_pub/core

注意事项

1. 请确保在使用任何功能前先初始化SDK
2. 上报功能需要配置正确的reportUrl
3. 部分功能可能依赖特定小游戏平台的API支持