App 弹窗是 GMP ReachSDK 提供的弹窗触达功能。

1. 配置应用鉴权信息

需提供 鸿蒙 应用包名和应用签名然后在 GMP 后台配置(管理中心-消息管理-客户端SDK-鉴权配置)，需保证与 app 的实际信息一致，可联系您的客户端开发人员获取。该项配置用于接口的安全鉴权校验，不会用于其他用途。
示例如下：

# 鸿蒙包名
com.example.gmpdemo
# 获取鸿蒙应用签名 SHA256 fingerprint
6918672280841579539

然后到GMP后台配置相关信息

2. 集成 SDK

2.1 集成 Finder SDK

弹窗 SDK 依赖 Finder SDK 进行数据回流，在使用弹窗 SDK 前，请确保已经集成了 Finder SDK。
Finder HarmonyOS Next SDK接入指南

2.2 集成弹窗 SDK

引入SDK（oh-package.json5）

"dependencies": {  
  ...    
  "@volcengine/gmp_popup": "0.0.1-alpha.4"  
}

3. 初始化 SDK

3.1 获取初始化必备id

3.1.1 获取项目id和应用id

在gmp首页，点击右上角头像-项目管理，即可进入项目后台页查看对应项目的项目id和应用id（项目id是初始化弹窗sdk的appid，应用id是用于初始化Finder SDK的appid）

3.1.2 获取主账号id（Saas版本）

进入火山引擎控制台，点击右上角头像 icon，红框中的账号 ID 即是 主账号id

3.1.3 获取弹窗应用id

在GMP首页，选择管理中心-通道管理-App弹窗-应用管理即可打开弹窗应用列表，最左侧一栏为弹窗应用id，将所选应用的弹窗应用id传入sdk初始化即可

3.1.4 获取弹窗应用id uuidType和deviceIdType

GMP 会根据 uuid 和 uuid type 对用户进行人群圈选，所以需要确保 SDK 中使用正确的 uuid 和 uuid type 。建议使用客户自有体系的用户 id 作为 uuid，并且 CDP ID 图谱中找到该 id 对应的 ID Code 作为 uuid type。若要使用匿名用户弹窗功能，则需要获取deviceId type。
可以在 CDP 中，进入“数据融合-ID 图谱构建”界面中查看当前项目中的所有id type


device_id_type

3.2 初始化

3.2.1 初始化

首先您需要初始化 Finder SDK，具体可参考：Finder HarmonyOS Next SDK初始化，再初始化弹窗 SDK

export default class MyAbilityStage extends AbilityStage {
  static appLog = new AppLog()
  
  onCreate() {
      //初始化Finder
      MyAbilityStage.appLog.init(this.context, finderInitConfig)
      MyAbilityStage.appLog.user()?.setUserUniqueID(UUID, UUID_TYPE)
      MyAbilityStage.appLog.start()
      
      //GMP项目配置
      const reachConfig: ReachConfig = {
        appLog: MyAbilityStage.appLog,
        appId: "your appid",
        appConfig: {
          host: "your host"
        },
        mainAccountId: MAIN_ACCOUNT_ID,
        uniqueUid: UUID,
        uniqueUidType: UUID_TYPE,
        deviceIdType: DEVICE_ID_TYPE
      }
      
      //资源位配置
      const popupConfig = new PopupConfig("POPUP_APP_ID", reachConfig)
      
      //初始化弹窗SDK    
      GMPPopupSDK.init(this.context, popupConfig)
    }
  }
}

3.2.2 参数说明

• ReachConfig 详细配置如下

• PopupConfig详细配置如下

pollingInterval

number

否

logEnabled

customLogger

IGMPLogger

3.3 更新用户画像

如您的产品中有账户体系，请在用户登录后立即设置 uuid，以保证用户登录前后口径一致性。Finder SDK 登陆态变化可参考：Finder SDK 登陆态变化
除此之外，您还需要及时通知弹窗SDK用户画像的变化
用户登录

GMPPopupSDK.updateUUID("your_uuid", "your_uuid_type")
appLog.user()?.setUserUniqueID("your_uuid", "your_uuid_type")

退出登录

GMPPopupSDK.updateUUID(null, null)
appLog.user()?.setUserUniqueID(null, null)

3.4 弹窗状态监听

弹窗 SDK 提供了弹窗状态的回调监听，接入方可以通过该回调监听弹窗弹出/关闭/弹窗按钮点击行为，并且可以拦截对应的点击事件

3.4.1 设置弹窗状态监听

GMPPopupSDK.setPopupWindowStatusListener({
  popupWindowShouldShow: (): boolean => {
      //弹窗是否允许展示 true 允许展示，false 不允许展示。可以在这里按需加自己的判断逻辑
      return true
  },
  onPopupWindowShow: (closeAction: () => void): void => {
    //弹窗展示回调
  },
  onPopupWindowDismiss: (): void => {
   //弹窗关闭回调
  },
  onPopupWindowClick: (url: string): void => {
    //弹窗中配置了跳转链接的按钮/图片被点击且拦截了弹窗的点击事件时回调
    //只有当 interceptPopupWindowClick 返回为 true 时回调
    //@param url 点击的跳转链接
  },
  interceptPopupWindowClick: (url: string): Boolean => {
    //是否拦截弹窗的点击事件 true代表拦截（自行处理跳转逻辑），
    //为false则会由sdk启动内嵌h5页处理跳转逻辑(必须是http开头的链接)
    //@param url 点击的跳转链接
    return false
  },
  popupWindowShowJudgeFromClient: (json: Record<string, Any>,
    callback: ClientRuleStrategyCallback): void => {
    // 弹窗前解析自定义规则,配置了自定义规则才会回调到这个接口(适用于需要通过配置参数判断是否需要弹窗的场景)
    // @param json 透传json 可能为null
    // @param callback 可以弹窗回调true，否则回调false。
    this.clientPopupWindowJSON = JSON.stringify(json)
    callback.showPopupWindow(true)
  }
})

3.4.2 移除弹窗状态监听

SDK内部会持有该listener的强引用，因此在不需要用到的时候请及时移除它

GMPPopupSDK.removePopupWindowStatusListener()

4. 其他可选配置

4.1 弹窗预览

点击预览弹窗后，接入方可以通过扫一扫获取到弹窗的id，将其传入SDK的预览弹窗接口，可以在调用预览接口的页面立刻弹出对应弹窗，调用SDK预览接口示例如下

GMPPopupSDK.previewPopupWindow("windowId")

在gmp平台管理中心-通道管理-app弹窗，找到需要预览的弹窗扫码即可获取到对应弹窗的windowId

4.2 启用/禁用弹窗

在某些沉浸式场景(如视频播放)或已弹窗场景可以禁止弹窗SDK的弹窗以避免对用户的体验带来干扰（关闭后需要在允许弹窗的场景再次调用来重新启用弹窗功能）

//false 禁用 true 启用
GMPPopupSDK.enablePopup(false)

4.3 设置弹窗补偿

APP弹窗是事件触发型的通道,在客户端本地完成弹窗的触发,「app弹窗」的触发可能在以下场景下触发失败;
触发弹窗时命中勿扰配置;
触发弹窗时用户侧为弱网不境;触发弹窗时遭遇其他未知异常。
当前触发失败后本次触达任务就结束了,因此在触发弹窗时允许设置补偿机制使本次触发失败的弹窗任务在下一次事件触发时尝试进行弹窗。
设置弹窗补偿的示例代码如下

GMPPopupSDK.setCompensateEnable(true)

4.4 关闭正在显示的GMP弹窗

在某些场景下想关闭正在显示的GMP弹窗时，可通过以下方法进行关闭

GMPPopupSDK.closeShowingPopupWindow()

4.5 匿名用户弹窗

popupConfig.setAnonymousPopupEnabled(true)

//初始化的ReachConfig中必填deviceIdType
const reachConfig: ReachConfig = {
        ...
        deviceIdType: "your deviceIdType"
      }

5. 触发弹窗

5.1 配置弹窗任务

在GMP首页，选择用户触达-消息触达-新增触达任务，选择App弹窗通道并选择在 3.1.3 中获取的弹窗应用，配置任务对应的事件及筛选条件如下图所示

5.2 客户端上报事件

Finder

在app上使用finder sdk上报对应的事件及参数

appLog.event("eventName", params)

GMP弹窗SDK埋点说明文档