华为HarmonyOS打造开放、合规的广告生态

场景介绍

激励广告是一种全屏幕的视频广告，用户可以选择点击观看，以换取相应奖励。

接口说明

接口名	描述
loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void	请求单广告位广告，通过AdRequestParams、AdOptions进行广告请求参数设置，通过AdLoadListener监听广告请求回调。
showAd(ad: Advertisement, options: AdDisplayOptions, context?: common.UIAbilityContext): void	展示广告，通过AdDisplayOptions进行广告展示参数设置。

开发步骤

获取OAID。

如果想要为用户更精准的推送广告，可以在请求参数AdRequestParams中添加oaid属性。

如何获取OAID参见获取OAID信息。

说明

使用以下示例中提供的测试广告位必须先获取OAID信息。

请求单广告位广告。

需要先创建一个AdLoader对象，通过AdLoader的loadAd方法请求广告，最后通过AdLoadListener，来监听广告的加载状态。

请求广告关键参数如下所示：

请求广告参数名	类型	必填	说明
adType	number	是	请求广告类型，激励广告类型为7。
adId	string	是	广告位ID。如果仅调测广告，可使用测试广告位ID：testx9dtjwj8hp。如果要接入正式广告，则需要申请正式的广告位ID。可在应用发布前进入流量变现官网，点击“开始变现”，登录鲸鸿动能媒体服务平台进行申请，具体操作详情请参见展示位创建。
oaid	string	否	开放匿名设备标识符，用于精准推送广告。不填无法获取到个性化广告。

请求广告参数名

类型

必填

说明

adType

number

是

请求广告类型，激励广告类型为7。

adId

string

是

广告位ID。

如果仅调测广告，可使用测试广告位ID：testx9dtjwj8hp。
如果要接入正式广告，则需要申请正式的广告位ID。可在应用发布前进入流量变现官网，点击“开始变现”，登录鲸鸿动能媒体服务平台进行申请，具体操作详情请参见展示位创建。

oaid

string

否

开放匿名设备标识符，用于精准推送广告。不填无法获取到个性化广告。

示例代码如下所示：

import { advertising, identifier } from '@kit.AdsKit';
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
private ads: Array<advertising.Advertisement> = [];
private context = getContext(this) as common.UIAbilityContext;
private oaid: string = '';
aboutToAppear() {
try {
// 使用Promise回调方式获取OAID
identifier.getOAID().then((data: string) => {
this.oaid = data;
hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in getting adsIdentifierInfo by promise');
}).catch((error: BusinessError) => {
hilog.error(0x0000, 'testTag', '%{public}s', `Failed to get adsIdentifierInfo, message: ${error.message}`);
})
} catch (error) {
hilog.error(0x0000, 'testTag', '%{public}s', `Catch err, code: ${error.code}, message: ${error.message}`);
}
}
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Row() {
Button('requestAd').onClick(() => {
let load: advertising.AdLoader = new advertising.AdLoader(this.context);
this.requestAd(load);
}).width('45%')
}
}
}
private requestAd(adLoader: advertising.AdLoader): void {
const adRequestParam: advertising.AdRequestParams = {
// 广告类型：激励广告
adType: 7,
// 'testx9dtjwj8hp'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
adId: 'testx9dtjwj8hp',
// 开放匿名设备标识符
oaid: this.oaid
};
const adOption: advertising.AdOptions = {
// 设置是否请求非个性化广告
nonPersonalizedAd: 0,
// 是否允许流量下载0：不允许，1：允许，不设置以广告主设置为准
allowMobileTraffic: 0,
// 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望
tagForChildProtection: -1,
// 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望
tagForUnderAgeOfPromise: -1,
// 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众
adContentClassification: 'A'
};
const adLoaderListener: advertising.AdLoadListener = {
onAdLoadFailure: (errorCode: number, errorMsg: string) => {
hilog.error(0x0000, 'testTag', '%{public}s',
`Failed to request ad, message: ${errorMsg}, error code: ${errorCode}`);
},
onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
hilog.info(0x0000, 'testTag', '%{public}s', `Succeeded in requesting ad`);
this.ads.push(...ads);
},
};
adLoader.loadAd(adRequestParam, adOption, adLoaderListener);
}
}

校验激励广告服务端验证回调

服务端验证回调是指鲸鸿动能平台发送给媒体服务器的网址请求，其中带有特定的查询参数，用来通知媒体服务器某位用户因为与激励视频广告互动而应予以奖励，从而规避欺骗的行为。

奖励用户

在给用户发奖励时，要把握好用户体验和奖励验证之间的平衡。由于服务器端回调会存在延迟的情况，因此我们建议客户端立即奖励用户，同时在收到服务器端回调时对所有奖励进行验证。这种做法可确保奖励符合发放条件，同时提供良好的用户体验。
对于某些应用而言，奖励是否达到发放条件非常重要，用户可适当接受延迟。这时，推荐做法是等待服务器端回调完成验证，再向用户发放奖励。

校验服务端验证回调

说明

App上架至华为应用市场（AppGallery）时间超过12小时才可以收到回调。

设置激励广告的奖励配置。
您在鲸鸿动能媒体服务平台上申请激励视频广告位时选择“媒体管理（点击媒体名）> 新增展示位 > 选择激励视频（点击下一步，进入编辑页面）”，设置奖励类型和奖励数量，并点击“高级设置”，设置服务器端验证的URL。如下图：
（可选）设置自定义数据customData和userId。
ads为步骤2请求到的广告信息，调用showAd方法来展示广告。

您在App中展示激励广告之前设置自定义数据customData和userId。示例代码如下所示：
1. import { advertising } from '@kit.AdsKit';
2. import { common } from '@kit.AbilityKit';
4. @Entry
5. @Component
6. struct Index {
7. private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
8. // 步骤2中请求到的广告内容
9. private ads: Array<advertising.Advertisement> = [];
10. private displayOptions: advertising.AdDisplayOptions = {
11. // 激励广告视频播放是否静音
12. mute: true,
13. // 设置自定义数据
14. customData: 'CUSTOM_DATA',
15. // 设置自定义数据
16. userId: '1234567'
17. };
19. build() {
20. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
21. Row() {
22. Button('showAd').onClick(() => {
23. this.showAd();
24. }).width('45%')
25. }
26. }
27. }
29. private showAd() {
30. let load: advertising.AdLoader = new advertising.AdLoader(this.context);
31. // 此处ads[0]表示请求到的第一个广告，用户根据实际情况选择
32. advertising.showAd(this.ads[0], this.displayOptions, this.context);
33. }
34. }
说明

如果没有设置customData和userId，不影响发放奖励事件上报但是服务端验证的参数中没有这两个字段。如果设置customData和userId，必须在展示广告之前设置并且URLEncode之后，长度不超过1024个字符，否则影响服务端验证。

获取要验证的内容。

用户观看完激励广告时，鲸鸿动能平台服务端会把需要验证的参数以及keyId和sign传给媒体提供的URL：https://www.example.com/feedback（即步骤1中配置的验证URL）。请求体样例：

{
"adId" : "testx9dtjwj8hp",
"data" : "CUSTOM_DATA",
"keyId" : "12345678",
"rewardAmount" : "10",
"rewardName" : "金币",
"sign" : "OA33u6mypnhE4hbmF32N/ibYi1uXt72nDDyYMwjDI6JXVVFKePZYo4F7Fuk2MaG......",
"uniqueId" : "3361626337333932313435313430373438383561376265636130393939313166",
"userId" : "1234567"
}

服务器端验证回调查询参数说明：

参数名称	类型	是否必选	描述
adId	String	是	激励视频广告位ID
data	String	否	自定义数据字符串
keyId	String	是	验证回调的密钥
rewardAmount	String	否	奖励数量
rewardName	String	否	奖励奖品
sign	String	是	回调的签名
uniqueId	String	是	获奖事件生成的十六进制的标识符
userId	String	否	用户ID

组装验证参数
验证内容（除sign、keyId）格式顺序如下：

adId={adId}&data={data}&rewardAmount={rewardAmount}&rewardName={rewardName}&uniqueId={uniqueId}&userId={userId}

其中‘{}’里面表示参数的值，且参数顺序不能变。如果参数为null或者空字符串，则URL中不拼接该参数。然后用SHA256计算散列值，得到paramContentData。示例代码如下所示：
1. String adId = request.getParameter("adId");
2. String data = request.getParameter("data");
3. ...
4. String userId = request.getParameter("userId");
5. String param = "adId=" + adId + "&data=" + data + "&rewardAmount=" + rewardAmount + "&rewardName=" + rewardName + "&uniqueId=" + uniqueId + "&userId=" + userId;
6. String sha256Value = Sha256Util.digest(param);
7. byte[] paramContentData = sha256Value.getBytes(Charset.forName("UTF-8"));
获取公钥列表。
a. 在鲸鸿动能媒体服务平台上查看对应的帐户信息时选择“账户”。

通过点击上图所示的“获取密钥”按钮弹出如下所示的弹框，获取“开发者ID”和“密钥”。

b. 您根据应用分发区域不同，需要使用对应站点的接口URL去获取公钥列表，不同站点对应的接口URL如下所示：
- 中国：https://ppscrowd-drcn.op.hicloud.com/action-lib-track/publickeys
将body通过密钥进行HMAC-SHA256加密得到签名，替换到Authorization中，并设置“开发者ID”和Authorization到Header中。示例代码如下所示：
1. String data = "";
2. String url = "https://ppscrowd-dre.op.dbankcloud.com/action-lib-track/publickeys";
3. String authorization = "Digest validTime=\"{0}\", response=\"{1}\"";
4. // 开发者ID
5. String userId = "YOUR_PUBLISHER_ID";
6. // 密钥
7. String key = "YOUR_KEY";
9. HttpClient httpclient = HttpClients.createDefault();
10. HttpGet request = new HttpGet();
11. try {
12. // 将body通过密钥进行HMAC-SHA256加密得到签名，替换到Authorization中
13. String validTime = String.valueOf(System.currentTimeMillis());
14. String body = validTime + ":/publickeys";
15. byte[] keyBytes = Base64.decodeBase64(key);
16. byte[] bodyBytes = body.getBytes(Charsets.UTF_8);
18. Mac mac = Mac.getInstance("HmacSHA256");
19. SecretKey secretKey = new SecretKeySpec(keyBytes, "HmacSHA256");
20. mac.init(secretKey);
21. byte[] signatureBytes = mac.doFinal(bodyBytes);
23. String signature = (signatureBytes == null) ? null : Hex.encodeHexString(signatureBytes);
24. authorization = MessageFormat.format(authorization, validTime, signature);
25. // 设置开发者ID和Authorization到Header中
26. request.setURI(new URI(url));
27. request.setHeader("userId", userId);
28. request.setHeader("Authorization", authorization);
29. HttpResponse response = httpclient.execute(request);
30. data = EntityUtils.toString(response.getEntity());
31. } catch (Exception e) {
32. System.out.println(e.getMessage());
33. }
返回data消息体（publicKey已匿名化）：
1. {
2. "keys": [
3. {
4. "keyId":"12345678",
5. "publicKey":"LS0tLS1*******************************************************"
6. },
7. {
8. "keyId": "22345678",
9. "publicKey":"LS0tLS1*******************************************************"
10. }
11. ]
12. }
返回消息结构体：

参数名称

类型

是否必选

描述

keys

List<key>

是

返回公钥列表
- key结构体：
参数名称

类型

是否必选

描述

keyId

String

是

密钥ID

publicKey

String

是

公钥
执行验证。
a. 根据keyId从公钥列表中找到对应的base64编码后的publicKey。

b. 将paramContentData、publicKey、sign和SHA256withRSA数字签名算法的入参，执行验证。

示例代码如下所示：
1. public static boolean verify(byte[] data, String publicKey, String sign, String signatureAlgorithm) {
2. try {
3. byte[] keyBytes = base64Decode(publicKey);
4. X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);
5. KeyFactory keyFactory = KeyFactory.getInstance("RSA");
6. PublicKey publicK = keyFactory.generatePublic(keySpec);
7. Signature signature = Signature.getInstance(signatureAlgorithm);
8. signature.initVerify(publicK);
9. signature.update(data);
10. return signature.verify(base64Decode(sign));
11. } catch (InvalidKeyException | SignatureException | UnsupportedEncodingException | InvalidKeySpecException | NoSuchAlgorithmException e) {
12. return false;
13. }
14. }
16. private static byte[] base64Decode(String encoded) throws UnsupportedEncodingException {
17. return Base64.decodeBase64(encoded.getBytes("UTF-8"));
18. }