广告 AD DCloud 5+原生插件接入文档

概述

本文档描述了 DCloud 5+app 和 wap2app 开发者如何集成 AD 原生插件(后面简称为插件),通过集成插件展示广告创造收益。 插件提供了以下几种广告形式:SplashAd(开屏广告)、RewardVideoAd(激励视频广告)、BannerAd(横幅广告)、InterstitialAd(插屏广告)等。

术语介绍

AppId:应用 id,18位 hex 字符串。【注意】调试时请使用测试 appId:ba0063bfbc1a5ad878;外发版本请替换成正式 appId,否则不会产生收益。

UnitId:广告位 id,广告类型缩写后紧跟从1开始的编号,如开屏广告位 s1,激励视频广告位 rv1。一般情况下使用默认的广告位 id 即可,需要分配额外的广告位时,请联系客户经理。

AdId:广告 id,全局唯一,相同素材的广告每次请求也不会重复。所有广告回调返回的参数都包含广告 id。

UserId:用户 id,接入方定义的用户唯一标识,传入时可以哈希脱敏,主要用于排查问题。

插件集成

DCloud 5+app 和 wap2app 接入5+原生插件扩展原生能力,不支持云端打包,仅支持本地离线打包。(请参考 DCloud 官方文档 https://nativesupport.dcloud.net.cn/AppDocs/README

插件集成步骤如下:

  1. 将 adsdk.js 拷贝到项目中,并在需要调用广告的文件中引入此文件;

adsdk.js:

document.addEventListener("plusready", function() {
	plus.adSdk = {
		setUserId : function (userId) {
			return plus.bridge.execSync("AdSdk", "setUserId", [userId])
		},
		showRewardVideoAd : function (params, callback) {
			callbackId = plus.bridge.callbackId(callback, null)
			return plus.bridge.exec("AdSdk", "showRewardVideoAd", [callbackId, params.unitId])
		},
		loadBannerAd : function (params, callback) {
			callbackId = plus.bridge.callbackId(callback, null)
			return plus.bridge.exec("AdSdk", "loadBannerAd", [callbackId, params.unitId, params.margins])
		},
		showBannerAd : function (params, callback) {
			callbackId = plus.bridge.callbackId(callback, null)
			return plus.bridge.exec("AdSdk", "showBannerAd", [callbackId, params.unitId, params.layout, params.margins])
		},
		destroyBannerAd : function (params) {
		    return plus.bridge.execSync("AdSdk", "destroyBannerAd", [params.unitId])
		},
		showInterstitialAd : function (params, callback) {
			callbackId = plus.bridge.callbackId(callback, null)
			return plus.bridge.exec("AdSdk", "showInterstitialAd", [callbackId, params.unitId])
		}
	}
}, true)
  1. 前端页面接入广告;
  2. 打开 demo 提供的原生代码框架,拷贝 HBuilderX 生成的本地打包 App 资源,进行本地离线打包。

插件初始化

初始化已在原生代码中完成,请参考插件集成

登录时请设置 userId:

plus.adSdk.setUserId("uid")

退出登录请重置 userId:

plus.adSdk.setUserId(null)

开屏广告接入

开屏广告以 App 启动作为曝光时机,提供 5s 的可感知广告展示。用户可以点击广告跳转到目标页面;或者点击右上角的“跳过”按钮,跳转到 app 主页。

开屏广告已在原生代码中接入,请参考插件集成

激励视频广告接入

激励视频广告是指将短视频融入到 app 场景当中,用户观看完激励视频广告后可以得到一些应用内奖励。使用场景包括但不限于: 1、游戏等应用内观看视频广告获得游戏内金币等:用户必须观看完整视频才能获取奖励; 2、积分类应用接入。

调用以下代码展示激励视频广告:

plus.adSdk.showRewardVideoAd({
    unitId: "rv1"
}, function(result) {
    if (result.event == 'onAdLoad') {
	    console.log(`onAdLoad: id=${result.id}`)
	} else if (result.event == 'onVideoCached') {
		console.log(`onVideoCached: id=${result.id}`)
	} else if (result.event == 'onAdShow') {
		console.log(`onAdShow: id=${result.id}`)
	} else if (result.event == 'onReward') {
		console.log(`onReward: id=${result.id}`)
	} else if (result.event == 'onAdClick') {
		console.log(`onAdClick: id=${result.id}`)
	} else if (result.event == 'onVideoComplete') {
		console.log(`onVideoComplete: id=${result.id}`)
	} else if (result.event == 'onAdClose') {
		console.log(`onAdClose: id=${result.id}`)
	} else if (result.event == 'onError') {
		console.log(`onError: id=${result.id}, code=${result.code}, message=${result.message}`)
	}
})

回调事件:

event desc
onAdLoad 广告加载成功
onVideoCached 视频素材缓存成功
onAdShow 广告页面展示
onReward 广告激励发放
onAdClick 广告被点击
onVideoComplete 广告播放完毕
onAdClose 广告被关闭
onError 广告出错,错误详情请查看 code 和 message

横幅广告接入

Banner 广告(横幅广告)位于 app 顶部、中部、底部任意一处,横向贯穿整个app页面;当用户与 app 互动时,Banner 广告会停留在屏幕上,并可在一段时间后自动刷新。

调用以下代码预加载 Banner 广告(可选):

plus.adSdk.loadBannerAd({
    unitId: "b1",
    margins: [0, 0, 0, 30] // [left, top, right, bottom]
}, function(result) {
    console.log(JSON.stringify(result))
})

调用以下代码展示 Banner 广告:

plus.adSdk.showBannerAd({
    unitId: "b1",
    layout: "bottom",
    margins: [0, 0, 0, 30] // [left, top, right, bottom]
}, function(result) {
    console.log(JSON.stringify(result))
})

回调事件:

event desc
onAdLoad 广告加载成功
onAdShow 广告页面展示
onAdClose 广告被关闭
onAdClick 广告被点击
onError 广告出错,错误详情请查看 code 和 message

调用以下代码销毁 Banner 广告:

plus.adSdk.destroyBannerAd({
    unitId: "b1"
})

插屏广告接入

插屏广告是移动广告的一种常见形式,在应用开流程中弹出,当应用展示插页式广告时,用户可以选择点击广告,访问其目标网址,也可以将其关闭,返回应用。

调用以下代码展示插屏广告:

plus.adSdk.showInterstitialAd({
    unitId: "i1"
}, function(result) {
    console.log(JSON.stringify(result))
})

回调事件:

event desc
onAdLoad 广告加载成功
onAdShow 广告页面展示
onAdClose 广告被关闭
onAdClick 广告被点击
onError 广告出错,错误详情请查看 code 和 message