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

青瓷看世界2024-11-05 13:12

场景介绍

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

接口说明

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

开发步骤

  1. 获取OAID。

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

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

    说明

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

  2. 请求单广告位广告。

    需要先创建一个AdLoader对象，通过AdLoader的loadAd方法请求广告，最后通过AdLoadListener，来监听广告的加载状态。
    请求广告关键参数如下所示：

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

    示例代码如下所示：

    复制代码
    1. import { advertising, identifier } from '@kit.AdsKit';
    2. import { common } from '@kit.AbilityKit';
    3. import { hilog } from '@kit.PerformanceAnalysisKit';
    4. import { BusinessError } from '@kit.BasicServicesKit';
    6. @Entry
    7. @Component
    8. struct Index {
    9. private ads: Array<advertising.Advertisement> = \[\];
    10. private context = getContext(this) as common.UIAbilityContext;
    11. private oaid: string = '';
    13. aboutToAppear() {
    14. try {
    15. // 使用Promise回调方式获取OAID
    16. identifier.getOAID().then((data: string) => {
    17. this.oaid = data;
    18. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in getting adsIdentifierInfo by promise');
    19. }).catch((error: BusinessError) => {
    20. hilog.error(0x0000, 'testTag', '%{public}s', `Failed to get adsIdentifierInfo, message: ${error.message}`);
    21. })
    22. } catch (error) {
    23. hilog.error(0x0000, 'testTag', '%{public}s', `Catch err, code: {error.code}, message: {error.message}`);
    24. }
    25. }
    27. build() {
    28. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
    29. Row() {
    30. Button('requestAd').onClick(() => {
    31. let load: advertising.AdLoader = new advertising.AdLoader(this.context);
    32. this.requestAd(load);
    33. }).width('45%')
    34. }
    35. }
    36. }
    38. private requestAd(adLoader: advertising.AdLoader): void {
    39. const adRequestParam: advertising.AdRequestParams = {
    40. // 广告类型：激励广告
    41. adType: 7,
    42. // 'testx9dtjwj8hp'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
    43. adId: 'testx9dtjwj8hp',
    44. // 开放匿名设备标识符
    45. oaid: this.oaid
    46. };
    47. const adOption: advertising.AdOptions = {
    48. // 设置是否请求非个性化广告
    49. nonPersonalizedAd: 0,
    50. // 是否允许流量下载0：不允许，1：允许，不设置以广告主设置为准
    51. allowMobileTraffic: 0,
    52. // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望
    53. tagForChildProtection: -1,
    54. // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望
    55. tagForUnderAgeOfPromise: -1,
    56. // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众
    57. adContentClassification: 'A'
    58. };
    59. const adLoaderListener: advertising.AdLoadListener = {
    60. onAdLoadFailure: (errorCode: number, errorMsg: string) => {
    61. hilog.error(0x0000, 'testTag', '%{public}s',
    62. `Failed to request ad, message: {errorMsg}, error code: {errorCode}`);
    63. },
    64. onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
    65. hilog.info(0x0000, 'testTag', '%{public}s', `Succeeded in requesting ad`);
    66. this.ads.push(...ads);
    67. },
    68. };
    69. adLoader.loadAd(adRequestParam, adOption, adLoaderListener);
    70. }
    71. }

  3. 事件订阅。

    开发者需要在App中订阅com.huawei.hms.pps.action.PPS_REWARD_STATUS_CHANGED事件来监听激励广告页面变化并接收奖励信息。示例代码中的订阅方法registerPPSReceiver()需要在每次展示广告前调用 。

    在订阅到公共事件后，可以从CommonEventData的parameters参数中使用"reward_ad_status"作为key值获取激励广告页面变化状态，使用"reward_ad_data"作为key值获取奖励信息，属性rewardType用来获取奖励物品的名称，rewardAmount用来获取奖励物品的数量。

    示例代码如下所示：

    复制代码
    1. import { commonEventManager, BusinessError } from '@kit.BasicServicesKit';
    2. import { hilog } from '@kit.PerformanceAnalysisKit';
    4. const KEY_REWARD_DATA = "reward_ad_data";
    5. const KEY_REWARD_STATUS = "reward_ad_status";
    7. export class RewardAdStatusHandler {
    8. // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
    9. private subscriber: commonEventManager.CommonEventSubscriber | null = null;
    11. // 订阅方法，需要在每次展示广告前调用
    12. public registerPPSReceiver(): void {
    13. if (this.subscriber) {
    14. this.unRegisterPPSReceiver();
    15. }
    16. // 订阅者信息
    17. const subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
    18. events: 'com.huawei.hms.pps.action.PPS_REWARD_STATUS_CHANGED',
    19. // publisherBundleName被设置为"com.huawei.hms.adsservice",这意味着只有来自该包名的事件才会被订阅者接受和处理。
    20. // 如果没有明确声明publisherBundleName，那么订阅者可能会收到来自其它包名的伪造事件，从而导致安全性问题或误导。
    21. publisherBundleName: 'com.huawei.hms.adsservice'
    22. };
    23. // 创建订阅者回调
    24. commonEventManager.createSubscriber(subscribeInfo, (err: BusinessError, commonEventSubscriber:
    25. commonEventManager.CommonEventSubscriber) => {
    26. if (err) {
    27. hilog.error(0x0000, 'testTag', '%{public}s',
    28. `createSubscriber error, code: {err.code}, message: {err.message}`);
    29. return;
    30. }
    31. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in creating subscriber');
    32. this.subscriber = commonEventSubscriber;
    33. // 订阅公共事件回调
    34. if (!this.subscriber) {
    35. hilog.warn(0x0000, 'testTag', '%{public}s', 'Need create subscriber');
    36. return;
    37. }
    38. commonEventManager.subscribe(this.subscriber, (err: BusinessError, commonEventSubscriber:
    39. commonEventManager.CommonEventData) => {
    40. if (err) {
    41. hilog.error(0x0000, 'testTag', '%{public}s', `Subscribe error, code: {err.code}, message: {err.message}`);
    42. } else {
    43. hilog.info(0x0000, 'testTag', '%{public}s', 'Subscribe data');
    44. const status: string = commonEventSubscriber?.parameters?.KEY_REWARD_STATUS;
    45. switch (status) {
    46. case AdStatus.AD_OPEN:
    47. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdOpen');
    48. break;
    49. case AdStatus.AD_CLICKED:
    50. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdClick');
    51. break;
    52. case AdStatus.AD_CLOSED:
    53. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdClose');
    54. this.unRegisterPPSReceiver();
    55. break;
    56. case AdStatus.AD_REWARDED:
    57. const rewardData: Record<string, string | number> = commonEventSubscriber?.parameters?.KEY_REWARD_DATA;
    58. const rewardType: string = rewardData?.rewardType as string;
    59. const rewardAmount: number = rewardData?.rewardAmount as number;
    60. hilog.info(0x0000, 'testTag', '%{public}s',
    61. `onAdReward, rewardType: {rewardType}, rewardAmount: {rewardAmount}`);
    62. break;
    63. case AdStatus.AD_VIDEO_START:
    64. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdVideoStart');
    65. break;
    66. case AdStatus.AD_COMPLETED:
    67. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdCompleted');
    68. break;
    69. default:
    70. break;
    71. }
    72. }
    73. });
    74. });
    75. }
    77. // 取消订阅
    78. public unRegisterPPSReceiver(): void {
    79. commonEventManager.unsubscribe(this.subscriber, (err: BusinessError) => {
    80. if (err) {
    81. hilog.error(0x0000, 'testTag', '%{public}s', `Unsubscribe error, code: {err.code}, message: {err.message}`);
    82. } else {
    83. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in unsubscribing');
    84. this.subscriber = null;
    85. }
    86. });
    87. }
    88. }
    90. enum AdStatus {
    91. AD_OPEN = 'onAdOpen',
    92. AD_CLICKED = 'onAdClick',
    93. AD_CLOSED = 'onAdClose',
    94. AD_REWARDED = 'onAdReward',
    95. AD_VIDEO_START = 'onVideoPlayBegin',
    96. AD_COMPLETED = 'onVideoPlayEnd'
    97. }

  4. 展示广告。

    ads为步骤2请求到的广告信息，调用showAd方法来展示广告。示例代码如下所示：

    复制代码
    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. };
    15. build() {
    16. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
    17. Row() {
    18. Button('showAd').onClick(() => {
    19. this.showAd();
    20. }).width('45%')
    21. }
    22. }
    23. }
    25. private showAd() {
    26. let load: advertising.AdLoader = new advertising.AdLoader(this.context);
    27. // 此处ads0表示请求到的第一个广告，用户根据实际情况选择
    28. advertising.showAd(this.ads0, this.displayOptions, this.context);
    29. }
    30. }

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

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

奖励用户

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

校验服务端验证回调

说明

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

  1. 设置激励广告的奖励配置。 您在鲸鸿动能媒体服务平台上申请激励视频广告位时选择"媒体管理（点击媒体名）> 新增展示位 > 选择激励视频（点击下一步，进入编辑页面）"，设置奖励类型和奖励数量，并点击"高级设置"，设置服务器端验证的URL。如下图：

  2. （可选）设置自定义数据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. // 此处ads0表示请求到的第一个广告，用户根据实际情况选择
    32. advertising.showAd(this.ads0, this.displayOptions, this.context);
    33. }
    34. }

    说明

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

  3. 获取要验证的内容。 用户观看完激励广告时，鲸鸿动能平台服务端会把需要验证的参数以及keyId和sign传给媒体提供的URL：https://www.example.com/feedback（[即步骤1中配置的验证URL](https://developer.huawei.com/consumer/cn/doc/#li5211654185420 "即步骤1中配置的验证URL")）。请求体样例：

    复制代码
    1. {
    2. "adId" : "testx9dtjwj8hp",
    3. "data" : "CUSTOM_DATA",
    4. "keyId" : "12345678",
    5. "rewardAmount" : "10",
    6. "rewardName" : "金币",
    7. "sign" : "OA33u6mypnhE4hbmF32N/ibYi1uXt72nDDyYMwjDI6JXVVFKePZYo4F7Fuk2MaG......",
    8. "uniqueId" : "3361626337333932313435313430373438383561376265636130393939313166",
    9. "userId" : "1234567"
    10. }

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

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

  4. 组装验证参数 验证内容（除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"));

  5. 获取公钥列表。 a. 在鲸鸿动能媒体服务平台上查看对应的帐户信息时选择"账户"。

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

    b. 您根据应用分发区域不同，需要使用对应站点的接口URL去获取公钥列表，不同站点对应的接口URL如下所示：

    将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 是 公钥

  6. 执行验证。 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. }
相关推荐
Flutter_OH8 小时前
Flutter OHOS 三方库与插件适配相关问题
harmonyos
Flutter_OH9 小时前
Flutter OHOS ohos应用编译相关问题
harmonyos
马剑威（威哥爱编程）12 小时前
【共创稿事节】HarmonyOS 7 Agent 开发实战 01：云端大模型 API 接入底座
华为·harmonyos
万物智能信息科技13 小时前
人体感应芯片PIR模块驱动开发—【万物智能之开源鸿蒙OpenHarmony系统实战开发系列教程】
驱动开发·嵌入式硬件·华为·开源·harmonyos
m0_7381858214 小时前
Flutter 鸿蒙化实战：sqflite 适配 OpenHarmony，本地 SQLite 数据库
flutter·华为·harmonyos·鸿蒙
马剑威（威哥爱编程）15 小时前
【共创稿事节】HarmonyOS 7 Agent 开发实战 02：Agent 工程脚手架与对话 UI 骨架
华为·harmonyos
打工仔折腾 AI16 小时前
鸿蒙平板远控电脑实测：ToDesk蓝牙键鼠、双模式鼠标与跨端剪贴板落地记录
人工智能·后端·python·性能优化·计算机外设·电脑·harmonyos
打工仔折腾 AI17 小时前
鸿蒙端ToDesk远控电脑实测：蓝牙键鼠、双模式鼠标与跨端剪贴板实践
后端·python·性能优化·计算机外设·电脑·harmonyos·ai agent 实战
OH_TPC17 小时前
【鸿蒙优选三方库】@ohos/axios：前端转鸿蒙，网络层几乎不用改
前端·华为·harmonyos·鸿蒙
m0_7381858217 小时前
Flutter 鸿蒙化实战：simple_circular_progress_bar 适配 OpenHarmony，环形进度条
flutter·华为·harmonyos·鸿蒙
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02历年考研数学一、数学二、数学三真题试卷及答案PDF03GitHub 镜像站点04「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会05如何新建文件夹？ 电脑新建文件夹的4种方法06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）08Telegram APK 下载安装完整指南 — 2026年最新09轻量化AI渗透武器库｜ARTEX自主攻防系统、资产梳理、漏洞挖掘、链路分析全流程智能化落地10微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新