# fs-adcomeon-component

微信小程序支付后广告组件

# 使用前准备


## 一. 申请发券插件使用权限

1. 小程序账号登录[微信公众平台](https://mp.weixin.qq.com/)
2. 设置 —> 第三方设置 -> 插件管理 —> 添加插件，进入添加插件操作页面
3. 搜索插件名 `微信支付券` 并添加, 提交审核待通过

## 二. 在小程序 app.json 文件中加入配置
```json
{
  "plugins": {
    "sendCoupon": { // 微信支付券
      "version": "2.0.1",
      "provider": "wxf3f436ba9bd4be7b"
    }
  }
}
```
## 三. 添加域名
1. 小程序账号登录[微信公众平台](https://mp.weixin.qq.com/)
2. 开发 —> 开发管理 —> 开发设置 —> 服务器域名
3. 在 `request合法域名` 中增加如下配置
```text
https://advertising.adcomeon.com
https://fshows-ecs-pro.cn-hangzhou.log.aliyuncs.com
```

# 使用方法
## 一. npm 安装, 参考 [小程序 npm 支持](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html)
```bash
npm install fs-adcomeon-component --save
```

## 二. 构建
1. 小程序开发者工具 -> 详情(工具右上角) -> 本地设置 -> 使用 npm 模块
2. 小程序开发者工具 -> 工具 -> 构建 npm
3. 构建成功后小程序代码包中将产出 "miniprogram_npm" 文件夹

## 三. 使用
### 方案一：在支付页接入组件

使用场景：支付页和支付结果页在同一页面下。
组件引入位置：支付页。
优势：对接在支付页，在支付页中加载组件时，广告进行预加载，能提升曝光率。

#### pageMode传入1，表示在支付页接入组件，在进入页面时就获取广告。

**接入步骤**

1. 页面的 json 文件中做如下配置
```json
{
  "usingComponents": {
    "fs-ad": "fs-adcomeon-component"
  }
}
```
2. 页面的 wxml文件
```html
<view wx:if="{{attachFsAd}}">
  <fs-ad
    id="fsAd"
    pageMode="{{1}}"
    flowMasterId="xxx"
    openId="xxx"
    extraInfo="{{extraInfo}}"
  ></fs-ad>
</view>
```
3. 页面的 js文件
```js
Page({
  data: {
    attachFsAd: false,
    extraInfo: {
      // 附加信息
      businessAddress: { // 当前消费地区
        provinceCode: '110000', // 省编码
        cityCode: '110100', // 市编码
        areaCode: '110101', // 区编码
        districtCode: '', // 街道编码
        address: '', // 详细地址
        latitude: '', // 纬度
        longitude: '' // 经度
      },
      storeInfo: { // 商户信息
        storeCategory: 'B0199', // 消费门店行业code
        storeName: '首展（良渚店）' // 消费门店名称
      },
      payTime: 1735660800, // 支付时间
      content: [{
        productCategory: '饮料', // 商品类目
        productName: '可口乐乐' // 商品名称
      }],
      amount: '100.00', // 支付金额
      payWay: 1, // 支付方式 1.微信 2.支付宝 3.云闪付 4.会员 5.其他
      payEnv: 2, // 支付环境 1.微信H5 2.微信小程序 3.支付宝生活号 4.支付宝小程序 5.APP 6.其他
      deviceInfo: { // 设备信息
        brand: 'HUAWEI', // 设备品牌
        model: 'Pura 70 Pro' // 设备型号
      },
      userId: '1234567890', // 用户id（微信就是openId，支付宝就是userid）
      flowMasterId: '1234567890' // 流量主id
    }
  },
  onLoad () {
    // 加载广告组件
    this.setData({
      attachFsAd: true,
    })
  },
  /**
   * @function 展示广告（在微信支付成功的回调时调用）
   * @desc wx.requestPayment的success中调用
   */
  handleOpenAd () {
    const fsAd = this.selectComponent('#fsAd')
    fsAd.showAd() // 展示广告
  },
  /**
   * @function 页面中的支付函数
   */
  handleWxPay () {
    wx.requestPayment({
      timeStamp: '',
      nonceStr: '',
      package: '',
      signType: 'MD5',
      paySign: '',
      success (res) {
        // 点击完成按钮
        this.handleOpenAd()
      },
      fail (res) { }
    })
  }
})
```

#### pageMode传入3，表示在支付页接入组件，必须在点击确认支付按钮时调用getAdData方法获取广告。

**接入步骤**

1. 页面的 json 文件中做如下配置
```json
{
  "usingComponents": {
    "fs-ad": "fs-adcomeon-component"
  }
}
```

2. 页面的 wxml文件
```html
<button bindtap="handleConfirmPay">确认支付</button>

<view wx:if="{{attachFsAd}}">
  <fs-ad
    id="fsAd"
    pageMode="{{3}}"
    flowMasterId="xxx"
    openId="xxx"
    extraInfo="{{extraInfo}}"
  ></fs-ad>
</view>
```

3. 页面的 js文件
```js
Page({
  data: {
    attachFsAd: false,
  },
  onLoad () {
    this.setData({
      attachFsAd: true,
    })
  },
  /**
   * @function 获取广告
   */
  getAdData () {
    const fsAd = this.selectComponent('#fsAd')
    fsAd.getAdData()
  },
  /**
   * @function 点击确认支付按钮
   */
  handleConfirmPay () {
    this.getAdData()
  },
  /**
   * @function 展示广告（在微信支付成功的回调时调用）
   * @desc wx.requestPayment的success中调用
   */
  handleOpenAd () {
    const fsAd = this.selectComponent('#fsAd')
    fsAd.showAd() // 展示广告
  },
  /**
   * @function 页面中的支付函数
   */
  handleWxPay () {
    wx.requestPayment({
      timeStamp: '',
      nonceStr: '',
      package: '',
      signType: 'MD5',
      paySign: '',
      success (res) {
        // 点击完成按钮
        this.handleOpenAd()
      },
      fail (res) { }
    })
  }
})
```

**注意事项**
- 如果必传参数openId是异步获取的，请通过wx:if，确保在获取openId、flowMasterId参数后再进行组件的一个显示，以防提示缺少必传参数
- pageMode必传


#### 方案二：在新开页（支付结果页）接入组件

使用场景：支付页和支付结果页是两个不同的页面。
组件引入位置：支付结果页。
劣势：对接在支付结果页即进入支付结果页的同时加载广告组件，无法提前渲染组件，流失率会比「方案一」高。

**接入步骤**
1. 页面的 json 文件中做如下配置
```json
{
  "usingComponents": {
    "fs-ad": "fs-adcomeon-component"
  }
}
```

2. 页面的 wxml文件

pageMode传入2，表示在新开页接入组件。

```html
<view wx:if="{{showFsAd}}">
  <fs-ad
    pageMode="{{2}}"
    flowMasterId="xxx"
    openId="xxx"
  ></fs-ad>
</view>
```

3. 页面的 js文件

**注意：showFsAd在data中的初始值应设置为false**

```js
Page({
  data: {
    showFsAd: false // showFsAd在data中的初始值应设置为false
  },
  onLoad () {
    // 显示广告
    this.setData({
      showFsAd: true
    })
  }
})
```


### 四. 组件参数说明

  | 变量 | 类型 | 必填 | 说明 |
  |:----|:----:|:----:|:----|
  | pageMode | Number | 是 | 获取广告时机-场景值： 1-预加载-进入页面获取广告  2-支付后新开页面获取广告 3-预加载-点击确认支付获取广告 |
  | openId | String | 是 | 用户openId |
  | flowMasterId | String | 是 | 流量主id，**联系运营人员提供** |
  | extraInfo | Obejct | 是 | 附加信息 |
  | ipAddress | String | 如需跑口令广告必传 | 顾客的真实ip |
  | ua | String | 如需跑口令广告必传 | 顾客浏览器的UA信息 |
  | orderId | String | 否 | 订单id，有则提供，没有可以不提供 |
  | haveNavBar | Boolean | 否 | 是否有微信顶部导航栏，默认为true, 默认有导航栏 |
  | payAmount | String | 否 | 实际支付金额 |

#### 支付成功确认推荐弹窗（新增类型）

广告接口 `creativeList[0]` 返回 `bgScheme: 5` 时展示带成功勾选图标、顶部提示、右上角取消推荐和底部确认按钮的新弹窗。原有 `bgScheme: 1～4` 保持原样；需要使用自定义弹窗时，`originalWindow` 应为 `false`。

半屏小程序广告的支付成功弹窗由接口返回的 `data.isShowDialog` 控制，组件内对应 `adInfo.isShowDialog`。`1` 表示显示，`2` 表示隐藏。返回 `2` 时，在 `originalWindow` 判断前直接调用 `handleCustomPaySuccessConfirm()` 并返回。字段未返回时，沿用原有弹窗逻辑。

所有配置继续复用素材中的现有字段，无需新增组件属性：

| 字段 | 新弹窗中的作用 |
|:----|:----|
| btnText / btnTextColor / btnBgColor | 确认按钮文字、文字颜色、背景色；背景色未配置时仍使用组件 `primaryColor` |
| btnTextFontSize / okFontWeight | 确认按钮字号（px）、字重 |
| payText / payTextColor / payTextFontSize | 中间的“支付成功”文字、颜色、字号（px） |
| payTextFontWeight | “支付成功”文字字重，Number 类型，默认 `500`；返回 `600` 或 `700` 可加粗，适用于所有自定义支付成功弹窗 |
| paySuccessIconUrl | `bgScheme: 5` 的成功图标图片地址，String 类型，按 `48 × 48px` 等比显示；未传、`null` 或空字符串时保留原绿色勾选图标 |
| titleText / titleTextColor / titleTextFontSize | 顶部提示文字、颜色、字号（px） |
| payModalBgColor / modalBgColor | 卡片背景色、遮罩背景色 |
| hasCancel | 是否展示右侧取消推荐；后端需返回 `true` 且 `cancelText` 非空才展示 |
| cancelText / cancelTextColor / cancelTextFontSize / cancelFontWeight | 右侧取消推荐文案、颜色、字号（px）、字重；文案由后端提供，传空字符串隐藏 |
| cancelAllowClick / cancelMinWidth / cancelLineHeight | 取消推荐是否可点击（`auto` / `none`）、最小点击宽度（px）、热区行高（px）；禁用时点击不会触发确认 |
| showCloseIcon | 是否展示左上角关闭图标，点击沿用取消逻辑，也受 `cancelAllowClick` 控制 |
| modalTips / modalTipsColor / modalTipsBgColor / modalTipsFontSize | 左上角“广告”标签文字、文字颜色、背景色、字号（px）；`modalTips` 传空字符串隐藏 |
| modalWidth / modalHeight / modalYPosition | 卡片宽度、高度、垂直偏移（px），沿用原默认值 `260`、`200`、`0`；窄屏自动限制最大宽度 |
| btnHot | 沿用现有热区规则：`false` 仅确认按钮触发广告，`true` 点击取消推荐以外区域也触发广告 |

新类型沿用原有默认值及空值回退规则，不单独设置默认文案或颜色；后端返回的有效配置应用到对应元素。可通过 `paySuccessIconUrl` 替换成功图标，未配置时显示原绿色勾选图标。

示例（广告素材字段）：

```js
{
  bgScheme: 5,
  originalWindow: false,
  btnText: '确认',
  btnTextColor: '#ffffff',
  btnBgColor: '#10ae65',
  payText: '支付成功',
  payTextColor: '#111111',
  payTextFontWeight: 500,
  paySuccessIconUrl: '', // 可配置为自定义成功图标的图片URL
  titleText: '领取外卖补贴金，可叠加使用',
  titleTextColor: '#999999',
  payModalBgColor: '#ffffff',
  modalBgColor: 'rgba(0,0,0,.5)',
  hasCancel: true,
  cancelText: '取消推荐',
  cancelTextColor: '#a6a3c3',
  cancelAllowClick: 'auto',
  btnHot: false
}
```

确认和取消沿用原有跳转、埋点及 `onCustomPaySuccessCancel` 事件。

extraInfo中的参数说明

  | 变量 | 类型 | 必填 | 说明 |
  |:----|:----:|:----:|:----|
  | businessAddress | Object | 否 | 当前消费地区 |
  | storeInfo | Object | 否 | 商户信息 |
  | payTime | Number | 否 | 支付时间 |
  | content | Array | 否 | 商品信息 goodsInfo[] |
  | amount | String | 否 | 支付金额 |
  | payWay | Number | 是 | 支付方式：1.微信 2.支付宝 3.云闪付 4.会员 5.其他 |
  | payEnv | Number | 是 | 支付环境：1.微信H5 2.微信小程序 3.支付宝生活号 4.支付宝小程序 5.APP 6.其他 |
  | deviceInfo | Object | 否 | 设备信息 |
  | userId | String | 是 | 用户id |
  | flowMasterId | String | 是 | 流量主id |

businessAddress中的参数说明

  | 变量 | 类型 | 必填 | 说明 |
  |:----|:----:|:----:|:----|
  | provinceCode | String | 否 | 省编码 |
  | cityCode | String | 否 | 市编码 |
  | areaCode | String | 否 | 区编码 |
  | districtCode | String | 否 | 街道编码 |
  | address | String | 否 | 详细地址 |
  | latitude | String | 否 | 纬度 |
  | longitude | String | 否 | 经度 |

storeInfo中的参数说明

  | 变量 | 类型 | 必填 | 说明 |
  |:----|:----:|:----:|:----|
  | storeCategory | String | 否 | 消费门店行业code |
  | storeName | String | 否 | 消费门店名称 |

deviceInfo中的参数说明

  | 变量 | 类型 | 必填 | 说明 |
  |:----|:----:|:----:|:----|
  | brand | String | 否 | 设备品牌 |
  | model | String | 否 | 设备型号 |

goodsInfo 中的参数说明

  | 变量 | 类型 | 必填 | 说明 |
  |:----|:----:|:----:|:----|
  | productCategory | String | 否 | 商品类目 |
  | productName | String | 否 | 商品名称 |


### 五. 组件方法说明


调用组件的getAdData方法获取广告（只在pageMode=3时使用）
```js
const fsAd = this.selectComponent('#fsAd')
fsAd.getAdData() // 获取广告
```

调用组件的showAd方法展示广告

```js
const fsAd = this.selectComponent('#fsAd')
fsAd.showAd() // 展示广告
```
