iGlees SDK文档

SDK简介

iGlees SDK为Cocos开发者提供了广告、网络请求、加解密、缓存数据等功能，CocosCreator开发者可以使用该SDK提供的功能快速高效的构建游戏。

SDK集成

导入SDK

iGlees SDK的所有功能均放在IG命名空间，然后根据具体的功能模块进行调用。比如IG.IGSdk，IG.HttpWrapper等。使用iGlees SDK前，需要先导入SDK。目前支持两种方式导入，具体如下：

npm方式导入

//在项目根目录使用npm命令安装iGlees SDK（建议使用最新版本）
npm install igsdk@latest --save

//代码中导入SDK使用
import IG from 'igsdk';

手动导入

//1、下载igsdk.js、igsdk.d.ts，将两个文件放入到项目assets目录下的lib目录（具体根据实际情况存放到指定目录），并把igsdk.js设置成插件，并允许web、native、编辑器环境加载

//2、导入SDK，并设置代码提示
import IG from './lib/igsdk.js';
/// <reference path="./lib/igsdk.d.ts" />

初始化SDK

在使用iGlees SDK前，请务必先调用初始化方法完成SDK的初始，具体如下：

/**
* 初始化（注：使用SDK功能前调用，只需要调用一次，建议进入首个场景就调用）
* @param sys 当前系统对象 （CocosCreator<3.0时传cc.sys，CocosCreator>=3.0时传sys）
* @param reflection 反射对象（打包原生平台时需要设置，CocosCreator<=3.5时传jsb.reflection， CocosCreator>=3.6时传native.reflection）
* @param logLevel 日志等级（线上环境设置为LOG_ERROR或OFF）
* @param 是否初始化成功
*/
static init(sys: any, reflection?: any, logLevel?: LOG_LEVEL): boolean;

//初始化SDK
IG.IGSdk.init(sys, sys.isNative ? jsb.reflection : null, IG.LOG_LEVEL.DEBUG);

广告模块

初始化广告SDK

在使用广告模块时，需先初始化广告SDK，具体如下：

/**
* 初始化广告SDK
* @param initOpt 初始化可配置参数
* @param callback 初始化回调
*/
static init(initOpt: ASWInitOpt, callback?: ASWInitCallback): void;
        
//初始化广告SDK
let initOpt = new IG.ASWInitOpt();
initOpt.mediaIdWeb = '11';
initOpt.mediaIdAndroid = '9';
initOpt.mediaIdIOS = '10';
initOpt.mediaId = '11';
initOpt.channel = "";
initOpt.customData = "";
initOpt.showLog = true;
initOpt.test = true;
IG.AdSdkWrapper.init(initOpt, (code, msg) => {
    console.log(`Init sdk : code=${code} , msg=${msg}`);
});

其中，初始化可配参数ASWInitOpt定义如下：

/**
 * 初始化参数
 */
export class ASWInitOpt extends InitOpt {
    //Web端媒体id
    public mediaIdWeb: string;
    //Android端媒体id
    public mediaIdAndroid: string;
    //iOS端媒体id
    public mediaIdIOS: string;
    //鸿蒙端媒体id
    public mediaIdOpenHarmony: string;
}

/**
 * 初始化可配置参数
 */
export class InitOpt {
    //媒体标识（必传）
    public mediaId: string = "";
    //自定义渠道标识。广告数据可以根据自定义渠道进行拆分
    public channel: string = "";
    //自定义数据，最长255字符。激励视频服务端验证时，该数据会回调给服务器
    public customData: string = ""
    // 是否显示日志，默认不显示。线上环境应设置成false
    public showLog: boolean = false;
    //是否打开测试模式。正式上线前请设置为false，否则将不产生收益
    public test: boolean = false;
}

请求广告

/**
* 请求广告
* @param adOpt 请求广告可配置参数
* @param callback 请求广告回调
*/
static requestAd(adOpt: ASWAdOpt, callback?: ASWAdCallback): void;

//请求广告
let adOpt = new IG.ASWAdOpt();
adOpt.adIdWeb = '3';
adOpt.adIdWechatGame = 'adunit-6c232b47c4cc6f9b';
adOpt.adIdAndroid = '37';
adOpt.adType = IG.AD_TYPE.REWARD_VIDEO;
IG.AdSdkWrapper.requestAd(adOpt, {
    onAdReward(adId) {
        console.log(`ad[${adId}] reward.`);
    },
});

其中，请求广告可配置参数ASWAdOpt定义如下：

/**
 * 请求广告参数
 */
export class ASWAdOpt {
    //广告类型（小游戏使用）
    public adType: AD_TYPE;
    //Web端广告位id
    public adIdWeb: string;
    //Android端广告位id
    public adIdAndroid: string;
    //iOS端广告位id
    public adIdIOS: string;
    //鸿蒙端广告位id
    public adIdOpenHarmony: string;
    //微信小游戏端广告位id
    public adIdWechatGame: string;
    //抖音小游戏端广告位id
    public adIdDouYinGame: string;
}

其中，请求广告回调ASWAdCallback定义如下：

/**
 * 请求广告回调接口
 */
export interface ASWAdCallback {
    /**
     * 加载广告成功回调
     * @param adId 广告位id
     */
    onAdLoad?(adId: string): void;

    /**
     * 广告曝光回调
     * @param adId 广告位id
     */
    onAdShow?(adId: string): void;

    /**
     * 广告点击回调（Web平台不一定回调）
     * @param adId 广告位id
     */
    onAdClick?(adId: string): void;

    /**
     * 激励视频可以奖励回调
     * @param adId 广告位id
     */
    onAdReward?(adId: string): void;

    /**
     * 激励视频观看完成回调
     * @param adId 广告位id
     */
    onAdComplete?(adId: string): void;

    /**
     * 广告关闭回调（Web平台不一定回调）
     * @param adId 广告位id
     */
    onAdDismiss?(adId: string): void;

    /**
     * 广告加载失败回调
     * @param adId 广告位id
     * @param code 错误码
     * @param msg 错误消息
     */
    onAdError?(adId: string, code: number, msg: string): void;
}

小游戏模块

小游戏模块所有功能均在MiniGameSdk下，具体功能如下：

授权

/**
* 授权
* @param scope 权限
* @param callback 回调
*/
authorize(scope: string, callback?: MiniGameCallback): void;

登录

/**
* 登录
* @param callback 回调
*/
login(callback?: MiniGameCallback): void;
      
//登录示例：
IG.MiniGameSdk.getInstance()?.login({
    onSuc(res) {
        console.log('login suc.', res);
    },
    onFail(code, msg) {
        console.error('login fail.', code, msg);
    }
});

/**
 * 小游戏回调接口
 */
interface MiniGameCallback {
    /**
     * 成功回调
     * @param res 响应信息
     */
    onSuc(res?: any): void;

    /**
     * 失败回调
     * @param code 错误码
     * @param msg  错误消息
     */
    onFail(code: number, msg: string): void;
}

检查登录态

/**
* 检查登录态 session_key 是否过期
* @param callback 回调
*/
checkSession(callback?: MiniGameCallback): void;
             
//示例：
IG.MiniGameSdk.getInstance()?.checkSession({
    onSuc() {
        console.log('checkSession suc.');
    },
    onFail(code, msg) {
        console.error('checkSession fail.', code, msg);
    }
})            

获取用户信息

/**
* 获取用户信息
* @param nodePosition 节点位置信息
* @param callback 回调
*/
getUserInfo(nodePosition?: MiniGameNodePosition, callback?: MiniGameCallback): void;


//示例：
let interstitialAdNode = find('ButtonLayout/InterstitialAd', this.node);
console.log(interstitialAdNode);
let authUserInfoNodeInfo = this.getNodeInScreenRect(interstitialAdNode);
console.error(authUserInfoNodeInfo);
IG.MiniGameSdk.getInstance()?.getUserInfo(authUserInfoNodeInfo, {
    onSuc(data) {
        console.log('getUserInfo suc.', data);
    },
    onFail(code, msg) {
        console.error('getUserInfo fail.', code, msg);
    },
})

/**
 * 小游戏节点位置信息
 */
export class MiniGameNodePosition {
    //左上角横坐标
    public left: number;
    //左上角纵坐标
    public top: number;
    //宽度
    public width: number;
    //高度
    public height: number;
    //是否调试模式（调试模式会展示获取用户信息按钮）
    public debug: boolean;
}

/**
 * 小游戏用户数据
 */
export class MiniGameUserData {
    //用户昵称
    nick: string;
    //用户头像地址
    avatar: string;
    //包括敏感数据在内的完整用户信息的加密数据
    encryptedData: string;
    //加密算法的初始向量
    iv: string;
}

分享

使用分享时，在iGlees SDK初始化之后，先设置展示分享按钮

//展示分享按钮
IG.MiniGameSdk.getInstance().setShareMenu({
    show: true
});

其中设置分享方法即参数如下：

/**
* 设置分享按钮
* @param shareOpt 分享可配参数
*/
setShareMenu(shareOpt: MiniGameShareOpt): void;

/**
 * 分享可配置参数
 * 参数说明：
 * 图片优先级：imageUrlId+imageUrl > useCanvasImg > 默认
 */
export class MiniGameShareOpt {

    /** 是否展示分享按钮（被动转发分享时设置） */
    public show?: boolean;
    /** 分享标题 */
    public title?: string;
    /** 分享描述（仅抖音小游戏时可用） */
    public desc?: string;
    /** 审核通过的图片ID （抖音小游戏的templateId） */
    public imageUrlId?: string;
    /** 图片地址 */
    public imageUrl?: string;
    /** 是否使用Canvas 内容作为转发图片 （仅微信小游戏时可用） */
    public useCanvasImg?: boolean;
    /** 使用Canvas 内容作为转发图片的可配参数 （仅微信小游戏时可用） */
    public canvasOpt?: MiniGameWxCanvasShareOpt;
    /** 是否使用带 shareTicket 的转发 （仅微信小游戏时可用） */
    public withShareTicket?: false;
    /** 查询字符串，必须是 key1=val1&key2=val2 的格式 */
    public query?: string;
    /** 审核通过的朋友圈预览图图片ID （仅微信小游戏时可用） */
    public imagePreviewUrlId?: string;
    /** 朋友圈预览图链接 （仅微信小游戏时可用） */
    public imagePreviewUrl?: string;
    /** 转发内容类型（仅抖音小游戏时可用） */
    public channel?: string;
}


/**
 * 微信Canvas截图分享可配置参数（仅微信小游戏可用）
 */
export class MiniGameWxCanvasShareOpt {
    /** 截取 canvas 的左上角横坐标 */
    public x?: number;
    /** 截取 canvas 的左上角纵坐标 */
    public y?: number;
    /** 截取 canvas 的宽度 */
    public width?: number;
    /** 截取 canvas 的高度 */
    public height?: number;
    /** 目标文件的宽度，会将截取的部分拉伸或压缩至该数值 */
    public destWidth?: number;
    /** 目标文件的高度，会将截取的部分拉伸或压缩至该数值 */
    public destHeight?: number;
    /** 目标文件的类型：jpg：jpg文件，png：png文件 */
    public fileType?: string;
    /** jpg图片的质量，仅当 fileType 为 jpg 时有效。取值范围为 0.0（最低）- 1.0（最高），不含 0。不在范围内时当作 1.0 */
    public quality?: number;
}

如果需要主动分享，具体调用如下：

/**
* 直接调起分享转发
* @param shareOpt 分享可配参数
*/
shareAppMessage(shareOpt: MiniGameShareOpt): void;


//调用示例：
IG.MiniGameSdk.getInstance().shareAppMessage({
    title: "我就是牌神",
    desc: "十三幺就是爽！",
    imageUrlId: 'testId',
    imageUrl:'testUrl'
});

设置

/**
* 调起客户端小程序设置界面
* @param callback 回调
*/
openSetting(callback: MiniGameCallback): void;

/**
* 获取用户的当前设置
* @param callback 回调
*/
getSetting(callback: MiniGameCallback): void;

游戏圈（微信）

/**
* 创建游戏圈按钮。游戏圈按钮被点击后会跳转到小游戏的游戏圈
* @param clubButtonOpt 游戏圈按钮可配参数
*/
createGameClubButton(clubButtonOpt?: MiniGameClubButtonOpt): any;

                     
/**
 * 戏圈按钮可配参数
 */
export class MiniGameClubButtonOpt extends MiniGameNodePosition {
    //活动页面
    public openlink: string;
    //传递了openlink值时，此字段生效，决定创建的按钮是否需要拥有红点，默认为true
    public hasRedDot?: boolean;
}

客服

/**
* 打开客服
* @param openCustomerServiceOpt 客服可配参数
* @param callback 回调
*/
openCustomerService(openCustomerServiceOpt?: MiniGameOpenCustomerServiceOpt, callback?: MiniGameCallback): void;


/**
 * 打开客服可配参数
 */
export class MiniGameOpenCustomerServiceOpt {
    //抖音客服类型。1：小 6 客服，2：抖音IM 客服（仅支持抖音），3：抖音客服平台（基础库 3.41.0 开始支持）
    public type?: number;
    //微信客服链接
    public url?: string;
    //微信客服企业ID
    public corpId?: string;
}

选择媒体文件

/**
* 选择媒体文件
* @param chooseMediaOpt 选择媒体文件可配参数
* @param callback 回调
*/
chooseMedia(chooseMediaOpt?: MiniGameChooseMediaOpt, callback?: MiniGameCallback): void;


/**
 * 媒体类型
 */
export enum MEDIA_TYPE {
    /** 图片 */
    IMAGE = 'image',
    /** 视频 */
    VIDEO = 'video',
    /** 可同时选择图片和视频 */
    MIX = 'mix'
}

/**
 * 来源类型
 */
export enum SOURCE_TYPE {
    /** 从相册选择 */
    ALBUM = 'album',
    /** 使用相机拍摄 */
    CAMERA = 'camera',
}

/**
 * 相机类型
 */
export enum CAMERA_TYPE {
    /** 使用后置摄像头 */
    BACK = 'back',
    /** 使用前置摄像头 */
    FRONT = 'front',
}

/**
 * 选择媒体文件可配参数
 */
export class MiniGameChooseMediaOpt {
    /** 最多可以选择的数量 */
    public count?: number;
    /** 媒体类型 */
    public mediaType: MEDIA_TYPE;
    /** 来源类型 */
    public sourceType: SOURCE_TYPE;
    /** 拍摄视频最长拍摄时间 */
    public maxDuration?: number;
    /** 仅在 sourceType 为 camera 时生效，使用前置或后置摄像头 */
    public camera?: CAMERA_TYPE;
}

网络请求模块

设置HTTP请求配置

/**
* 设置Http请求配置（请求之前设置）
* @param httpConfig Http请求配置
*/
static setConfig(httpConfig: HttpWrapperConfig): void;

//构建HTTP请求配置
let httpConfig = new IG.HttpWrapperConfig();
httpConfig.baseUrl = 'https://rx.dijikj.com/flkapi/';
httpConfig.version = '1.1.1';
httpConfig.channel = 'officail';
//设置HTTP请求配置
IG.HttpWrapper.setConfig(httpConfig);

其中，HTTP配置HttpWrapperConfig定义如下：

/**
 * Http请求配置
 */
export class HttpWrapperConfig extends HttpConfig {
    //请求基地址
    public baseUrl?: string;
    //客户端版本号
    public version?: string;
    //渠道标识
    public channel?: string;
    //签名前缀
    public signPrefix?: string;
    //AES加密秘钥
    public key?: string;
    //AES加密向量
    public iv?: string;
}

/**
 * Http请求配置
 */
export class HttpConfig {
    //请求超时时间（ms）
    public timeout: number = 5000;
}

发起请求

/**
* GET请求
* @param path 请求路径
* @param callback 请求回调
*/
get<T extends HttpResData>(path: string, callback?: HttpCallbackBean<T>): void;

/**
* POST请求
* @param path 请求路径
* @param params 请求参数
* @param callback 请求回调
*/
post<T extends HttpResData>(path: string, params?: object, callback?: HttpCallbackBean<T>): void;

/**
* 上传文件
* @param path 请求路径
* @param file 文件路径或文件（小程序里面传文件路径）
* @param fileName 上传文件名称
* @param params 请求参数（额外的 form data）
* @param callback 请求回调
*/
uploadFile<T extends HttpResData>(path: string, file: string | Blob, fileName: string, params?: Object, callback?: HttpCallbackBean<T>): void;


//构建回调
let callback = new IG.HttpCallbackBean<LoginResData>();
callback.onFail = (code: number, msg: string) => {
    console.error(`Http request fail: code=${code} , msg=${msg}`);
};
callback.onRes = (data: LoginResData) => {
    //缓存token
    IG.HttpWrapper.setToken(data.data.token);
}
//构建请求参数
let param = new LoginParam();
param.type = 1;
param.mobile = '13617678127';
param.code = '123454321';
//发起请求
new IG.HttpWrapper().post<LoginResData>('user/login', param, callback);

加解密模块

/**
* 加解密工具类
*/
export class CryptoUtil {
    /**
    * 设置配置（未设置时使用默认秘钥、向量）
    * @param key 秘钥
    * @param iv 向量
    */
    static setKey(key: string, iv?: string): void;
    
    /**
    * 获取秘钥
    * @param key 当前设置的秘钥
    * @returns  秘钥
    */
    private static getKey;
    
        
    /**
    * 获取向量
    * @param iv 当前设置的向量
    * @returns 向量
    */
    private static getIv;
    
    /**
    * MD5（32位小写）
    * @param data 需要MD5的数据
    * @returns MD5后的数据
    */
    static md5(data: string): any;
    
    /**
    * AES加密
    * @param data 需要AES加密的数据
    * @param key 秘钥（未设置时，使用默认秘钥）
    * @param iv 向量（未设置时，使用默认向量）
    * @returns AES加密后的数据
    */
    static aesEncrypty(data: string, key?: string, iv?: string): any;
    
    /**
    * AES解密
    * @param data 需要AES解密的数据
    * @param key 秘钥（未设置时，使用默认秘钥）
    * @param iv 向量（未设置时，使用默认向量）
    * @returns AES解密后的数据
    */
    static aesDecrypt(data: string, key?: string, iv?: string): any;
    
    /**
    * Base64加密
    * @param data 需要Base64加密的数据
    * @returns Base64加密后的数据
    */
    static base64Encrpty(data: string): any;
    
    /**
    * BASE64 解密
    * @param data 需要Base64解密的数据
    * @returns Base64解密后的数据
    */
    static base64Decrypt(data: string): any;
    
    /**
    * 生成符合UUID v4标准的唯一标识（优化版）
    */
    static uuid(): string;

}

缓存模块

/**
* 本地存储工具类
*/
export class StorageUtil {
    
    /**
    * 检查是否可以缓存
    * @param key 数据key
    */
    private static checkAvailable;
    
    /**
    * 缓存数据
    * @param key 数据key
    * @param data 数据
    */
    static setData(key: string, data: any): void;
    
    /**
    * 获取缓存数据
    * @param key 数据key
    * @returns 数据
    */
    static getData(key: string): string | null;
    
    /**
    * 安全缓存数据（数据会加密）
    * @param key 数据key
    * @param data 数据
    * @param encryptKey 加密秘钥（未设置时，使用默认秘钥）
    * @param encryptIv 加密向量（未设置时，使用默认向量）
    */
    static setDataSafely(key: string, data: any, encryptKey?: string, encryptIv?: string): void;
    
    /**
    * 获取缓存数据（数据会解密）
    * @param key 数据key
    * @param encryptKey 加密秘钥（未设置时，使用默认秘钥）
    * @param encryptIv 加密向量（未设置时，使用默认向量）
    * @returns 数据
    */
    static getDataSafely(key: string, encryptKey?: string, encryptIv?: string): string | null;

}