# Gaia SDK 集成文档

# 一、集成准备

# 1.修改默认参数

将压缩包中gaiares/params目录下json文件打开，不同渠道选择不同的json文件，将渠道广告参数配置到相应位置,如果网络或者服务器异常拉不到后台配置，就会启用默认参数，示例如下：

{
	"app": {
		"appKey": "4d347f232094330ada3c3ff769fde19b"   //游戏对应的appKey, 从“广告配置-H5游戏-添加游戏”后获取
	},
	"ad": {
		"adPos": [
			{
				"posId": "banner_pos",	//游戏中的广告位Id，从“广告配置-广告位管理-添加广告位”后获取  
				"ver": "v1",	//参数版本
				"showType": "banner",	//展示类型，对应后台“广告配置-广告位管理-展示类型”
				"adUnit": [	//广告单元，对应后台“广告配置-广告单元”
					{
						"unitId": "154874",	//渠道广告单元id，对应后台“广告配置-广告单元-广告位ID”
						"type": "banner",	//渠道广告格式，对应后台“广告配置-广告单元-填充类型”
						"weight": 2	//展示权重，值越大优先级越高，对应后台“广告配置-广告单元-权重”
					},
					{
						"unitId": "154875",
						"type": "native",
						"weight": 1
					}
				]
			},
			{
				"posId": "inter_pos",
				"ver": "v1",
				"showType": "inter",
				"adUnit": [
					{
						"unitId": "820e000ac5c744e4945951da8649156a",
						"type": "inter",
						"weight": 2
					},
					{
						"unitId": "154875",
						"type": "native",
						"weight": 1
					}
				]
			},
			{
				"posId": "video_pos",
				"ver": "v1",
				"showType": "video",
				"adUnit": [
					{
						"unitId": "154876",
						"type": "video",
						"weight": 1
					}
				]
			},
			{
				"posId": "native_pos",
				"ver": "v1",
				"showType": "native",
				"adUnit": [
					{
						"unitId": "154875",
						"type": "native",
						"weight": 1
					}
				]
			}
		]
	}
}

说明：json文件的命名是根据渠道名称，目前支持的渠道命名方式如下所示：

渠道名称	json文件名称
oppo	params_oppo
vivo	params_vivo

# 2.引擎配置

# 2.1 CocosCreator引擎

# 2.1.1 导入SDK

引入GaiaSdk.d.ts文件

将压缩包内libs目录里的GaiaSdk.d.ts文件放在工程下与creator.d.ts同级的目录。

引入GaiaSdk.mini.js文件

将压缩包内libs目录里的GaiaSdk.mini.js复制到引擎工程的assets目录内存放脚本的目录，一般为Script目录，并按以下步骤将其导入为插件。
引擎内选中GaiaSdk.mini.js文件--->右上角属性检查其中勾选“导入为插件”--->点击应用即可

# 2.1.2 导入SDK所需要的资源

将压缩包内gaiares目录复制到引擎工程的assets/resource目录下即可。

# 2.2 Laya引擎

# 2.2.1 导入SDK

引入gaia-laya.d.ts文件

将压缩包内libs目录里的gaia-laya.d.ts文件放在工程下与LayaAir.d.ts同级的目录。

引入gaia-laya.mini.js文件

将压缩包内libs目录里的gaia-laya.min.js复制到引擎工程的bin/libs目录，并在bin目录里的index.js文件添加以下代码：

	
	loadLib("libs/laya.ui.js")//sdk依赖库，必须添加
	loadLib("libs/gaia-laya.min.js")

# 2.1.2 导入SDK所需要的资源

将压缩包内gaiares目录复制到引擎工程的bin/res目录下即可。

# 二、接口调用

# 1.初始化

在第一个场景的start()生命周期函数中调用初始化接口。

callback为初始化回调，true为初始化成功，false为初始化失败。

	 GaiaSdk.GaiaAd.getInstance().init(callback);

# 2.检查广告

通过检查广告接口可以判断广告是否加载成功，此接口只会对原生和激励视频广告生效。

posId为广告位Id；
callback为回调，返回true表示已经有广告准备好，false表示广告加载失败。

	GaiaSdk.GaiaAd.getInstance().checkAd("inter_pos", (state) => {
            console.log("==========checkNative", state);
    });

# 3.展示广告

展示广告接口以下两个，开发这根据需求选择合适的接口进行展示广告。

# 3.1 无需指定展示位置和大小的广告

此接口适用于横幅广告、激励视频、插屏广告。

posId为广告位Id；
callback为结束后的回调，err为异常信息，type为展示的广告类型，state为激励视频发奖标识，true可发奖，否则不能发奖。

展示激励视频示例

    GaiaSdk.GaiaAd.getInstance().showAd("video_pos", (err,type,state) => {
            if(err){
            	//展示广告异常
                console.log("show video_pos error:", err);
                return;
            }
            if(state){
            	//广告播放完成，可以发放奖励
                console.log("can reward :" + state);
            }else{
            	//中途退出广告，不能发放奖励
            }
            console.log("show video_pos success  type:", type);           
            
        });

展示其他广告示例

    GaiaSdk.GaiaAd.getInstance().showAd("banner_pos", (err,type) => {
            if(err){
            	//展示广告异常
                console.log("show banner_pos error:", err);
                return;
            }
          	//广告展示成功
            console.log("show banner_pos success  type:", type);           
            
        });

# 3.2 指定展示位置和大小的广告

此接口适用于OPPO原生广告。

	
	GaiaSdk.GaiaAd.getInstance().showAdWithPosit(posId, param, callback);

param参数说明:

属性名称	属性类型	属性说明
w	number	原生宽度
h	number	原生高度
x	number	原生x坐标
y	number	原生y坐标

# 4.隐藏广告

此接口适用于原生和banner广告，参数传广告位ID即可。

	GaiaSdk.GaiaAd.getInstance().hideAd(posId);

# 5.检查是否能够添加桌面图标接口

callback为结束后的回调，true为可以添加，false为不能添加。

GaiaSdk.GaiaAd.getInstance().checkDeskTop(callback);

# 6. 添加桌面图标接口

callback为结束后的回调，true为添加成功，false为添加失败。

GaiaSdk.GaiaAd.getInstance().addDeskTop(callback);

# 三、其他

# 1.目前SDK支持渠道的广告类型

渠道	banner	原生广告	原生插屏	原生banner	插屏广告	激励视频	开屏广告
oppo	支持	支持	/	支持	/	支持	支持 (无需技术接入，oppo后台申请广告位即可)
vivo	支持	/	支持	支持	支持	支持	/

# 2. 测试

测试时根据oppo (opens new window)、vivo (opens new window)的官方文档安装相应的调试器调试rpk包，调试过程中可以参考SDK日志进行排查SDK接入情况，SDK的日志TAG过滤"GAIA"。

初始化关键日志

	GAIA sdk version:v1.0.0		//SDK版本
	GAIA [initAd]				//调用初始化接口
	GAIA init success!			//初始化成功

广告关键日志

以激励视频为例：

	GAIA [loadVideo]					//请求激励视频广告
	GAIA video ad load success			//激励视频请求成功
	GAIA video Id is null				//激励视频广告单元id为空，没有配置广告单元id
	GAIA [showAd] video_pos				//调用展示广告接口，video_pos为调用展示接口传入的广告位Id
	GAIA show raward video success		//激励视频展示成功
	GAIA reward vedio play complete		//激励视频播放完成并关闭广告

← H5游戏接入指南 Home →